Snac: from Org to browsable HTML

Org mode (orgmode.org) is objectively the most flexible, advanced and adaptable authoring markup language available today.

HTML is undoubtedly the most widespread display markup language, with the best perspectives for long-term availability.

Specially tailored for academics looking to easily author electronic versions of books, lecture notes or similar material, snac (snippets of academe) offers a bridge between Org and HTML: from a single Org source file, it provides split, interlinked and directly publishable web-ready documents.

Setup

snac makes use of python and shell scripts.

Python virtual environment and requirements

Create a virtual environment (here: named snac-venv) and activate it:

  python -m venv snac-venv
  source snac-venv/bin/activate

Install the requirements:

  pip install -r requirements.txt

Authoring a snac

Source file

The source file is index.org in the src directory.

Sections and their labels

Sections are defined through Org mode headlines. Each headline should have a CUSTOM_ID whose format is contrained to the form [id] for a first-level section, [id]_[subid] for second-level, etc.

Plunging into the sections hierarchy, any nth-level section's CUSTOM_ID must have the n-1th-level section's CUSTOM_ID as prefix (in order for later page splitting and interlinking to work).

Equations and their labels

Block equations are displayed including a label, permalink and optional alternative labels.

When writing block equations,
• give them a semantic label (which we call eqlabel) in the form of a dedicated link, which must be unique throughout the whole document;
• [optional] include alteqlabels (i.e. labels from other sources for the same equation) as a list;
• add LaTeX tag and label with values set to eqlabel,

Full example:

#+begin_eqlabel
<<tau>>
#+begin_alteqlabels
- KBI V.1.33
#+end_alteqlabels
#+end_eqlabel
\begin{equation}
\tau (\lambda) = \mbox{exp}~ \sum_{n=0}^\infty \frac{i_n}{n!} Q_n (\lambda - \xi)^n
\tag{tau}\label{tau}
\end{equation}

Figures

To include simple figures, simply use a link to the corresponding file. For example,

  #+begin_eqlabel
  <<fig-your_label>>
  #+end_eqlabel
  #+caption: Your caption.
  #+attr_html: :width 100%
  [[./fig/your_figure.jpg]]

Search box

A search box is included in each output HTML page. Edit the searchbox_string in the src/split.py script, making sure you set your site as the value of the sites input element.

Styling

The main style file is css/snac.css.

Publishing workflow

• produce the main file's html version: invoke C-c C-e h h from the Emacs buffer for your index.org source file
• run the export.sh script (invoking ./scripts/export.sh from the base directory)
• navigate to export/html/index.html to see the results

License

This codebase is released under the terms of the GNU Affero General Public License (Version 3, 19 November 2007).