Stephan Brosinski

2013-11-22 (fe88fa1)


Uberdoc is a wrapper script for Pandoc which provides a build system to turn a number of e.g. markdown files into large documents.

I use it to write technical documents. Default output is HTML. Optionally it generates a nicely formatted PDF using LaTex.

The provided default templates are just a starting point. These should be personalized for custom, e.g. client specific documents.

Directory Layout

Uberdoc uses the following directory layout for your document.

in                      --> contains the document's chapters
        img             --> optional image files for this chapter
        chapter1.md     --> markdown content for this chapter
    toc.txt             --> reference of all chapters and their order

styles                  --> optional css styles etc.
templates               --> optional html and latex templates (for PDF conversion)

out                     --> your doc ends up here


Initializing a new dir for uberdoc, this creates a sample document and config file

$ udoc init
Copying default config file ...
Creating dir structure and sample chapters ...

Create a git repo for current document, provide an initial gitignore and commit

$ udoc git
Initializing git repo in current dir and adding files ...
git init
git add .gitignore
git add in
git add uberdoc.cfg
git commit -m "setup uberdoc document"

Create document, use -p for PDF output in addition to HTML

$ udoc build
Check environment ...
Cleaning ...
Parse toc ...
Copy dependencies ...
Generating document ...
Done ...

Open new document in browser or PDF viewer

$ udoc show

If you want to customize the default HTML/Latex templates or CSS styles, run this command to create a copy of the default templates for your document. Then edit the files in ./templates or ./style.

$ udoc customize
Creating templates ...
Creating styles ...

This scans the document's toc.txt table of contents file, shows which chapter directories exist in in the document dir, creates new chapter dirs and offers (with --delete) to remove chapters which are not in the table of contents anymore:

$ udoc outline
Exists: chapter1 -> ./in/chapter1/chapter1.md
Exists: chapter2 -> ./in/chapter2/chapter2.md
Exists: chapter3 -> ./in/chapter3/chapter3.md
Creating: chapter4 -> ./in/chapter4/chapter4.md

$ udoc outline --delete
Exists: chapter1 -> ./in/chapter1/chapter1.md
Exists: chapter3 -> ./in/chapter3/chapter3.md
Exists: chapter4 -> ./in/chapter4/chapter4.md
Missing: chapter2 -> ./in/chapter2/chapter2.md
Remove chapter2? (y/N):

You can place a # in front of a TOC entry to disable a chapter or a ! to force Uberdoc to only consider this chapter. This way you can for example only build a subset of your document, or, using the outline command easily remove certain chapters.

If Pandoc or Uberdoc throw errors, run this command to check if your document setup is okay.

$ udoc check
Loading config: uberdoc.cfg
Config settings:
  doc_dir = .
  in_dir = in
  out_dir = out
  img_dir = img
  style_dir = style
  toc_filename = toc.txt
  doc_filename = concept
  input_ext = .md
  pandoc_cmd = pandoc
  pandoc_options_html = -s --default-image-extension=png --template=../templates/default.html
  pandoc_options_pdf = -s --default-image-extension=pdf --template=../templates/default.tex --toc --number-sections -V "geometry:top=2cm, bottom=3cm, left=2.5cm, right=2cm"
Document version: 2013-10-10 (dc89484)
Environment setup ok.




The easiest way would be pip:

pip install uberdoc

You can also clone this repository and run

python setup.py install


You may change uberdoc.cfg as follows:


# dir for chapter content
in_dir = src

# build output dir
out_dir = out

# chapter image folder name
img_dir = img

# dir for css styles
style_dir = style

# file name of table of contents file
toc_filename =toc.txt

# base name for resulting document
doc_filename = concept

# extension for chapter files, default is Markdown
input_ext = .md

# pandoc command, needs to be in path
pandoc_cmd = pandoc

# pandoc conversion options for html
pandoc_options_html = -s --template=../templates/default.html

# pandoc conversions options for pdf
pandoc_options_pdf =  -s --template=../templates/default.tex --toc --number-sections -V geometry:"top=2cm, bottom=3cm, left=2.5cm, right=2cm"


Uberdoc uses nose for testing and tox to run tests for different Python versions.

Just run either

$ nosetests

$ tox

Ideas for improvement

Now start writing and stop messing with your tools!

Extending the Markdown Syntax

Uberdoc uses a templating engine to allow user to extend the markdown syntax used in its chapter files.

Predefined Variables

The following variables are provided by Uberdoc and can be used in markdown files by e.g. adding

Variable Value
md_file templating/templating.md
version 1.2.2
doc_version 2013-11-22 (fe88fa1)

Custom Variables

Variable Value
doc_dir .
b c


Defining a macro in your markdown document:

{% macro todo(description) -%}
> *TODO:* {{description}}
{%- endmacro %}

Calling the TODO macro:

{{todo('this needs to be rewritten!')}}

results in:

TODO: this needs to be rewritten!


Or using filters:

{% filter upper %}
This text becomes uppercase
{% endfilter %}



Or including other markdown files:

{% include 'templating/some.md' %}

This is a seperate markdown file some.md being included by the Templating Demo chapter