Emacs Org Mode for Documentation

I've heard people raving about Org Mode in emacs circles for years now. Finally I had a reason to try it lately and it absolutely lives up to the hype!

I have been using it to write documentation, specifically a book about the Flavour framework for Java-based SPAs. It easily handles the key things I want from a technical documentation authoring tool:

Read on for tips on using Org Mode for documentation

Fundamental Organization

For a book, I wanted a main file listing the chapters, with a separate file for each chapter. In Org Mode this is easily handled with includes. Here is the code in the main file to include the first chapter:
* Introduction
#+include: ""
To create a heading, use M-enter.

Embedded Code Samples

To start a code sample, type C-c C-, s. Then type the kind of code (java, html, xml, etc.). Then your sample goes between the begin and end tags.
#+begin_src html
<html:text value="username" />
For method names or other code referenced inline, surround the code with tildes:
It launches the ~main()~ method

Easy publishing to HTML

To export to a single HTML file, type C-c C-e h h. You'll get one HTML file containing all included .org files.

For syntax highlighting in code samples to work, I had to add this at the top of my main document:

# -*- org-export-allow-bind-keywords: t -*-

Easy publishing to PDF

For a PDF file, type C-c C-e l p.

You'll need to have LaTeX installed. For me, installing LaTeX was straightforward:

sudo apt install texlive-latex-extra

Last modified on 10 Dec 2023 by AO

Copyright © 2024 Andrew Oliver