How I created my web home

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
-->

Comentarios

Comments powered by Disqus