Technical Markdown

A markdown setup for technical documents, reports, theses & papers.

Check the Changelog.md for the latest changes.

Quick Intro

This is a markdown setup demonstrating the power and use of markdown for technical documents:

• Fully automated conversion sequence with pandoc such that exporting (content.md) is done in the background:

  • export to PDF with pandoc to xelatex using latexmk See Output
  • export to HTML with pandoc to html See Output, See Live Output

• Pandoc filters for different AST (abstract syntax tree) conversions:

  • own filters with panflute [doc]
  • --crosscite [doc] for citing
  • pandoc-crossref [doc] for cross referencing
  • pandoc-include-files [doc] for file transclusion

• Full-fledged VS Code setup to write and style your document (nvim is better 😏).

Quick-Start

Note

You need nix installed on your system. Also direnv is suggested.

With Nix

• Activate the shell:

direnv allow && direnv reload
# or
just develop
# or
nix develop ./tools/nix --no-pure-eval

• Build the HTML output:

just build html

This will build the HTML output from its markdown main file.

Serve all conversions with process-compose by doing:

just serve

With Container

TODO: not yet refurbished.

Demo Project

There is also a demo showing a full thesis project.

Warning

The demo is still in v2 and only here as a reference, it worked with pandoc 2.x.

Rationale

Pandoc is awesome and the founder John MacFarlane develops pandoc in a meticulous and principled style. The documentation is pretty flawless and the community (including him) is really helpful. That is why we rely heavily on pandoc.

1. We target the output formats html5 and latex, because

   • HTML can be viewed in all browsers and web standards such as CSS3 etc. have become a major advantage and enables ridiculous dynamic, interactive styling. Collapsible table of contents is just the beginning.
   • LaTeX enables producing high quality output PDF (xelatex). Every proper book and distributed PDF is written and set in LaTeX.

2. The orchestration around calling pandoc is basically only a file watcher gradle which calls pandoc on file changes. We want as little as possible different tools to achieve the above output formats. That also means we do not want to have lots of pre- and post-processing tasks aside from running pandoc. The main goal is, that users can write markdown as a first-party solution with some enhanced features enabled by pandoc itself. Writing technical documents should become a breeze.

3. The common agreement in the industry about using M$ Office for writing technical documentations as demonstrated here, is considered the most complete and utter bullshit you can adhere to. Certainly employees mostly must obey. The common argument is "people need to exchange documents and work on it". In our experience, a lot of time and money is spent which never gets debated.

   It's about high time to turn into a direction which will likely become the standard. Technical writers should really focus on the content they write and not focus on styling quirks and tricks.

4. Every technical document writer probably knows about source code management (git). There you go with proper team work.

Project Layout

The following directories of a single project in src (e.g. src/techmd) are important for the content of the output:

• content.md : The main markdown document.
• chapters : All markdown source included in the main markdown document.
• files : All additional files referenced in the markdown documents in chapters.
• literature : All bibliography/literature related files (e.g. bibliography.bib).
• includes : Special include files (e.g. MathJax definitions) and other project related build tooling files which act as input files to the pandoc build process.

The following directories are important for the styling of the output:

• tools/convert : The main tools directory containing pandoc related output configs. It acts as pandoc's data-dir. See env. variables in docker builds.
  • tools/convert/defaults : pandoc defaults .
  • tools/convert/includes : pandoc templates for HTML and PDF output settings.
  • tools/convert/css CSS styling for HTML output.
  • tools/convert/filters : pandoc filters for modifying pandocs abstract syntax tree.
  • tools/convert/scripts : Some workaround scripts for converting tables based on a config file in

Building and Viewing

Run the following tasks defined in tasks.json from VS Code or use the following shell commands:

• Show HTML Output: Serves the HTML for preview in a browser with autoreload:

  just main view-html

• Convert Markdown -> HTML: Runs the markdown conversion with Pandoc (html) continuously:

  just build html

  • The conversion with pandoc applies the following filters in defaults.
  • The HTML output can be inspected in content.html.

• Convert Markdown -> PDF: Runs the markdown conversion with Pandoc (latexmk and xelatex) continuously:

  just build pdf

  • The conversion with pandoc applies the following filters in defaults.
  • The PDF output can be inspected in Content.pdf.
  • The LaTeX output can be inspected in build/output-tex/input.tex.

IDE Editors

VS Code

TODO: refurbish and test

Docker Build

TODO: refurbish to v3.

• Version v2

Editing Styles

HTML

• You can edit the main.less file to change the look of the markdown. Edit the main.less file to see changes in the conversion from content.md.
• pandoc-latex.yaml: The pandoc defaults for the HTML conversion.

LaTeX

The following templates are responsible for the LaTeX output:

• pandoc-latex.yaml: The pandoc defaults for the latex conversion.
• Latex template: The main templates.

Pandoc Filters

Pandoc filters are harder to debug. There is an included unix-like tee.py filter which can be put anywhere into the filter chain as needed, to see the AST JSON output in the folder build/pandoc-filter-out (see dev.py for adjustments). The filter teeStart.py first clears all output before doing the same as tee.py. Uncomment the tee.py filters in pandoc-filters.yaml.

Issues

• Pandoc v2 issues

Todo

• Add CI.
• Add tests.
• Add prince conversion to PDF.

Support & Donation

When you use Githooks and you would like to say thank you for its development and its future maintenance: I am happy to receive any donation:

🌻 Sponsor Me 🌻