Compiler for my blog.
NOTE: readme is a little outdated, I’ve moved away from Hakyll to a custom generation script. You can fild retired Hakyll stuff here.
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 src/compile_org.py.
To compile Org into HTML, I’m invoking Emacs in batch mode in compile_org.py script.
Your can try it with src/compile_org.py --test src/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 src/compile-ipynb.
I’m compiling with jupyter, that executes the code and does few extra tweaks in src/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 src/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).
screenshot comparisons via git-diff-image
Helpful for testing css changes.
In addition I’m using blink-diff since compare can’t handle pages that are too long :(
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.