CSS for Org-exported HTML

A Clean and Comfort Stylesheet

This article serves as a complete demonstration for my org.css, a simple and clean stylesheet for org-exported HTML file. You may switch between the default style provided by Emacs Org mode, i.e., styles specified in the variable org-html-style-default and my customized stylesheet using the button at the top left corner.

1 Introduction

Org mode is for keeping notes¹, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system² [1].

Org mode was created by Carsten Dominik back in 2003. It is a built-in major mode in Emacs. It's similar to markdown [2], where all editing is done in plain text with some character markups to decorate texts and finally the text file can be exported to some other formats, e.g., HTML. The philosophy is that we can concentrate on the contents with as few distraction from the styles as possible, i.e., as easy-to-read and easy-to-write as is feasible. However, the original markdown is a markup language used to create web pages, while Org mode provides much richer functionality beyond simple text markup, e.g., a complete Getting Things Done (GTD) system, task timing and reminder, complete system for reproducible research, etc. In this article however we only focus on one of its uses, generating HTML pages. I will assume that readers are already familiar with Emacs and org mode, otherwise please refer to orgmode.org and https://www.gnu.org/software/emacs/ for introduction.

3 Motivation

As a heavy Emacs user, blogging with org mode is a natural choice. I'm keeping notes in org mode, and I may want to publish some of them online. Questions like why not use products like MS OneNote or Google Keep or Wordpress or whatever simply boil down to personal preference.

Org file is a simple text file which can be processed efficiently by external programs.
It has good built-in support from Emacs, and
can be exported to various formats, TeX, PDF and HTML. Except for some special cases where dedicated styles are needed, say academic papers, the default export styles with simple tweaks usually satisfy my needs. However, the default style provided by org html exporter is simple boring. So I decide to tweak the stylesheet a little bit to make it clean, simple and more eye appealing.

Source code of this file is available at https://github.com/gongzhitaao/orgcss.

4 Setup

Publishing with org mode can be achieved as simple as a few keystrokes (say C-c C-e h h for html exporting and C-c C-e l p for pdf exporting). We omit the publishing configuration as the main goal of this article is to demo my stylesheet. The process can be meticulously tweaked following the instruction here. Actually in my current setup, no tweaks and special configurations are needed. All remains default and works out of the box.

4.1 External Utilities

Table 1 list all the external utilities I used for publishing and rendering.

Table 1: Utilities
Utility	Description
bibtex2html	Export citations in bib files, if any, to html.
MathJax	Render math equations.

Here are some notes about the above utility.

bibtex2html is optional if no citation is required. Citation syntax is \cite{key}, or cite:key. To use this functionality, you need to include the following elisp code in your configuration.
```
(require 'ox-bibtex)
```
I do not have a better option for HTML bibtex export. I think an ideal solution is pure lisp-based or Javascript-based. The problem with Javascript-based solution is that the back-reference might be difficult to implement.
I use MathJax inline rendering for equations despite of its speed. It is said that KaTeX loads and renders faster than MathJax, however, the former supports only a subset of \(\LaTeX\) syntax. See the comparison between the two. Anyway, I do not have that many equations to show off.

4.2 Org Templates

The following is my org file template for blogging.

#+TITLE: Article Title Goes Here
#+OPTIONS: toc:nil num:3 H:4 ^:nil pri:t
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="org.css"/>

#+BEGIN_abstract
Article abstract goes here.
#+END_abstract

# now prints out the previously disabled (toc:nil) table of contents.
#+TOC: headlines 2

Your content goes here.

# note the ignore tag
* Refrences                                                          :ignore:

# prints out bibliograph, if any, with bibtex2html.  The first parameter is the
# bibliograph file name without .bib extension, the second is the reference
# style.  The rest parameters are parsed to `bibtex2html'.  Refer to the
# ox-bibtex document for further information.

#+BIBLIOGRAPHY: ref plain limit:t option:-nokeywords

# This is an automatically generated section if you use footnote.
* Footnotes

With all these setup, only one thing is left, i.e., tweaking the styles of exported html. By default, The HTML exporter assigns some special CSS classes to appropriate parts of the document and your style specifications may change these, in addition to any of the standard classes like for headlines, tables, etc. The list is actually not complete, you may want to export a test org file and read the source of exported html file to find out what classes are available. The current page shows off my org.css. Some other good styles for org-exported html can be found on http://orgmode.org/, http://doc.norang.ca/org-mode.html and etc.

5 Demo

<2015-11-09 Mon 14:41>

We use Lorem ipsum text to demonstrate all elements you would expect to see in the org-exported HTML pages. Note however that the .title, .subtitle and #postamble element are not included in this section.

5.1 TODO Title with TODO

5.2 DONE Title with DONE

5.3 [A] Title with Priority

5.4 Title with Tag tag0 tag1

5.5 Miscellaneous

5.5.1 Table

Table 2: Table Caption
\(N\)	\(N^2\)	\(N^3\)	\(N^4\)	\(\sqrt n\)	\(\sqrt[4]N\)
1	1	1	1	1	1
2	4	8	16	1.4142	1.1892
3	9	27	81	1.7321	1.3161

5.5.2 List

The ordered list

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec et massa sit amet ligula maximus feugiat.
Morbi consequat orci et tincidunt sagittis.

Unordered list

Aliquam non metus nec elit pellentesque scelerisque.
In accumsan nunc ac orci varius hendrerit.
Suspendisse non eros eu nisi finibus maximus.

Definition list

Lorem ipsum: dolor sit amet, consectetur adipiscing elit. Mauris laoreet sollicitudin venenatis. Duis sed consequat dolor.
Etiam feugiat: pharetra sapien et semper. Nunc ornare lacus sit amet massa auctor, vitae aliquam eros interdum. Mauris arcu ante, imperdiet vel purus ac, bibendum faucibus diam. Ut blandit nec mi at ultricies. Donec eget mattis nisl. In sed nibh felis. Cras quis convallis orci.
Sed aliquam: odio sed faucibus aliquam, arcu augue elementum justo, ut vulputate ligula sem in augue. Maecenas ante felis, pellentesque auctor semper non, eleifend quis ante. Fusce enim orci, suscipit ac dapibus et, fermentum eu tortor. Duis in facilisis ante, quis faucibus dolor. Etiam maximus lorem quis accumsan vehicula.

5.5.3 Picture

And a really wide picture.

5.5.4 Math

\begin{align} \mathcal{F}(a) &= \frac{1}{2\pi i}\oint_\gamma \frac{f(z)}{z - a}\,dz\\ \int_D (\nabla\cdot \mathcal{F})\,dV &=\int_{\partial D}\mathcal{F}\cdot n\, dS \end{align}

6 Known Issues

The citation exporter, ox-bibtex, does NOT work seamlessly. As of Org-mode 8.3.2, I have the following issues.

6.1 Dangling Element solved

The lisp function insert-file-contents used in ox-bibtex does not move point and insertion-marker to the end of inserted text (I'm not sure it is a bug or an intention). The result is that the citation is a dangling table not included in the bibliography div.

The expected result is

<div id="bibliography">
  <h2>Bibliography</h2>
  <table>
  <!-- Citation content goes here -->
  </table>
</div>

But we got

<div id="bibliography">
  <h2>Bibliography</h2>
</div>
<table>
<!-- Citation content goes here -->
</table>

Unless a patch is submitted, we may need to manually adjust this weird result.

6.2 Bibliography in Wrong Section solved

The exported bibliography is always included in some other section div instead of a stand-lone section.

The expected result is

<div id="outline-container-1" class="outline-2">
  <!-- section 1 -->
</div>
<div id="outline-container-2" class="outline-2">
  <!-- section 2 -->
</div>
<div id="outline-container-3" class="outline-2">
  <!-- section 3 -->
</div>
<div id="bibliography">
  <!-- bibliography goes here -->
</div>

But we got

<div id="outline-container-1" class="outline-2">
  <!-- section 1 -->
</div>
<div id="outline-container-2" class="outline-2">
  <!-- section 2 -->
</div>
<div id="outline-container-3" class="outline-2">
  <!-- section 3 -->
  <div id="bibliography">
    <!-- bibliography goes here -->
  </div>
</div>

The problem is that the #+BIBLIOGRAPHY command is always ignored unless it is belonged to a section. ~~This is due to the internal implementation of keyword~~ ~~parser of ox-html. Currently hacking some post-processing code is the only~~ ~~solution if you do not want to do it manually~~.

This problem is solved as follows.

Add the following snippet to your init.el

(require 'ox-extra)
(ox-extras-activate '(ignore-headlines))

adding ignore tag to whichever headline you want to ignore. Note that this is different from the COMMENT in Org mode in that COMMENT ignores the head and contents in its section, while ignore only ignores the headline but keeps the contents when exporting. See the above template.

6.3 Wrong Back Reference

The links generated by ox-bibtex is also troublesome. Given ref.bib, bibtex2html will generate two files, reb_bib.html and ref.html. The utility ox-bibtex directly inserts contents of ref.html to the current exported html. Now when you click links in the exported html, you will be directed to ref_bib.html. And when expecting to get back to the exported html by clicking links in ref_bib.html, you will be instead directed to ref.html. My solution is to ~~remove the bibliograph source with option:-nobibsource~~ replace the link in ref_bib.html with when compiling the HTML (see this gulpfile.js), it is a hacky way though.

6.4 `fci-mode` Issue

If you use fci-mode , and it is turned on in the major code of your to-be-exported source code section, you will notice some dummy characters at each newline (as of Org-v9.3.1) as following.

#include <iostream>
using namesapce std;

int main()
{
  return 0;
}

The workaround to this issue: https://emacs.stackexchange.com/q/44361 and some discussions on emacs-orgmode maillist. I did not have this issue with previous version of org-mode and fci-mode. Simply turning off the fci-mode for major mode solves the problem.

7 Conclusion

This article essentially demonstrates my stylesheet for org-exported html file without going into details about the publishing process which requires some knowledge about Emacs and org mode. There are some dangling issues around the citation with ox-bibtex, to which the simple solution is to use links instead of citations, if possible. Otherwise, hacking some post-processing code is necessary.

8 Credits

Some styles are borrowed from the following projects.

References

[1]	Carsten Dominik and many others. Org mode for Emacs, 2003. [ bib \| http ]
[2]	John Gruber. Markdown, December 2004. [ bib \| http ]

Footnotes:

For note keeping, Deft with Org mode make a cute couple.

A great article elaborates on this.