Hakyll compiler for my blog.
Features:
- formats:
- org-mode
- ipython notebooks
- markdown (useful to link READMEs as blog posts)
- tags
- feeds (rss/atom)
- comments support using Isso
- math support via Mathjax
- drafts
- custom metadata attributes (e.g. tags, special uuid attribute for linking comments, pingback)
- symlink support
There are some comments in site.hs, feel free to email me or open an issue if you want me to explain how something works!
I’ll write down about it properly at some point later!
Post compilers
Org-mode
See my org-mode sandbox.
Org related stuff is in Org.hs and misc/compile-org.
To compile Org into HTML, I’m invoking Emacs in batch mode in compile-org script.
Your can try it with misc/compile-org --test misc/test.org.
Reason I’m not using Pandoc for rendering is that it only supports a subset of Org-mode. If you are a heavy user of Org-mode features, e.g. doesn’t support literate programming via org-babel.
Using custom script lets me configure (and hack a little) Emacs to bend it into doing what I want. I also process the resulting HTML with BeautifulSoup to add some things org-mode isn’t capable of like sidenotes.
Ipython
See my org-mode sandbox.
Ipython related things are in Ipynb.hs and misc/compile-ipynb.
I’m compiling with jupyter, that executes the code and does few extra tweaks in misc/ipynbconfig.py, in particular:
- hidden cell support (e.g. when you have lots of boilerlate that don’t need to be in the post body)
- details/summary support, so you can collapse boilerplate or long outputs in a collapsible section.
Misc things
css/generate-links.py for generating CSS for certain links (e.g. wikipedia/reddit/github)
symlink support: see misc/poke-symlinks.py and preview.
Very useful when the target post (e.g. ipython notebook is in a different repository). Without this, detecting changes wouldn’t work (see issue).
Running & building
I guess best place to start would be hakyll tutorial.
Compiling the site
When I want to release new version of site, I’m basically doing a clean rebuild and copying the resulting _site directory.
In reality it’s a little more elaborate, I’m keeping the whole website (HTMLs) under git, so I can easily track changes and rollback in case of issues. I’ll explain it and share some workflows later.