An Org-mode template for technical specification documents and HTML publishing
- 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
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
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
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)
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
MIT License, (c) 2016 Karsten Schmidt