Home

Awesome

Technical Markdown

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

History rewritten: Due to LFS mistakes, main branch was rewritten and a reclone of this repository is needed.

Note: A docker build setup has been implemented! Read more in here.

Check the Changelog.md for the latest changes.

Demo

Quick Intro

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

Quick-Start

Execute the following in a shell:

./gradlew -t build-html

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

Demo Project

There is also a demo showing a full thesis project.

Rational

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 ridiculuous dynamic, interactive styling. Collapsable table of contents is just the beginning.
    • LaTeX enables to produce 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. Writting technical documents should become a breeze.

  3. The common agreement in the industry about using M$ Office for writting 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". experiences, a lot of time and money is spent which gets never debated.

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

  4. Every technical document writter 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:

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

Dependencies

If you have docker, you should directly open this project in VS Code with the provided .devcontainer setup which gives you a hassle free experience. See Docker Setup for more information. Building on a native system, you need the following dependencies:

Gradle

For the Gradle build tool you need a working Java runtime. On Linux and macOS you can do:

brew install java

You should not need to install Gradle, since everything is setup by the checked-in gradlew Gradle wrapper.

Yarn

So far yarn is not required on the system and handled by the dependent Gradle task yarnSetup. If you experience problems with having the node modules not correctly setup, use

cd tools
../build/techmd/yarn/bin/yarn install --modules-path build/techmd/node_modules

Pandoc

Install pandoc (>= 2.9.2.1, tested with 2.16.2)

For Linux and macOs:

brew install pandoc pandoc-crossref

For Windows:

choco install pandoc

Python

Install a recent python3 (>= 3.9) and the following packages.

Setup a python environment in .venv with python -m venv --system-site-packages ./.venv and install the packages:

python -m venv --system-site-packages .venv # or simply symlink to an existing one.
source .venv/bin/activate
pip3 install -r tools/docker/setup/python.requirements

The VS Code tasks pass the config ${config:python.pythonEnv} directly as an argument to gradlew (if not set python is the default). The tasks are run in a shell where ./.venv/bin/activate has been called. Then, pandoc will use the correct python when launching the filters.

You can also use the ignored .envrc file with direnv.

Building and Viewing

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

Docker Build

We provide 2 images based on pandoc/latex:2.18-alpine in gabyxgabyx/technical-markdown:

  1. gabyxgabyx/technical-markdown:latest-minimal : Minimal docker images including pandoc and all necessary tools to fully build your markdown. It does not include the folder tools and convert and your mounted Git repository needs to contain these as in this repository or by setting the environment variables described below. This is useful if you want to tweak the layout and styling of the document.
  2. gabyxgabyx/technical-markdown:latest : The full-fledged image which is used in this VS Code .devcontainer setup. It contains its baked tools and tools/convert folders which are used to compile your markdown.

The <version> above corresponds to either latest or the Git version tag minus the v prefix.

Environment Variables

Numbers refer to the container images above:

Env. NameDefault ValueDescription
TECHMD_TOOLS_DIR1. not setThe tools directory containing all files needed for the conversion.
2 . /home/techmd/technical-markdown/tools
TECHMD_CONVERT_DIR1. not setThe convert directory containing the files needed for the pandoc converstion.
2 . /home/techmd/technical-markdown/tools/convert
TECHMD_USE_SYSTEM_NODE1. trueUse the node installation on the system instead of installing a local one into the build folder
2. true

Using the Docker Image

Either copy the .devontainer to your project (you don't need the tools folder) and open the project in the VS Code remote container extension.

Alternatively you can always use:

docker run -v "<path-to-your-repo>:/workspace" \
    gabyxgabyx/technical-markdown:latest"
    ./gradlew build-html

Extending the Technical-Markdown Docker Images

If you need special other tools and an other setup which might be useful for the general images above, consider submitting an issue. Otherwise you can always extend the existing images for layout/styling changes with another Dockerfile like:

FROM gabyxgabyx/technical-markdown:latest-minimal as mycustomtechmd
// More Dockerfile commands ...

Building the Technical-Markdown Docker Images

To build the images in this repository for customization use:

tools/docker/build.sh \
    --base-name "mycustomimage" \
    [--push-base-name "docker.io/superuser"] \
    [--push]

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.

LaTeX

The following templates are responsible for the LaTeX output:

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

Panflute [done]

Using pandoc >=2.10 we have more types and AST changes in

meaning that also the python library panflute needs to be supporting this:

Transclude: Relative file paths [done]

So far relative paths are not yet supported in pandoc-include-files.lua filter.

Table Issues [done]

Todo

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:

paypal