I used to prefer writing in reStructuredText more than in Markdown, but I must admit Markdown is quite convenient to use with $\LaTeX$ and Pelican. First of all, there is less need to process escapes, and second, it is possible to use Markdown extensions.
I was using ReST, but wanted to keep simple escape characters in my source code. I first wrote a script to preprocess my source code, but finally I manage to write an ugly plugin for Pelican to do it on the fly. The code is available on github, it consists in implementing a new reader, very close to the original RreStructuredText, but applying my script first.
Since my first try of Pelican, things have changed… There is now a plugin render_math which allows to directly use MathJax and its syntax in the source, without needing to change the theme template. Since I was satisfied with my theming (and I wanted sans-serif fonts, which is still unsupported), I set the auto_insert
option to False
in my settings.
However, there were still some problems with this plugin : some characters need to be escaped in Markdown, such as braces (putting in the source $∅=\{\}$
does not give what is expected), it does not recognize \[
and \]
for display equations, and other syntax problem arise for instance with *
and _
(think of the source $x *y* z$
).
I finally discovered that a better solution was not to rewrite this plugin, but to use a Markdown extension called python-markdown-mathjax. It directly modifies the behaviour of the Markdown interpreter. It happens that this extension did not perfectly satisfy my needs, but it was really simple to adapt it to my needs. Here is my fork.
I’m now very happy, and I can write a lot of silly stuff :
\[\sum_{n⩾1} n = \frac{-1}{12}.\]
Other new things that are new and very nice in pelican :
First of all, there is a plugin called i18n_subsites which does exactly what I needed to have my site in French and English (I used to generate two versions of the site, with two different theme templates and settings — horrible to maintain – but it was duplicating static files for instance, and I needed a script to generate the whole site).
So I have modified my theme, which is now quite simple. I have put it on github if you want to try it. It is not very standard, pages are sorted by an attribute position
, and the home page has a save_as
attribute set to index.html
, so I do not have this file in the templates.
Finally, there is also a plugin called liquid_tags which is very nice to import directly IPython notebooks (only with Markdown, as far as I understand).
I still have problems to style properly the notebooks (the method given by the plugin consisting in adding a file _nb_header.html
does not work for me, it conflicts with the whole CSS styling of the site). But I trust there is a solution.