Package @ideable/style-org-theme

This package contains the sintax higlighting of my editor theme spacesmacs-dark exported as css. Uses the org-html-htmlize-generate-css to generate all the classes that aligns to the org-mode exports.

How to use it

The style are distribute as node_modules so you would need npm to install them. These styles works with the org-html-export-to-html function but you might need some settings to make sure that would work on your setup please make sure that your org-publish would set the htmlize to css.

#+BIND: org-html-htmlize-output-type ("css")

Additionally we don’t want to use the default css provided by org mode so another header to add would be:

#+OPTIONS: html-style:nil

This package is heavily inspired by orgcss

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

#+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.

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.

TODO Title with TODO

DONE Title with DONE

Title with Priority

Title with Tag   tag0 tag1

Miscellaneous

Table

Table 1: 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

List

  • The ordered list
    1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    2. Donec et massa sit amet ligula maximus feugiat.
    3. 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.

Picture

And a really wide picture.

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}

Known Issues

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

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.

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.

  1. Add the following snippet to your init.el

    (require 'ox-extra)
    (ox-extras-activate '(ignore-headlines))
    
  2. 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.

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.

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.

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.

References   ignore