Adliance QmDoc

What is QmDoc

QmDoc is used by Adliance GmbH to automatically convert Markdown files to nicely formatted PDF files including corporate design guidelines.

Installation

QmDoc is a .NET Core global tool. You'll need .NET 10 installed in order to install and use QmDoc.

Open your commandline and call

dotnet tool install -g Adliance.QmDoc

to install QmDoc, or call

dotnet tool update -g Adliance.QmDoc

to upgrade it to the latest version.

Usage

Once QmDoc is installed, you can convert all Markdown (*.md) files in a directory by calling QmDoc in that directory. You may also specify files or directories by using the --source parameter:

qmdoc --source "c:\users\me\project\documentation"

or

qmdoc --source "c:\users\me\project\documentation\my_awesome_document.md"

By default, only Markdown files directly inside the source directory are converted. Add --include-subdirectories to also look into all of its subdirectories:

qmdoc --source "c:\users\me\project\documentation" --include-subdirectories

QmDoc supports the following commands:

• pdf (default command) converts Markdown to PDF.
• html converts Markdown to HTML.
• pdf-and-html converts Markdown to both PDF and HTML at once.
• pdf-and-html-and-markdown does the same as pdf-and-html, but additionally stores the processed Markdown (after all includes, placeholders etc. have been applied) that is fed into the HTML conversion. The target directory must differ from the source directory, otherwise the source files would be overwritten.
• docx converts Markdown to DOCX (only supports a subset of features compared to the PDF/HTML conversion).

For example, to convert to both PDF and HTML:

qmdoc pdf-and-html --source "c:\users\me\project\documentation"

Call

qmdoc --help 

to see all commands and parameters.

Themes

QmDoc supports multiple themes which can be used to easily create PDF documents that match the different corporate designs of clients or projects.

For example

qmdoc set-theme --theme Adliance

to switch to the Adliance theme. Themes are automatically downloaded from the GitHub repository and cached locally in the USERPROFILE\.qmdoc\themes directory. Please note that it may take a few minutes until changes of the theme on GitHub are picked up by your local installation of QmDoc.

You can also set the theme for a single conversion by using the --theme parameter. For example

qmdoc --theme ScientificDX

will convert all Markdown files in the current directory to PDF by using the "ScientificDX" theme.

Each theme must consist of 5 different files (index.html, footer.html, header.html, styles.scss, options.json) that specify the behaviour and look and feel of the resulting PDF files. If no theme is specified, a simple default theme will be used.

Features

See the Features Showcase Markdown file for all the nifty little features that QmDoc adds to Markdown.