This website is made of static html pages generated by Nikola from Emacs Orgmode sources (I've learnt to stay away from CMSs). Nikola is a Python package that translates a collection of plain-text sources in a variety of markup languages to html, providing support for blogging and commenting, and visually styling the site through different themes. Themes in turn rely on an independent template system (it can be Mako or Jinja2) plus a set of CSS and font files (and some themes support replacing CSSs and fonts using a bootswatch theme).
This leverage of external tools is certainly a smart choice of Nikola's designers, but it is rather confusing to website newbies like me. I also found Nikola's documentation a bit hard to follow, not knowing these external tools, as the roles of the different tools are not clearly explained (it is probably clear enough if you have some experience in web publishing, but it is not my case). I would probaby have given up on Nikola but for this wonderful post on shisaa.jp) So it was a bit hard starting up, but the effort has paid. (By the way, if a Nikola guru ever reads this post, I would be happy to stand corrected on the rough summary of Nikola above).
For what is worth, here is a summary of how I proceeded. It is pretty straightforward now that is done, except perhaps for the publication list part, which I had to put together myself and maybe of use to others.
Nikola setup
I installed Nikola with pip as explained in the documentation. I
added the orgmode plugin with
nikola plugin --install orgmode
After creating an empty site with nikola init, one must tune the
conf.py script. This is well commented and mostly straightforward.
The more delicate variables were POST and PAGES,
which define the input and output directories, INDEX_PATH, which
specifies the destination of the post index (and which you must change
if you want a site, like this one, which is not primarily a blog), and
TRANSLATIONS, which defines where the different translations will be
placed. By default, the DEFAULT_LANG is put in the output
directory, with translations in subdirectories. I opted for a more
symmetrical structure with a subdirectory for each language (two in my
case), so that translating a file requires less work (for example,
language-free images can be included specifying the same relative
path).
Theme
I chose one of Nikola's built-in themes. While it is possible to derive from a theme to tweak it to your liking (e.g. by adding custom CSS), I just don't know enough CSS to do it without messing up, so I stuck to what is provided by the distribution.
CSS for code highlighting
The Orgmode plugin needs additional CSS to give syntax highlighting
(which gives the additional flexibility of choosing the color
scheme). It is done through pygment, and the CSS is generated with
something like
pygmentize -S emacs -a .highlight -f html >>custom.css
The custom.css file must then be placed in the assets/css
subdirectory of the theme in use (check that the bundles file
includes it).
Comments
Nikola supports several third-party comment systems. I am currently
experimenting with Disqus. Setup involves simply setting the
variables COMMENT_SYSTEM and COMMENT_SYSTEM_ID in conf.py.
The publication list
My bibliography (including references to my own publications) is
stored in Zotero. Although there are tools to create html directly
from Zotero collections, there was none I could get working to my
satisfaction. So presently the publication list is created from a
BibTex file using bibtex2html to produce a bare html list, to
which I add the Nikola header and then treat like a regular Nikola
page.
The .bib file comes from the Zotero collection which holds my
publications, from which it is exported with BetterBibTex (a Zotero
plugin). I include attached files in the export to be able to serve
the articles' pdf, but the .bib file needs filtering before it can
be fed to bibtex2html because the file field is formatted as
:name:path:application/pdf, and can have more than one file (Zotero
stores journal site snapshots and files like supporting information as
well). I also need to change the relative path so that the pdfs are
correctly linked. All this is done with sed (long live regexps!).
The three steps (filtering, converting and building the source page
for Nikola) are done in the following bash script (assuming the
desired Zotero collections has been exported in subdirectory own):
#!/bin/bash
sed '/file =/ {
s%\([{;]\)[^:;]*:\([^:;]*\):application/pdf\([;}]\)%\1\2\3%;
s%{[^:;]*:[^:;]*:[^:;]*;%{%;
s%;[^:;]*:[^:;]*:[^:;]*;%;%;
s%;[^:;]*:[^:;]*:[^:;]*}%}%;
s%{files/%{../../files/%;
} ' own/own.bib >own/own-f.bib
echo "\def\BIBand{y}" >macros.tex
echo "\def\backslash{\\}" >>macros.tex
SDIR=../personal
ODIR=${SDIR}/main/personal
bibtex2html --nodoc --no-abstract --no-keywords --unicode --named-field file pdf --sort-as-bibtex --macros-from macros.tex --style sp_yearorder_authorsc -o publist own/own-f.bib
cat pubhead.html publist.html >${ODIR}/publist.html
cat pubhead_bib.html publist_bib.html >${ODIR}/publist_bib.html
bibtex2html --nodoc --no-abstract --no-keywords --unicode --named-field file pdf --sort-as-bibtex --macros-from macros.tex --style en_yearorder -o publist own/own-f.bib
cat pubhead.en.html publist.html >${ODIR}/publist.en.html
cat pubhead_bib.en.html publist_bib.html >${ODIR}/publist_bib.en.html
ln -s -f $PWD/own/files $SDIR/files
The four headers (pubhead.html, etc.) are obvious variations of the
following:
.. title: Publicaciones .. slug: publist .. date: 2015-07-31 10:24:50 UTC-03:00 .. tags: .. category: .. link: .. description: .. type: text
)