org-page: a static site generator that publishes an Org repository from Emacs

Sources in one branch, published HTML in another

org-page is a static site generator based on org-mode, written by Kelvin Hu, with the document dated 2012-08-23 in its header. The very first line of the README is an apology: the project is not under active development any more.

The repository description says the same thing more bluntly, marking it as inactive, and it lives under the emacsorphanage organisation, which is the home for packages whose original maintainers have moved on. The last push was on 2026-07-21.

The central idea is worth understanding regardless. You keep your Org sources and the generated HTML in the same git repository, on different branches. The sources live on a source branch and the generated files are published to a master branch, and the branch names are configurable. The README points at the author's own personal site as an example of a site generated this way, with the Org sources and the HTML in one repository.

The publication cycle is six steps. You specify the base commit, the most recent prior one being used if you omit it, and org-page reads the changes between the latest commit and that base on the source branch. The changes are marked for publication, preparation jobs run, and then the changes are published, which can be an addition, a modification or a deletion. The index page for each category and tag is updated, and publication finishes.

That the third step is marked as a separate phase, and that the fourth is where additions, modifications and deletions all come together, is where the design is either elegant or fragile, and the README tells you which.

A convenience command, op/new-repository, creates a repository set up this way, so the initial state does not have to be assembled by hand.

A dozen generated features, and the ones you do not have to build

The feature list is numbered to thirteen, and several of the entries are the reason a static site generator is worth using at all.

Org sources and HTML files managed by git, and incremental publication according to the git diff command, are the foundation described above. On top of that there is category support, auto-generated tags support, auto-generated RSS support, auto-generated search engine support, and a beautiful theme with theme customization support.

The rest covers what a site needs once the content pipeline works. Commenting is implemented using disqus, duoshuo or hashover, and the configuration shows all three being set at once, which is how the original author probably ran it. Website traffic analytics uses Google Analytics. An index and about page are auto-generated if no default is provided, and there is a site preview.

The search engine support is the entry that deserves a second look, because a client-side search index over your own content is a piece of infrastructure most people never build. A generated index means the search box on the site works without a server, which matters for a static site on a host with no search capability.

The theme lives in its own directory in the repository, and the customization support means the theme is not a fixed asset but something you adjust. The whole list describes a generator aimed at someone who writes in Org mode and wants a complete site rather than a blog engine with a few options.

The documentation is in the doc folder, and the README points to quick-guide.org in there for a more detailed introduction and configuration.

Installation through MELPA and a handful of setq lines

org-page is available from melpa, and the recommended installation is through Emacs' package management system. For the more detailed introduction, the README points at quick-guide.org in the doc folder.

The configuration is a block of settings in your .emacs file. The first lines are only needed if you install org-page manually rather than through the package system, and they put the checkout on the load path and require the package:

   : (add-to-list 'load-path "path/to/org-page")
   : (require 'org-page)
   : (setq op/repository-directory "path/to/your/org/repository")
   : (setq op/site-domain "http://your.personal.site.com/")

The two settings that matter are op/repository-directory, which points at the git repository holding your Org sources, and op/site-domain, which is the address the generated site is served from. The commenting options follow, and each of the three comment services has a variable, with op/hashover-comments set to t to switch that service on. The analytics identifier is last and optional.

Publishing is an evaluation of a function. The full form takes arguments, and the short form takes none:

   : (op/do-publication nil "HEAD^1" "~/org-pub/" nil)

   : (op/do-publication)

It can also be run from the keyboard with M-x op/do-publication and a return. There is one caveat that will catch you the first time, and it is bold in the README: org-page does not commit your Org files to git, so you have to commit them manually before you run the command. The generator publishes what is already committed, and it will not stage or commit for you.

The preview path is a single command, M-x op/do-publication-and-preview-site, which publishes into a temporary directory called ~/.op-tmp/ and then previews it in the browser.

Nine dependencies, and four of them are libraries you may not have

The dependency list is where a project of this age and this ambition shows its cost, and it is worth reading before you install.

Emacs is the obvious one, and org-mode is required at version 8.0 or later, with M-x org-version and a return as the way to check. Git is required, obviously, since the whole model is a git repository with two branches.

Then come the libraries. mustache.el is a mustache templating library for Emacs, which is what the theme system is built on. htmlize.el provides syntax highlighting, and the README notes that it is usually shipped with Emacs. dash.el is a modern list library and ht.el a modern hash table library, both of which are conventional choices for modern Elisp but not part of Emacs itself.

simple-httpd, a simple Emacs web server, is required for the site preview, and git.el is an Elisp API for programmatically using Git, which is how the tool reads the diff without shelling out for everything.

So the count is nine, and the ones most likely to be missing are mustache.el, dash.el and ht.el, since they are separate packages rather than standard library code. MELPA handles the packaging, and the README does not enumerate which of the dependencies come with the package and which you have to install yourself.

The repository layout shows the code split by concern, which is a good sign for reading it. There is org-page.el as the main entry point, op-export.el for the export side, op-git.el for the git interaction, op-template.el for the templating, op-enhance.el, op-util.el and op-vars.el for the variables and helpers, and a themes/ directory. The file naming makes it clear where to start reading if you want to understand the diff-driven publication.

Deletions and renamed URIs are the two known holes

The known issues section names two problems, and both are the kind that produce confusion rather than errors.

The first is deletion. The change handler for deletions has not been implemented, so if you delete some Org sources you may have to delete the corresponding generated HTML files by hand. The README repeats this in the workflow section, where it notes that org-page is designed to handle additions, modifications and deletions but that since deletion does not happen often it has not been implemented yet. That is an honest statement of a gap with a rationale attached, and it is also a statement of what will happen to you when you reorganise.

The second is URI path change detection, which is not available at all. The example is a post published at a path like /blog/2013/03/25/the-old-post-name, and if you later change that value in the Org source, org-page cannot detect it. What it does instead is publish a new HTML file, so the old file for the old URI stays on disk and you have to delete it yourself. The practical consequence is that changing a published URL leaves a stale page live, which matters if the old address is indexed or shared.

Both known issues share a shape. The tool is good at the common case, which is adding and modifying, and it leaves the rare cases to the operator. Since the project is no longer being developed, those gaps are unlikely to be filled, which means a workflow that deletes or renames content needs a manual step after publishing, and that step is easy to forget.

One more thing is worth noting for anyone considering this today. The package name is org-page, the author is Kelvin Hu, and the maintained successor for people who want this today would be a different tool, since the dependency on a specific org-mode version and a set of Elisp libraries is what makes the abandoned version awkward to install cleanly.

Editorial conclusion

org-page is worth reading if you write in Org mode and want your site to be the same repository as your notes, because the design of a source branch and a master branch with a diff-driven publish is a genuinely pleasant arrangement, and the auto-generated index, tag pages, RSS and search are the parts you would otherwise write yourself. It is the wrong tool if you need a maintained generator, because the README opens by saying the project is not under active development any more, and it is the wrong tool if you delete and rename source files, because both of those cases are listed as known issues with no implementation. Before you rely on it, verify three things yourself: that the org-mode version on your machine is at least 8.0, which the dependency list requires, that your Emacs can load the optional libraries it needs, since mustache.el, htmlize.el, dash.el and ht.el are not all guaranteed to be present, and that your content workflow does not depend on deletions or on renaming a post's URI, since the README states deletion is not implemented at all and URI path change detection is unavailable, both leaving stale HTML behind for you to remove by hand.

Frequently asked questions

Official sources

1. emacsorphanage/org-page on GitHub
2. Issues
3. README