Pelican is a static website and blog generator written in Python that I've recently chosen to use to make this blog on my website. I chose it because I prefer static HTML pages for security and simplicity. Pelican intends for you to use reStructuredText (.rst extension) to create the original documents, but it also supports your creating documents in Markdown, AsciiDoc, and even - I was very pleased to see - HTML. Which is good, because while rST is convenient for simple stuff, there are only slightly complicated things it seems incapable of, like applying emphasis to a URL - you can have emphasis or a URL, not both.
Pointers:
- Favourite: http://docutils.sourceforge.net/docs/user/rst/quickref.html
- page about Pelican by the friend who helped convinced me to use it
- Best starting point for learning about reStructuredText
- And this
- Pelican Themes
- Syntax highlighting lexers provided by pygment
- precede a code block with
.. code-block:: bash
- replace "bash" with the appropriate form of code (see the lexer list above) - great trick for highlighting inline code (at stackoverflow, of course)
- what the hell is a slug?! I don't know what the name means, but essentially it's the final name of the generated file
- if you don't want the blog to be at the root of your website, you can do that. Use SITEURL = '/blog' in the pelicanconf.py
- HTML Entities (such as "e" with an acute accent) in reStructuredText are a real pain - in fact I haven't figured them out yet. It looks like it will have to be solved with a plugin as the official method is too painful to consider.