Blogging with org-static-blog

• org-static-blog is a fantastic and very simple tool to maintain a static site blog from emacs orgmode.
• For me it was easier hosting the blog on a shared hosting platform (Uberspace) rather than using GitHub or Gitlab pages.
  • It's very simple to add a tls certificate to your blog when hosting it on an Uberspace.
  • I think it should work with all static site generators, not just with org-static-blog

A long long time ago I started to think about blogging. I think blogging is a nice way to provide solutions of problems. On the one hand it helps me to recall things in the future and on the other hand it might help others who have similar problems.

Being a nerd, I spent quite a lot of time thinking about my blogging system.

My requirements were:

• Keep it simple
• RSS feed
• TLS encryption
• No JavaScript
• Based on orgmode

There are lots of tools based on orgmode for blogging, but the one I like most is org-static-blog by my friend bastibe.

In this first blog entry I'll try to document the technical background about this blog.

This includes:

• Setting up org-static-blog
• Setting up an Uberspace for hosting a static blog
• My blogging workflow
• Future work

Org-static blog is a very simple static site generator by bastibe, written in emacs lisp.

It converts .org to .html files and creates an rss feed for you.

My configuration looks like this:

(add-to-list 'load-path "~/projects/blog/org-static-blog/")
(require 'org)
(require 'org-static-blog)

(setq org-static-blog-publish-title "zngguvnf.org")
(setq org-static-blog-publish-url "https://zngguvnf.org/")
(setq org-static-blog-publish-directory "~/projects/blog/html/")
(setq org-static-blog-posts-directory "~/projects/blog/html/posts/")
(setq org-static-blog-drafts-directory "~/projects/blog/html/drafts/")
(setq org-export-with-toc nil)
(setq org-export-with-section-numbers nil)
(setq org-static-blog-index-length 2)

Furthermore I modified org-static-blog-page-header, org-static-blog-page-preamble, org-static-blog-page-postamble.

To make this blog look more like an org document, I changed the date format and its position in org-static-blog-create-index, org-static-blog-create-archive, org-static-blog-post-template and used an .css file, inspired by Kelvin Hu who is the maintainer of org-page.

If you are interested in details just drop me a line.

Have a look at my blogging workflow to see org-static-blog in action.

Uberspace is a german shared hosting provider.

You can try it for a month, after that you can pay what you want (minimum 1 Euro/ month). For this you get ssh access to a server running CentOS and 10 GB storage, great documentation (german only) and awesome personal support via mail.

For hosting this blog I set up a new account.

After that I added my public ssh key and created an entry in my /.ssh/config file

Host zngguvnf
 HostName perseus.uberspace.de
 User zngguvnf

Now typing ssh zngguvnf in my shell is enough to login.

While I registered the domain zngguvnf.org I want this and www.zngguvnf.org to point to my Uberspace account.

To do this:

uberspace-add-domain -d zngguvnf.org -w

uberspace-add-domain -d www.zngguvnf.org -w

This code will return an A and AAA record. Now enter the A record at your domain provider and create a CNAME entry called www.yourdomain.org that points to yourdomain.org.

Using a free Let's encrypt TLS Cert is really easy on Uberspace.

To redirect http to https put the following in your .htaccess

RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteCond %{ENV:HTTPS} !=on
RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [R=301,L]

Now create a git bare repository on your Uberspace

git init --bare ~/blog.git

and add a post-receive hook vim ~/blog.git/hooks/post-receive

#!/bin/sh
WEB_DIR=~/blog

git --work-tree=${WEB_DIR} checkout HEAD --force -- html
rsync -r ~/blog/html/* ~/html

leave vim with :wq ;)

make this hook executable.

chmod +x ~/blog.git/hooks/post-receive

Now create an tmp folder

mkdir ~/blog

When you now push a commit to the bare repository it will checkout the folder ~/blog.git/html in the folder ~/blog/html and then publish it by copying the files to ~/html.

(I think it is not possible to do this with a gitcheckout, not using a tmp folder.)

Finally, create a .git repository on your local machine and add the remote.

git init ~/path/to/your/local/blog_dir
cd ~/path/to/your/local/blog_dir
# this folder should be a git repo
git remote add origin ssh://zngguvnf@perseus.uberspace.de/home/zngguvnf/blog.git
git push --set-upstream origin master

That's it. And this should work with all static site generators, not just with org-static-blog.

Let's write a post and publish it.

1.) Create file ~/projects/blog/html/posts/2017-07-06--hello-world.org

2.) Write your post (this must include #+title: and #+date:)

#+title: Hello World!
#+date: <2017-07-06 Thu>

Hello World!

3.) M-x org-static-blog-publish

4.) Publish your files

git add html/index.html html/rss.xml html/2017-07-06--hello-world.org

git commit -m "Blog post hello world"

git push

That's it, you are done!

If you have comments, questions or opinions please drop me a line at 2017-07-13–blogging-with-org-static-blog AT zngguvnf dot org. Please tell me whether it's ok to publish your comment here or not.