#+TITLE: thi.ng/org-spec

An [[http://orgmode.org][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 [[http://ditaa.sourceforge.net][Ditaa]], [[http://graphviz.org][Graphviz]] & [[http://plantuml.com/][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:

#+BEGIN_SRC shell

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 #+END_SRC

• 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=:

#+BEGIN_SRC emacs-lisp (setq org-export-babel-evaluate nil)

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

• 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:

#+BEGIN_SRC org #+OPTIONS: prop:("VERSION") #+END_SRC

To enable all properties:

#+BEGIN_SRC org #+OPTIONS: prop:t #+END_SRC

• License

MIT License, (c) 2016 Karsten Schmidt