Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thi-ng/org-spec

Org-mode skeleton for technical specifications & HTML theme
https://github.com/thi-ng/org-spec

Last synced: 28 days ago
JSON representation

Org-mode skeleton for technical specifications & HTML theme

Awesome Lists containing this project

README 

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