Creating And Deploying Org Mode Jekyll Site To Github Pages

We’ll go over how to create a Jekyll site using Org-mode and how to deploy it to Github Pages! I won’t go over styling and creating a nice Jekyll site, just building a bare bones basic one, and deploying to GitHub.

Folder Structure

First off, create a root directory, I’ll name it mysite. Now, once you have done that, mimic the following folder structure:

mysite/ # This is the folder you just created
├── assets
│   ├── css
│   ├── images
│   └── js
├── _includes
├── _layout
├── org
│   └── _posts
└── _posts

Ideally, we would want one folder for org files, and another for the Jekyll site. Unfortunately, the way GitHub is, it does not allow for this type of setup and only checks in the top directory for the files. The price we pay for free web hosting.

The folders _includes, _layouts, and assets are just for styling and templating. I won’t go into detail about this, since this post is just how to get your Jekyll site to GitHub.

Org-mode Hack

Next is updating some things in your init.el file. Just copy, paste then modify to meet your needs:

;; For jekyll
(setq org-publish-project-alist
    '(("org-mysite"
       ;; Path to your org files.
       :base-directory "path/to/proj/mysite/org"
       :base-extension "org"

       ;; Path to your Jekyll project.
       :publishing-directory "path/to/proj/mysite/"
       :recursive t
       :publishing-function org-publish-org-to-html
       :headline-levels 4
       :html-extension "html"
       :body-only t ;; Only export section between <body> </body>
       :table-of-contents nil)

      ("org-static-mysite"
       :base-directory "path/to/proj/mysite/org/"
       :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|php"
       :publishing-directory "path/to/proj/mysite/"
       :recursive t
       :publishing-function org-publish-attachment
       :table-of-contents nil)

      ("mysite" :components ("org-mysite" "org-static-mysite"))))

I got this bit from the org-mode site. I tweaked it a bit. Once you have done that, evaluate the statement, reload the file, or restart emacs to make the change take effect.

Creating Pages

Alright, we’re one step closer to finishing! Next, is creating the configuration file for Jekyll to use once we start its server. Create a file called _config.yml, and just paste this line inside: exclude: [org/]. Without this line, Jekyll will make the files in org directory visible to anyone, and we don’t want that. If you want to see all available options, check out Jekyll’s documentation.

Next step is to create the index.html file but since we’re using Org, we’ll call it index.org. Create the file inside the org directory and just put the following for now:

#+BEGIN_HTML
---
title: YOUR AWESOME TITLE HERE
---
#+END_HTML

* Hello World!

  This is the index page

The lines between the HTML tags are needed by Jekyll to be able to do whatever it needs to do. You would usually declare what layouts you want to use and other things in there. This is all we need to be able to test and run our new site!

Before we being testing and seeing our site locally, we must first convert our files to html. This is where the org hack comes in handy. Do C-c C-e while in index.org. You should see a plethora of menu options, ignore all of them and press X (uppercase), next enter mysite. You should see the mini buffer printing out some info. Once it’s done, we’ll move to the next section. The complete command would be C-c C-e X mysite

Running Your Site Locally

Okay, go to your terminal and go to your project root directory. Next, run jekyll serve. The server should start and tell you that it’s running on 127.0.0.1:4000. If you go there, you should see our simple little index file. There you go, Website completed! Not really, but you get the point.

Deploying to GitHub (Finally)

You are now ready to show off your site! First thing you need to do is create an empty repository (Don’t add a readme or anything) in github with the following format: USERNAME.github.io. My user name is gopar, so mine would be gopar.github.io. Once the repo is created, just copy and run these commands from the root directory of your project. In this case, our root directory is mysite.

echo "# USERNAME.github.io" >> README.md
echo "_site/" > .gitignore
git init
git add .
git commit -am "first commit"
git remote add origin https://github.com/USERNAME/USERNAME.github.io.git
git push -u origin master

If you now go to your browser and type USERNAME.github.io, you should see your new website! If you want to see an example repo of this, check out the emacs meetup I created. Hope this helps :)