Building an Org Mode Website: Part 3

Published: July 7, 2025

Starting to Build Up the Website

Now that the code produced by the org-publish function has been minimized as much as possible using the basic option settings, it is time start to building up the website.

HTML5

As a first step for this part we will configure what type of html code is generated.

Doctype (:html-doctype "html5")

The org mode exporter can generate several different types of html code. This is also more of a legacy feature from when the HTML standard was rapidly evolving. Now, in most cases, you should set the doctype to 'html5'. The variable 'org-html-doctype-alist' provides the details of what options are available.

HTML5 Style (:html-html5-fancy t)

The HTML5 standard also includes support for a more semantic structure of many document sections. Turning this option on enables those for many elements. With this option a block that begins with '#+begin_aside' will be wrapped in an '<aside>' tag. Without this option those blocks would be wrapped in a '<div class="aside">' tag. The variable 'org-html-html5-elements' contains the list of elements that are supported by this feature.

Styling the Website

If you export the webpages now the webpage will be displayed with the default styles of the browser. Functional, but does not present a very polished look.

Creating a Style Sheet

Looking at the generated HTML code you can see what elements are available for styling. I created a basic style sheet covering those elements and saved it as 'styles.css' in an 'assets' sub-folder.

Including CSS in the Export

The default publishing configuation that we began in Part 1 will only publish *.org files. To start including other types of files in the publishing action you need to establish config setting for those files. To do so, add something like the following to the org-publish-project-alist variable:

("org-assets"
   :base-directory "~/org/assets"
   :base-extension "jpg\\|gif\\|png\\|css"
   :publishing-function org-publish-attachment
   :publishing-directory "~/public_html"
   :recursive t)

Combining the Project Settings

With the 'org-assets' project added to the project list variable, the project is available for selection when you start the publish function. Most times you will probably want to publish both projects together. The org-publish-project-alist variable actually takes two types of project configurations. The first type we have seen in the previous two examples. The second type is a project that is a list of other projects. Selecting a project of that type with org publish function, publishes all the projects in its list. Here is what we will add:

("org-website"
   :components: ("org"
                 "org-assets"))

Linking to the Style Sheet

The final step in this part is to tell browser to use the style sheet we created above. This is done by style link code to the header attribute. Earlier we had set the html-head-extra option to the empty string. Now we will modify it like this:

("org"
 ;; ... (only relevant change is shown)
 :html-head-extra "\
<link rel=\"stylesheet\" type=\"text/css\" href=\"/style.css\""
 ;; ...
 )

This could have also been added to the html-head option. At this point it should not make any difference where it is placed.