I've been thinking about getting my own blog up for more than a while now, and finally made it happen! This is is my first post, and it will cover the basics steps I took to get this site up and running.
During my day-to-day work, I make heavy use of Emacs, Emacs Org-Mode, git and GitHub. So it only felt natural to also go and try to use those tools for my blogging adventure. And for the purpose of this post, I will assume a basic familiarity with those tools. After reviewing a few options on org-blog-wiki, I found a combination of Org-Mode and Jekyll to be the most promising route. And as it turns out, setting it up is indeed quite straightforward.
First, we need Jekyll and Ruby. If you're on a current Ubuntu, the following commands should do.
# install command on Ubuntu sudo apt -y install ruby ruby-dev build-essential # set up local ~/ruby-gems folder in .path gem install jekyll bundler jekyll-sitemap pygments.rb
Next, we need to set up the blog, populate it using a Jekyll template structure, and push it to GitHub. And at this point, we are already live!
cd ~/projects/communicate/blog git init git create thackl.github.io # use your own username here jekyll new --force . # otherwise complains about non-empty bundle exec jekyll serve # now it runs locally: http://localhost:4000/ sed -i '/_site/d' .gitignore # remove _site from .gitignore git add * git commit -am 'jekyll scaffold' git push -u origin master # we're live: https://thackl.github.io/
What is still missing, though, is a way to write blog posts in Org-Mode, and somehow convert them so they can be hosted by Jekyll. To achieve this, we will rely on Emacs publishing engine which offers conversion of .org pages to .html pages. There are different ways how to set the overall blog structure, depending on whether one wants to be able to write all pages, including the front page, about pages, etc. using org, or just the posts themselves.
For the sake of simplicity, I went with option two: I only write the actual posts in Org-Mode, but not any of the other content pages. To do this, we need two things:
A sub-directory to store the org-posts in
mkdir _org && cd _org
and a minimal configuration for the org-mode publishing system in our
~/.emacs, so the html exports end up at the right location.
(setq org-publish-project-alist '(("thackl.github.io" ;; my blog project (just a name) ;; Path to org files. :base-directory "~/projects/communicate/blog/_org" :base-extension "org" ;; Path to Jekyll Posts :publishing-directory "~/projects/communicate/blog/_posts/" :recursive t :publishing-function org-html-publish-to-html :headline-levels 4 :html-extension "html" :body-only t )))
Now, we are ready to write our first simple post. Start with opening a file at
YYYY-MM-DD with today's
date. Add a Jekyll-style Front Matter section with some required meta
--- layout: post title: "Using org-mode with Jekyll" excerpt: Introduce how to use Emacs's Org-mode with Jekyll to generate GitHub Pages ---
Then, add some content, aka this, and finally, run the Emacs publishing
C-c C-e P f to convert
Now check http://localhost:4000/ to see a local copy of your post (make sure
bundle exec jekyll serve is still running). If you like what you see, commit
and push the changes, so that they appear on your https://USERNAME.github.io/
site. Now it should look something like this: