thi.ng/org-spec

An Org-mode template for technical specification documents and HTML publishing

Features

• Specification document skeleton for a web application, incl. usage examples of various org-mode features:
  • Inline, text-based diagramming via Ditaa, Graphviz & PlantUML
  • Hyperlink abbreviations (incl. presets for GitHub, RFC, W3C, Wikipedia)
  • Section status flags, tags & custom properties
  • Tables
  • Named section IDs for internal x-refs
  • Footnotes
  • Automatically updating fields (e.g. publication date)
  • Automatic updating of document changelog (using git commits)
• Beautiful, minimal, responsive CSS theme with print support (also for PDF generation)
• Basic syntax highlighting of code blocks

Example output

Take a look at the published version of the included demo document:

http://demo.thi.ng/org-spec/

The corrensponding .org source file: https://raw.githubusercontent.com/thi-ng/org-spec/master/index.org

Getting started

The index.org source file contains everything (apart from CSS, which is located in the /css dir), including build instructions and further comments, not visible in the exported document.

You can use s3cmd to quickly publish the generated HTML version to AWS S3, like so:

# if you need to install s3cmd first
brew install s3cmd
s3cmd --configure

# optionally create a website bucket
s3cmd ws-create s3://BUCKETNAME

# only upload HTML, CSS & PNGs
s3cmd -P --recursive --exclude=* \
      --include=index.html \
      --include=*.css \
      --include=assets/*.png \
      put . s3://BUCKETNAME

Diagramming & exporting

The template heavily utilizes Org-mode’s noweb references to assemble diagrams from individual snippets, as well as to provide CSS-like functionality for diagrams by defining a single snippet (per diagram tool) containing global styles.

• http://orgmode.org/manual/Noweb-reference-syntax.html#Noweb-reference-syntax
• http://orgmode.org/manual/noweb_002dref.html#noweb_002dref
• http://orgmode.org/manual/noweb.html#noweb

The code blocks actually defining the full diagrams are all located in the last section of the document (titled “Diagram definitions”). This section is only present in the source code and will NOT be exported to HTML (however the code blocks are still evaluated during export and hence produce the diagrams each time).

If your doc contains a lot of such diagrams (especially PlantUML), then exporting can take quite a long while. To save time (and if you’re not currently working on diagram parts), you can temporarily disable the evaluation of ALL code blocks by setting the org-export-babel-evaluate to nil:

(setq org-export-babel-evaluate nil)

;; to re-enable...
(setq org-export-babel-evaluate t)

Custom property export

By default the template is configured to export only a specific set of properties stored in drawers attached to a section/sub-tree. The list of exported property names can be edited in line 4 of the template:

#+OPTIONS: prop:("VERSION")

To enable all properties:

#+OPTIONS: prop:t

License

MIT License, (c) 2016 Karsten Schmidt