Org-HTML Themes: two stylesheets that turn Org mode export into a real web page

The problem is one stylesheet, and this repository is that stylesheet

The README states the gap plainly: Org mode provides basic HTML support, and you can enhance a document's appearance by overriding CSS stylesheets and adding custom HTML themes. That is the whole premise. Nobody is asking you to change your Org workflow or adopt a different publishing pipeline. You keep the files you have and add a setup file that points at a stylesheet.

The repository is small in the way a design project should be. The tree holds README.org as the primary document, an org/ directory for the Org-specific files, src/ for the stylesheet sources, docs/ and images/ for screenshots, examples/ for demonstrations, and a TODO-org-html-themes.org file. There is also a _config.yml, which is the Jekyll configuration GitHub Pages uses to render the README.org into the project page you are probably reading.

That the documentation is written in Org and rendered by Org is a small consistency worth noting. The README is the export demo.

The only hard requirement is Org mode version 8 or later, and if your Emacs does not bundle that version you install one from ELPA. There is no build step, no package manager, and no generated artifact to run.

Bigblow treats the exported page as a reading tool

Bigblow is described as aimed at optimal Org mode experience in your browser, and the difference between it and a plain stylesheet shows up in what it binds to the keyboard. The README publishes the full shortcut table:

- `?` or `h` opens the dashboard - `n` and `p` move to the next and previous main heading - `b` scrolls up, `<` scrolls to top, `>` scrolls to bottom - `-` collapses all, `+` expands all - `r` and `R` move between tasks in a list, `q` stops reviewing - `g` reloads the page

That list is the design. An exported Org document with checkboxes becomes something you can work through in the browser, moving between tasks with `r` and stopping with `q`, without an editor open. The collapse and expand bindings apply the same idea to structure.

For a theme, this is an unusual amount of JavaScript. Most HTML themes for note tools are CSS and a highlight script. Bigblow is a small application, and the README links a 2:49 silent demo video so you can watch it work before deciding.

The theme is also tied to a specific aesthetic. One quoted user mentions not being able to use another emacs-theme than the author's emacs-leuven-theme, which suggests Bigblow inherits the same colours and proportions. If you already have an Emacs setup you like, that is a feature. If you want your exported HTML to match your corporate stylesheet, it is not.

ReadTheOrg is a Sphinx clone with an acknowledged mobile weakness

The second theme takes a different approach. ReadTheOrg is described as a clone of the official sphinx_rtd_theme used by Read the Docs, and the README credits its creators rather than claiming independent design. That framing tells you what you get: the familiar three-column documentation layout with a sidebar of headings and a content pane, applied to Org output.

The credit matters more than it might seem, because cloning a theme means inheriting its assumptions. The Sphinx read-the-docs theme was built for technical documentation with a predictable structure, and it assumes that structure is there.

The README is honest about where that falls down. A note block says the original theme works well on mobile devices while ReadTheOrg does not stay completely functional, and it explains why: the maintainer does not have a lot of time for the project because of other responsibilities, and asks for help on that front and on improving the default structure of the HTML export.

That note is the most useful sentence in the README for anyone deciding. It is an accurate statement of where the project sits: two themes, one actively developed, one stable but imperfect, both maintained by one person with a day job.

If you are publishing documentation that people read on a phone, test that before you commit. If you are publishing to an internal network where readers are at desks, ReadTheOrg is a good choice and Bigblow's keyboard map is probably irrelevant to you.

Both setup files changed name and then changed path, within six months

This is the part of the project that will actually bite you, and the README gives it two separate notice sections with dates.

The first change, dated 2026-01-24, renamed the setup files. The old names theme-bigblow.setup and theme-readtheorg.setup are deprecated and replaced by html-theme-bigblow.setup and html-theme-readtheorg.setup. The change makes the names more accurate, since they configure HTML export specifically.

The second change, dated 2026-07-10, moved all setup files into an org/setup/ directory. A SETUPFILE line that pointed at one location:

#+SETUPFILE: https://fniessen.github.io/org-html-themes/org/html-theme-bigblow.setup

now points at another:

#+SETUPFILE: https://fniessen.github.io/org-html-themes/org/setup/html-theme-bigblow.setup

The same applies to the ReadTheOrg setup file. What makes this manageable is the backward compatibility path: Org files using the old names still work, but a warning banner is injected into the exported HTML page telling you what to change. That is a good design choice, because a silent break would have left you with stale setup files you never discovered, and a hard failure would have broken existing exports. The banner is visible only in the output, which is exactly where you would look.

The README's own header uses the new layout, loading both a readtheorg setup file and a latex-listings setup from ~/org/setup/, which confirms the new directory structure is the intended one. Note the URL form and the local form differ, so you can vendor these files locally if you prefer not to depend on the hosted version at export time.

A syntax reference page is the honest way to pick a theme

The README points to a demo page it calls the Org mode syntax reference, which provides what it describes as a maximal working support of Org mode syntax. That page exists as four files in the examples directory: org-mode-syntax-reference.org, the rendered .html, a .pdf, and a .tex.

Shipping the PDF and the TeX source alongside the HTML is the detail that makes this useful. It means you can see the same document in three output formats and compare, rather than squinting at a screenshot of someone else's markup. For a project whose entire purpose is styling one exporter, that is the right artifact to provide.

Two more example files cover the other themes' strengths. org-mode-task-management.org exercises the checkbox and task-list features that Bigblow's `r` and `q` bindings are built for, and org-mode-theme-preview.org gives a side-by-side look at the themes.

The README also links out to a separate refcard-org-mode page for full examples of headings, code, admonitions, footnotes, and tables. Between the two, you can see how every Org construct renders before committing to a stylesheet for your own documents.

If you are choosing, start there. Reading CSS tells you what the theme could support; reading a syntax reference page tells you what it does support on the constructs you actually write.

No releases, one maintainer, and a GPL-3.0 licence

The repository publishes no GitHub releases, so there is no version number to pin and no changelog to read. What you get is commit history on master and the dated notices in the README, which is how you learn that the setup files moved on 2026-07-10 and were renamed on 2026-01-24.

That absence is a fair signal about the project's shape. It is a styling project with two themes, maintained by Fabrice Niessen, whose contact details in the README are obfuscated in typical Org fashion as a concat expression rather than written out plainly. The last push was on 2026-09-26, so the work is current rather than abandoned.

The licence is GPL-3.0, and the README displays it with a shields.io badge plus a PayPal donation link for the project. GPL on a collection of stylesheets is stricter than you might expect if you were planning to fold a theme into a commercial product's asset pipeline, since copyleft applies to the stylesheet as a distributed work. If you only want to use it to export your own documents, which is what it is for, this does not come up.

The maintainer asks users to get in touch if they use the project, saying it helps suggest directions for the code and may inspire other developers. Given the TODO file in the tree and the explicit request for help with ReadTheOrg on mobile, that request is aimed at a specific gap rather than general recruitment.

Editorial conclusion

Org-HTML Themes solves a narrow problem properly. Org mode's built-in HTML export is functional and plain, and adding a stylesheet is all it takes to get a document that looks deliberate, which is what these two themes do. Bigblow is the more interesting of the pair because it ships a keyboard map and a dashboard, so the exported page behaves like a tool rather than a document. ReadTheOrg is a faithful clone of the Sphinx read-the-docs theme and the author notes it degrades on mobile. Two things to check before you rely on it. The project publishes no GitHub releases at all, so version tracking comes from the repository rather than from tags. And both setup files were renamed on 2026-01-24 and then relocated under org/setup/ on 2026-07-10, so an older Org file will export with a warning banner injected into the page until you update the SETUPFILE path.

Frequently asked questions

Official sources

1. fniessen/org-html-themes on GitHub
2. Issues
3. License: GPL-3.0
4. README