Building an Org Mode Website: Part 2

Published: July 2, 2025

Streamlining the HTML Code

If you do not set any options in the org-publish-project-alist variable, Org Mode will by default include a lot of extra code in the files that it generates. This includes some predefined styles, extra numbering, and even some Javascript code. I prefer to have quite a bit of control over how my HTML code is structured and also that it is as minimal and straightforward as possible. With that in mind, we are going to strip down the code as much as possible and then build back in those parts that might actually be useful for our purposes. Here are the initial options that we will added to code to minimize the output.

Step 1

These first two options were turned off by the initial example code used in Part 1.

Section Numbers (:section-numbers nil)

The Org Mode export function adds section numbering to the headers. We might add that back in later, but for now we will turn it off with by setting :section-numbers to nil.

Table of Contents (:with-toc nil)

By default a table of contents is generated for each file. This is not a table of content for the website, but rather a table of contents for each individual file. Our initial posts will not be long enough to need this so we will turn it off by setting :with-toc to nil. Here it is important to note that most of these settings can be reenabled on a per file basis. If we do ever have a long article, the table of contents gneration can be enabled for that file if desired.

Step 2

The Exporting section of the Org Mode manual includes an example of what options to set to get 'a minimal HTML file'. We will next include those options.

HTML Document Header (:html-head "")

The Org Manual describes this setting as "Arbitrary lines for appending to the HTML document's head". We will set that to an empty string.

Default Style (:html-head-include-default-style nil)

Emacs includes a built-in stylesheet template. Using this feature will inculde the style information within each generated file. We will everntually being using our own style sheet. It will also be a separate file to keep styling code separate from the content structure so this will be set to nil.

Code Highlighting Javascript (:html-head-include-scripts nil)

This feature uses some Javascript snippets to enable higlighting of references in code blocks. The script that is included is defined in org-html-scripts. Something else that we will drop for now by setting to nil.

Preable and Postamble (:html-preamble nil :html-postamble nil)

If html-preamble or html-postamble are set to t then the HTML export function will use org-html-preamble-format and org-html-postamble-format respectively to insert a string as the pre- or postamble. If the variables are set to a string or a function that returns a string then that text will be used instead. Postamble can also be set to 'auto' in which case the exporter will build postamble using the author's name, email address, creator's name, and date. If either is set to nil then nothing is exported for that section.

Org-Info Javascript (:html-use-infojs nil)

Emacs includes a javascript file that provides either a Info-like or a Org Mode folding like view of the webpage. This would mainly be useful for longer complicated articles which I am not anticipating at the moment. Setting it to nil turns it off all the time. By default it is set to 'when-configured' which will cause the script to be included whenver there is a "#+INFOJS_OPT:" line in the file.

Step 3

One additional settings to help minimize and streamline the code. This may already not be generated as a secondary effect of everything we turned off above.

HTML Validation Link (:html-validation-link nil)

During the early days of html when the standard was rapidly evovling it was common to advertise which version of the standard your webite was compliant with and to provide a link to a website that would validate that your html was indeed compliant with the standard. This was somewhat important when browser support for html standards was very inconsistent. If the page validated as compliant, but did not look correct then the problem must be with the browser. Not something needed now so we will set it to nil.