forked from gongzhitaao/orgcss
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
88 lines (81 loc) · 33.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>CSS for Org-exported HTML</title><meta name="generator" content="Org mode"><meta name="author" content="Zhitao Gong"><link id="pagestyle" rel="stylesheet" type="text/css" href="org.css"><script type="text/x-mathjax-config">MathJax.Hub.Config({
displayAlign: "center",
displayIndent: "0em",
"HTML-CSS": { scale: 100,
linebreaks: { automatic: "false" },
webFont: "TeX"
},
SVG: {scale: 100,
linebreaks: { automatic: "false" },
font: "TeX"},
NativeMML: {scale: 100},
TeX: { equationNumbers: {autoNumber: "AMS"},
MultLineWidth: "85%",
TagSide: "right",
TagIndent: ".8em"
}
});</script><script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML"></script></head><body><div id="content"><header><h1 class="title">CSS for Org-exported HTML</h1><p class="subtitle">A Clean and Comfort Stylesheet</p></header><script>function swapStyle(e){document.getElementById("pagestyle").setAttribute("href",e)}</script><div style="margin:1em auto"><button onclick='swapStyle("org.css")'>Customized</button> <button onclick='swapStyle("org-default.css")'>Default</button></div><div class="abstract"><p></p><p>This article serves as a complete demonstration for my <a href="org.css">org.css</a>, 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 <code>org-html-style-default</code> and my customized stylesheet using the button at the top left corner.</p></div><nav id="table-of-contents"><h2>Table of Contents</h2><div id="text-table-of-contents"><ul><li><a href="#sec:introduction">1. Introduction</a></li><li><a href="#sec:related-markdowns">2. Related Markdowns</a></li><li><a href="#sec:motivation">3. Motivation</a></li><li><a href="#sec:setup">4. Setup</a><ul><li><a href="#sec:external-utilities">4.1. External Utilities</a></li><li><a href="#sec:org-templates">4.2. Org Templates</a></li></ul></li><li><a href="#sec:demo">5. Demo</a><ul><li><a href="#org9f0bfa0">5.1. <span class="todo TODO">TODO</span> Title with TODO</a></li><li><a href="#org7cff5c1">5.2. <span class="done DONE">DONE</span> Title with DONE</a></li><li><a href="#org878efa3">5.3. <span class="priority">[A]</span> Title with Priority</a></li><li><a href="#org2813018">5.4. Title with Tag   <span class="tag"><span class="tag0">tag0</span> <span class="tag1">tag1</span></span></a></li><li><a href="#org4213c27">5.5. Miscellaneous</a></li></ul></li><li><a href="#sec:known-issues">6. Known Issues</a><ul><li><a href="#sec:dangling-element">6.1. <del>Dangling Element</del>   <span class="tag"><span class="solved">solved</span></span></a></li><li><a href="#sec:bibliograph-in-wrong-section">6.2. <del>Bibliography in Wrong Section</del>   <span class="tag"><span class="solved">solved</span></span></a></li><li><a href="#sec:wrong-back-reference">6.3. Wrong Back Reference</a></li><li><a href="#h2-fci-mode-issue">6.4. <code>fci-mode</code> Issue</a></li></ul></li><li><a href="#sec:conclusion">7. Conclusion</a></li><li><a href="#org3032670">8. Credits</a></li></ul></div></nav><div id="outline-container-org5ccf305" class="outline-2"><h2 id="sec:introduction"><a id="org5ccf305" name="org5ccf305"></a><span class="section-number-2">1</span> Introduction</h2><div class="outline-text-2" id="text-sec:introduction"><blockquote><p></p><p><a href="http://orgmode.org/">Org mode</a> is for keeping notes<sup><a id="fnr.1" name="fnr.1" class="footref" href="#fn.1">1</a></sup>, maintaining TODO lists, planning projects, and authoring documents with a fast and effective <i>plain-text</i> system<sup><a id="fnr.2" name="fnr.2" class="footref" href="#fn.2">2</a></sup> [<a href="#dominik2003-org">1</a>].</p></blockquote><p>Org mode was created by Carsten Dominik back in 2003. It is a built-in major mode in <a href="http://www.gnu.org/software/emacs/">Emacs</a>. It's similar to <a href="http://daringfireball.net/projects/markdown/syntax">markdown</a> [<a href="#gruber2004-markdown">2</a>], 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 <a href="https://en.wikipedia.org/wiki/Getting_Things_Done">Getting Things Done (GTD)</a> system, task timing and reminder, complete system for reproducible research, etc. In this article however we only focus on one of its uses, <i>generating HTML pages</i>. I will assume that readers are already familiar with Emacs and org mode, otherwise please refer to <a href="http://orgmode.org/">orgmode.org</a> and <a href="https://www.gnu.org/software/emacs/">https://www.gnu.org/software/emacs/</a> for introduction.</p></div></div><div id="outline-container-org80f308b" class="outline-2"><h2 id="sec:related-markdowns"><a id="org80f308b" name="org80f308b"></a><span class="section-number-2">2</span> Related Markdowns</h2><div class="outline-text-2" id="text-sec:related-markdowns"><p><a href="https://daringfireball.net/projects/markdown/">Markdown 1.0.1</a> was first released back in 2004.</p><blockquote><p></p><p>Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).</p></blockquote><p>There are many flavors of markdowns and tools. The followings are some that I really like. For a more complete list of markdown flavors, see <a href="http://pandoc.org/">Pandoc</a>.</p><figure><img src="img/org-mode.png" alt="org-mode.png" style="width:80px"></figure><p><a href="http://orgmode.org/">Org mode</a>, a Emacs built-in major mode. This document is generated in Org mode.</p><figure><img src="img/gfm.png" alt="gfm.png" style="width:80px"></figure><p><a href="https://guides.github.com/features/mastering-markdown/">Github Flavored Markdown (GFM)</a>, a variant favored by <a href="https://github.com">Github</a>.</p><figure><img src="img/madoko.png" alt="madoko.png" style="width:80px"></figure><p><a href="https://www.madoko.net/">Madoko</a>, a less-known but excellent and fast markdown processor for writing <i>professional</i> articles, books, manuals, webpages and presentations, with a focus on simplicity and plain text readability.</p><figure><img src="img/texinfo.png" alt="texinfo.png" style="width:80px"></figure><p><a href="https://www.gnu.org/software/texinfo/">Texinfo</a> uses a single source file to produce output in a number of formats, both online and printed (dvi, html, info, pdf, xml, etc.). It is well-integrated in Emacs.</p></div></div><div id="outline-container-org43cc596" class="outline-2"><h2 id="sec:motivation"><a id="org43cc596" name="org43cc596"></a><span class="section-number-2">3</span> Motivation</h2><div class="outline-text-2" id="text-sec:motivation"><p>As a heavy Emacs user, <a href="https://www.google.com/search?q=blogging+with+org+mode">blogging with org mode</a> 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.</p><ol class="org-ol"><li>Org file is a simple text file which can be processed efficiently by external programs.</li><li>It has good built-in support from Emacs, and</li><li>can be exported to various formats, <i>TeX</i>, <i>PDF</i> and <i>HTML</i>. 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 <i>boring</i>. So I decide to tweak the stylesheet a little bit to make it <i>clean</i>, <i>simple</i> and more <i>eye appealing</i>.</li></ol><p>Source code of this file is available at <a href="https://github.com/gongzhitaao/orgcss">https://github.com/gongzhitaao/orgcss</a>.</p></div></div><div id="outline-container-org0b207ba" class="outline-2"><h2 id="sec:setup"><a id="org0b207ba" name="org0b207ba"></a><span class="section-number-2">4</span> Setup</h2><div class="outline-text-2" id="text-sec:setup"><p>Publishing with org mode can be achieved as simple as a few keystrokes (say <kbd>C-c C-e h h</kbd> for html exporting and <kbd>C-c C-e l p</kbd> 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 <a href="http://orgmode.org/manual/Publishing.html#Publishing">instruction here.</a> Actually in my current setup, no tweaks and special configurations are needed. All remains default and works out of the box.</p></div><div id="outline-container-orge3a33aa" class="outline-3"><h3 id="sec:external-utilities"><a id="orge3a33aa" name="orge3a33aa"></a><span class="section-number-3">4.1</span> External Utilities</h3><div class="outline-text-3" id="text-sec:external-utilities"><p>Table <a href="#org243be5c">1</a> list all the external utilities I used for publishing and rendering.</p><table id="org243be5c"><caption class="t-above"><span class="table-number">Table 1:</span> Utilities</caption><colgroup><col class="org-left"><col class="org-left"></colgroup><thead><tr><th scope="col" class="org-left">Utility</th><th scope="col" class="org-left">Description</th></tr></thead><tbody><tr><td class="org-left"><a href="https://www.lri.fr/~filliatr/bibtex2html/">bibtex2html</a></td><td class="org-left">Export citations in bib files, if any, to html.</td></tr><tr><td class="org-left"><a href="https://www.mathjax.org/">MathJax</a></td><td class="org-left">Render math equations.</td></tr></tbody></table><p>Here are some notes about the above utility.</p><ul class="org-ul"><li><p><code>bibtex2html</code> is optional if no citation is required. Citation syntax is <code>\cite{key}</code>, or <code>cite:key</code>. To use this functionality, you need to include the following elisp code in your configuration.</p><div class="org-src-container"><pre class="src src-emacs-lisp"><span class="org-rainbow-delimiters-depth-1">(</span><span class="org-keyword">require</span><span class="org-whitespace-space"> </span>'<span class="org-constant">ox-bibtex</span><span class="org-rainbow-delimiters-depth-1">)</span>
</pre></div><p>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.</p></li><li>I use <a href="https://www.mathjax.org/">MathJax</a> inline rendering for equations despite of its speed. It is said that <a href="http://khan.github.io/KaTeX/">KaTeX</a> loads and renders faster than MathJax, however, the former supports only a subset of \(\LaTeX\) syntax. See the <a href="http://www.intmath.com/cg5/katex-mathjax-comparison.php">comparison</a> between the two. Anyway, I do not have that many equations to show off.</li></ul></div></div><div id="outline-container-orgf46b8e9" class="outline-3"><h3 id="sec:org-templates"><a id="orgf46b8e9" name="orgf46b8e9"></a><span class="section-number-3">4.2</span> Org Templates</h3><div class="outline-text-3" id="text-sec:org-templates"><p>The following is my org file template for blogging.</p><div class="org-src-container"><pre class="src src-org"><span class="org-org-document-info-keyword">#+TITLE:</span> <span class="org-org-document-title">Article Title Goes Here</span>
<span class="org-org-meta-line">#+OPTIONS: toc:nil num:3 H:4 ^:nil pri:t</span>
<span class="org-org-meta-line">#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="org.css"/></span>
<span class="org-org-block-begin-line">#+BEGIN_abstract</span>
Article abstract goes here.
<span class="org-org-block-end-line">#+END_abstract</span>
<span class="org-comment"># now prints out the previously disabled (toc:nil) table of contents.</span>
<span class="org-org-meta-line">#+TOC: headlines 2</span>
Your content goes here.
<span class="org-comment"># note the ignore tag</span>
<span class="org-org-level-1">* Refrences </span><span class="org-org-level-1"><span class="org-org-tag">:ignore:</span></span>
<span class="org-comment"># prints out bibliograph, if any, with bibtex2html. The first parameter is the</span>
<span class="org-comment"># bibliograph file name without .bib extension, the second is the reference</span>
<span class="org-comment"># style. The rest parameters are parsed to `bibtex2html'. Refer to the</span>
<span class="org-comment"># ox-bibtex document for further information.</span>
<span class="org-org-meta-line">#+BIBLIOGRAPHY: ref.bib plain option:-nobibsource limit:t option:-nokeywords</span>
<span class="org-comment"># This is an automatically generated section if you use footnote.</span>
<span class="org-org-level-1">* Footnotes</span>
</pre></div><p>With all these setup, only one thing is left, i.e., tweaking the styles of exported html. By default, The HTML exporter assigns some <a href="http://orgmode.org/manual/CSS-support.html">special CSS classes</a> 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 <a href="http://orgmode.org/">http://orgmode.org/</a>, <a href="http://doc.norang.ca/org-mode.html">http://doc.norang.ca/org-mode.html</a> and etc.</p></div></div></div><div id="outline-container-org3ebb00d" class="outline-2"><h2 id="sec:demo"><a id="org3ebb00d" name="org3ebb00d"></a><span class="section-number-2">5</span> Demo</h2><div class="outline-text-2" id="text-sec:demo"><p><span class="timestamp-wrapper"><span class="timestamp"><2015-11-09 Mon 14:41></span></span></p><p>We use <a href="https://en.wikipedia.org/wiki/Lorem_ipsum">Lorem ipsum</a> text to demonstrate all elements you would expect to see in the org-exported HTML pages. Note however that the <code>.title</code>, <code>.subtitle</code> and <code>#postamble</code> element are not included in this section.</p></div><div id="outline-container-org9f0bfa0" class="outline-3"><h3 id="org9f0bfa0"><span class="section-number-3">5.1</span> <span class="todo TODO">TODO</span> Title with TODO</h3></div><div id="outline-container-org7cff5c1" class="outline-3"><h3 id="org7cff5c1"><span class="section-number-3">5.2</span> <span class="done DONE">DONE</span> Title with DONE</h3></div><div id="outline-container-org878efa3" class="outline-3"><h3 id="org878efa3"><span class="section-number-3">5.3</span> <span class="priority">[A]</span> Title with Priority</h3></div><div id="outline-container-org2813018" class="outline-3"><h3 id="org2813018"><span class="section-number-3">5.4</span> Title with Tag   <span class="tag"><span class="tag0">tag0</span> <span class="tag1">tag1</span></span></h3></div><div id="outline-container-org4213c27" class="outline-3"><h3 id="org4213c27"><span class="section-number-3">5.5</span> Miscellaneous</h3><div class="outline-text-3" id="text-5-5"></div><div id="outline-container-org09a8f6b" class="outline-4"><h4 id="org09a8f6b"><span class="section-number-4">5.5.1</span> Table</h4><div class="outline-text-4" id="text-5-5-1"><table><caption class="t-above"><span class="table-number">Table 2:</span> Table Caption</caption><colgroup><col class="org-right"><col class="org-right"><col class="org-right"><col class="org-right"><col class="org-right"><col class="org-right"></colgroup><thead><tr><th scope="col" class="org-right">\(N\)</th><th scope="col" class="org-right">\(N^2\)</th><th scope="col" class="org-right">\(N^3\)</th><th scope="col" class="org-right">\(N^4\)</th><th scope="col" class="org-right">\(\sqrt n\)</th><th scope="col" class="org-right">\(\sqrt[4]N\)</th></tr></thead><tbody><tr><td class="org-right">1</td><td class="org-right">1</td><td class="org-right">1</td><td class="org-right">1</td><td class="org-right">1</td><td class="org-right">1</td></tr><tr><td class="org-right">2</td><td class="org-right">4</td><td class="org-right">8</td><td class="org-right">16</td><td class="org-right">1.4142</td><td class="org-right">1.1892</td></tr><tr><td class="org-right">3</td><td class="org-right">9</td><td class="org-right">27</td><td class="org-right">81</td><td class="org-right">1.7321</td><td class="org-right">1.3161</td></tr></tbody></table></div></div><div id="outline-container-org0767160" class="outline-4"><h4 id="org0767160"><span class="section-number-4">5.5.2</span> List</h4><div class="outline-text-4" id="text-5-5-2"></div><div id="outline-container-orgcbeeaa6" class="outline-5"><h5 id="orgcbeeaa6">The ordered list</h5><div class="outline-text-5" id="text-orgcbeeaa6"><ol class="org-ol"><li>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</li><li>Donec et massa sit amet ligula maximus feugiat.</li><li>Morbi consequat orci et tincidunt sagittis.</li></ol></div></div><div id="outline-container-org36f6071" class="outline-5"><h5 id="org36f6071">Unordered list</h5><div class="outline-text-5" id="text-org36f6071"><ul class="org-ul"><li>Aliquam non metus nec elit pellentesque scelerisque.</li><li>In accumsan nunc ac orci varius hendrerit.</li><li>Suspendisse non eros eu nisi finibus maximus.</li></ul></div></div><div id="outline-container-org0e0ab8d" class="outline-5"><h5 id="org0e0ab8d">Definition list</h5><div class="outline-text-5" id="text-org0e0ab8d"><dl class="org-dl"><dt>Lorem ipsum</dt><dd>dolor sit amet, consectetur adipiscing elit. Mauris laoreet sollicitudin venenatis. Duis sed consequat dolor.</dd><dt>Etiam feugiat</dt><dd>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.</dd><dt>Sed aliquam</dt><dd>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.</dd></dl></div></div></div><div id="outline-container-org0248b3e" class="outline-4"><h4 id="org0248b3e"><span class="section-number-4">5.5.3</span> Picture</h4><div class="outline-text-4" id="text-5-5-3"><figure><img src="./img/pic-demo.png" alt="pic-demo.png"><figcaption><span class="figure-number">Figure 5: </span>Demo Picture with Caption</figcaption></figure><p>And a really wide picture.</p><figure><img src="img/long-img.png" alt="long-img.png"><figcaption><span class="figure-number">Figure 6: </span>A really long picture</figcaption></figure></div></div><div id="outline-container-org7b391b4" class="outline-4"><h4 id="org7b391b4"><span class="section-number-4">5.5.4</span> Math</h4><div class="outline-text-4" id="text-5-5-4">\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}</div></div></div></div><div id="outline-container-org324aa12" class="outline-2"><h2 id="sec:known-issues"><a id="org324aa12" name="org324aa12"></a><span class="section-number-2">6</span> Known Issues</h2><div class="outline-text-2" id="text-sec:known-issues"><p>The citation exporter, <code>ox-bibtex</code>, does NOT work seamlessly. As of <code>Org-mode 8.3.2</code>, I have the following issues.</p></div><div id="outline-container-orge57e035" class="outline-3"><h3 id="sec:dangling-element"><a id="orge57e035" name="orge57e035"></a><span class="section-number-3">6.1</span> <del>Dangling Element</del>   <span class="tag"><span class="solved">solved</span></span></h3><div class="outline-text-3" id="text-sec:dangling-element"><p>The lisp function <code>insert-file-contents</code> used in <code>ox-bibtex</code> 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.</p><p>The expected result is</p><div class="org-src-container"><pre class="src src-html"><<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"bibliography"</span>>
<<span class="org-function-name">h2</span>><span class="org-underline"><span class="org-bold-italic">Bibliography</span></span></<span class="org-function-name">h2</span>>
<<span class="org-function-name">table</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">Citation content goes here </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">table</span>>
</<span class="org-function-name">div</span>>
</pre></div><p>But we got</p><div class="org-src-container"><pre class="src src-html"><<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"bibliography"</span>>
<<span class="org-function-name">h2</span>><span class="org-underline"><span class="org-bold-italic">Bibliography</span></span></<span class="org-function-name">h2</span>>
</<span class="org-function-name">div</span>>
<<span class="org-function-name">table</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">Citation content goes here </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">table</span>>
</pre></div><p>Unless a patch is submitted, we may need to manually adjust this weird result.</p></div></div><div id="outline-container-orgc09b8ed" class="outline-3"><h3 id="sec:bibliograph-in-wrong-section"><a id="orgc09b8ed" name="orgc09b8ed"></a><span class="section-number-3">6.2</span> <del>Bibliography in Wrong Section</del>   <span class="tag"><span class="solved">solved</span></span></h3><div class="outline-text-3" id="text-sec:bibliograph-in-wrong-section"><p>The exported bibliography is always included in some other section div instead of a stand-lone section.</p><p>The expected result is</p><div class="org-src-container"><pre class="src src-html"><<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"outline-container-1"</span> <span class="org-variable-name">class</span>=<span class="org-string">"outline-2"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">section 1 </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
<<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"outline-container-2"</span> <span class="org-variable-name">class</span>=<span class="org-string">"outline-2"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">section 2 </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
<<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"outline-container-3"</span> <span class="org-variable-name">class</span>=<span class="org-string">"outline-2"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">section 3 </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
<<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"bibliography"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">bibliography goes here </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
</pre></div><p>But we got</p><div class="org-src-container"><pre class="src src-html"><<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"outline-container-1"</span> <span class="org-variable-name">class</span>=<span class="org-string">"outline-2"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">section 1 </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
<<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"outline-container-2"</span> <span class="org-variable-name">class</span>=<span class="org-string">"outline-2"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">section 2 </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
<<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"outline-container-3"</span> <span class="org-variable-name">class</span>=<span class="org-string">"outline-2"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">section 3 </span><span class="org-comment-delimiter">--></span>
<<span class="org-function-name">div</span> <span class="org-variable-name">id</span>=<span class="org-string">"bibliography"</span>>
<span class="org-comment-delimiter"><!-- </span><span class="org-comment">bibliography goes here </span><span class="org-comment-delimiter">--></span>
</<span class="org-function-name">div</span>>
</<span class="org-function-name">div</span>>
</pre></div><p>The problem is that the <code>#+BIBLIOGRAPHY</code> command is always ignored unless it is belonged to a section. <del>This is due to the internal implementation of keyword</del> <del>parser of <code>ox-html</code>. Currently hacking some post-processing code is the only</del> <del>solution if you do not want to do it manually</del>.</p><p>This problem is solved as follows.</p><ol class="org-ol"><li><p>Add the following snippet to your <code>init.el</code></p><div class="org-src-container"><pre class="src src-emacs-lisp"><span class="org-rainbow-delimiters-depth-1">(</span><span class="org-keyword">require</span><span class="org-whitespace-space"> </span>'<span class="org-constant">ox-extra</span><span class="org-rainbow-delimiters-depth-1">)</span>
<span class="org-rainbow-delimiters-depth-1">(</span>ox-extras-activate<span class="org-whitespace-space"> </span>'<span class="org-rainbow-delimiters-depth-2">(</span>ignore-headlines<span class="org-rainbow-delimiters-depth-2">)</span><span class="org-rainbow-delimiters-depth-1">)</span>
</pre></div></li><li>adding <code>ignore</code> tag to whichever headline you want to ignore. Note that this is different from the <code>COMMENT</code> in Org mode in that <code>COMMENT</code> ignores the head and contents in its section, while <code>ignore</code> only ignores the headline but keeps the contents when exporting. See the above template.</li></ol></div></div><div id="outline-container-org31ab5f9" class="outline-3"><h3 id="sec:wrong-back-reference"><a id="org31ab5f9" name="org31ab5f9"></a><span class="section-number-3">6.3</span> Wrong Back Reference</h3><div class="outline-text-3" id="text-sec:wrong-back-reference"><p>The links generated by <code>ox-bibtex</code> is also troublesome. Given <code>ref.bib</code>, <code>bibtex2html</code> will generate two files, <code>reb_bib.html</code> and <code>ref.html</code>. The utility <code>ox-bibtex</code> directly inserts contents of <code>ref.html</code> to the current exported html. Now when you click links in the exported html, you will be directed to <code>ref_bib.html</code>. And when expecting to get back to the exported html by clicking links in <code>ref_bib.html</code>, you will be instead directed to <code>ref.html</code>. My solution is to <del>remove the bibliograph source with <code>option:-nobibsource</code></del> replace the link in <code>ref_bib.html</code> with when compiling the HTML (see this <a href="https://github.com/gongzhitaao/orgcss/blob/master/gulpfile.js#L49">gulpfile.js</a>), it is a hacky way though.</p></div></div><div id="outline-container-org0fae9ed" class="outline-3"><h3 id="h2-fci-mode-issue"><a id="org0fae9ed" name="org0fae9ed"></a><span class="section-number-3">6.4</span> <code>fci-mode</code> Issue</h3><div class="outline-text-3" id="text-h2-fci-mode-issue"><p>If you use <a href="https://github.com/alpaker/Fill-Column-Indicator"><code>fci-mode</code></a>, 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 <code>Org-v9.1.14</code>) like the followings.</p><div class="org-src-container"><pre class="src src-c++"><span class="org-preprocessor">#include</span><span class="org-whitespace-space"> </span><span class="org-string"><span class="org-rainbow-delimiters-depth-1"><</span></span><span class="org-string">iostream</span><span class="org-string"><span class="org-rainbow-delimiters-depth-1">></span></span>
<span class="org-keyword">using</span><span class="org-whitespace-space"> </span><span class="org-type">namesapce</span><span class="org-whitespace-space"> </span><span class="org-variable-name">std</span>;

<span class="org-type">int</span><span class="org-whitespace-space"> </span><span class="org-function-name">main</span><span class="org-rainbow-delimiters-depth-1">()</span>
<span class="org-rainbow-delimiters-depth-1">{</span>
<span class="org-whitespace-space"> </span><span class="org-keyword">return</span><span class="org-whitespace-space"> </span><span class="org-highlight-numbers-number">0</span>;
<span class="org-rainbow-delimiters-depth-1">}</span>
</pre></div><p>I did not have this issue with previous version of <code>org-mode</code> and <code>fci-mode</code>. Simply turning off the <code>fci-mode</code> for major mode solves the problem.</p></div></div></div><div id="outline-container-org3f25af7" class="outline-2"><h2 id="sec:conclusion"><a id="org3f25af7" name="org3f25af7"></a><span class="section-number-2">7</span> Conclusion</h2><div class="outline-text-2" id="text-sec:conclusion"><p>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 <code>ox-bibtex</code>, to which the simple solution is to use links instead of citations, if possible. Otherwise, hacking some post-processing code is necessary.</p></div></div><div id="outline-container-org3032670" class="outline-2"><h2 id="org3032670"><span class="section-number-2">8</span> Credits</h2><div class="outline-text-2" id="text-8"><p>Some styles are borrowed from the following projects.</p><ol class="org-ol"><li><a href="https://github.com/fniessen/org-html-themes">fniessen/org-html-themes</a></li><li><a href="https://gist.github.com/mowen/326524">mowen/gist326524</a></li><li><a href="http://demo.thi.ng/org-spec/">org-spec</a></li><li><a href="http://doc.norang.ca/org-mode.html">Organize Your Life In Plain Text!</a></li><li><a href="https://github.com/thomasf/solarized-cs">thomasf/solarized-css</a></li><li><a href="http://orgmode.org/worg/org-web.html">Web Pages Made with Org-Mode</a></li></ol></div></div><div id="bibliography"><h2>References</h2><table><tr valign="top"><td align="right" class="bibtexnumber">[<a name="dominik2003-org">1</a>]</td><td class="bibtexitem">Carsten Dominik and <a href="http://orgmode.org/org.html#History-and-Acknowledgments">many others</a>. Org mode for Emacs, 2003. [ <a href="ref_bib.html#dominik2003-org">bib</a> | <a href="http://orgmode.org/">http</a> ]</td></tr><tr valign="top"><td align="right" class="bibtexnumber">[<a name="gruber2004-markdown">2</a>]</td><td class="bibtexitem">John Gruber. Markdown, December 2004. [ <a href="ref_bib.html#gruber2004-markdown">bib</a> | <a href="http://daringfireball.net/projects/markdown/">http</a> ]</td></tr></table></div><div id="footnotes"><h2 class="footnotes">Footnotes:</h2><div id="text-footnotes"><div class="footdef"><sup><a id="fn.1" name="fn.1" class="footnum" href="#fnr.1">1</a></sup><div class="footpara"><p class="footpara">For note keeping, <a href="http://jblevins.org/projects/deft/">Deft</a> with Org mode make a cute couple.</p></div></div><div class="footdef"><sup><a id="fn.2" name="fn.2" class="footnum" href="#fnr.2">2</a></sup><div class="footpara"><p class="footpara">A <a href="http://doc.norang.ca/org-mode.html">great article</a> elaborates on this.</p></div></div></div></div></div><div id="postamble" class="status"><a class="author" href="http://gongzhitaao.org">Zhitao Gong</a> / <span class="date">2018-12-09 Sun 11:23</span><span class="creator"><a href="https://www.gnu.org/software/emacs/">Emacs</a> 25.2.2 (<a href="https://orgmode.org">Org</a> mode 9.1.14)</span></div></body></html>