HomeInstallationUsageIndexGitHub </> Reference

Reference

About this page

This page contains reference information like factual technical details and descriptions that are usually long and would unnecessarily overload the other pages if placed there.

Command line syntax

Here is the program's help (the Python example, the Java version will give a similar output):

>python %MD2HTML_HOME%/python/md2html.py -h
usage: md2html.py [-h] [--input-root INPUT_ROOT] [-i INPUT]
                  [--input-glob INPUT_GLOB] [--sort-by-file-path]
                  [--sort-by-variable SORT_BY_VARIABLE] [--sort-by-title]
                  [--output-root OUTPUT_ROOT] [-o OUTPUT]
                  [--argument-file ARGUMENT_FILE] [-t TITLE]
                  [--title-from-variable TITLE_FROM_VARIABLE]
                  [--template TEMPLATE] [--link-css LINK_CSS]
                  [--include-css INCLUDE_CSS] [--no-css] [-f] [-v] [-r]
                  [--legacy-mode]

Creates HTML documentation out of Markdown texts.

optional arguments:
  -h, --help            show this help message and exit
  --input-root INPUT_ROOT
                        root directory for input Markdown files. Defaults to
                        current directory
  -i INPUT, --input INPUT
                        input Markdown file name: absolute or relative to the '
                        --input-root' argument value
  --input-glob INPUT_GLOB
                        input Markdown file name pattern: absolute or relative
                        to the '--input-root' argument value
  --sort-by-file-path   If '--input-glob' is used, the documents will be sorted
                        by the input file path
  --sort-by-variable SORT_BY_VARIABLE
                        If '--input-glob' is used, the documents will be sorted
                        by the value of the specified page variable
  --sort-by-title       If '--input-glob' is used, the documents will be sorted
                        by their titles
  --output-root OUTPUT_ROOT
                        root directory for output HTML files. Defaults to
                        current directory
  -o OUTPUT, --output OUTPUT
                        output HTML file name: absolute or relative to '--
                        output-root' argument value. Defaults to input file name
                        with '.html' extension
  --argument-file ARGUMENT_FILE
                        argument file. Allows processing multiple documents with
                        a single run. Also provides different adjustment
                        possibilities and automations. If omitted, the single
                        file will be processed
  -t TITLE, --title TITLE
                        the HTML page title
  --title-from-variable TITLE_FROM_VARIABLE
                        If specified then the program will take the title from
                        the page metadata at the step of making up the input
                        file list
  --template TEMPLATE   template that will be used for HTML documents generation
  --link-css LINK_CSS   links CSS file, multiple entries allowed
  --include-css INCLUDE_CSS
                        includes content of the CSS file into HTML, multiple
                        entries allowed
  --no-css              creates HTML with no CSS. If no CSS-related arguments is
                        specified, the default CSS will be included
  -f, --force           rewrites HTML output file even if it was modified later
                        than the input file
  -v, --verbose         outputs human readable information messages
  -r, --report          turns on formalized output that may be further
                        automatically processed. Only if HTML file is generated,
                        the path of this file will be output. Incompatible with
                        -v
  --legacy-mode         Allows processing documentation projects prepared for
                        version of the program prior to 1.0.0. It's still
                        recommended to migrate the documentation projects to the
                        newer version

Here are some additional explanations:

• The --output argument. The program expects it to be defined as location relative to the program invocation current directory. This is required for possible further relative paths recalculations. The --input and the --template arguments are recommended to be defined the same way. Other variations were not tested so try them first if they are really required. See the recommended project structure for the example.

• The --input-glob argument. See [glob_wiki]. This syntax helps defining input file set like this: doc_src/*.txt that means "all files with txt extension in directory doc_src". doc_src/**/*.txt will mean the same but also subdirectories of directory doc_src will be scanned recursively.

• The --force argument. If it's not specified then only the input files that were changed since their previous processing will be processed. Specify this argument to forcibly regenerate all output files.

  Note

  Processing only changed files is faster but needs some caution. Changes in the template or page flows must be reflected in all output files that use this template, but if the input files are unchanged they will not be processed. This also applies to usage of GLOBs if page flows are used as well. If a new file is added to the folder or deleted from it the corresponding page flows will be changed and these changes must be reflected in all corresponding output files.

  So use -f option in any cases when there's a risk of breaking the documentation consistency.

• The --no-css argument. If nether --link-css nor --include-css is specified then the default CSS is included into the page. To avoid this, use --no-css argument; then no CSS will be used on the template resolution.

Argument file structure

Here is a very simple example of an argument file content:

{
    "documents": [
        { "input": "index.txt", "title": "Home" },
        { "input": "about.txt", "output": "about.html", "title": "Home" }
    ]
}

Here is a quite complex example of an argument file content:

{
    "options": {
        # This only affects the whole run verbosity, for now only printing execution duration.
        "verbose": true,
        "legacy-mode": false
    },
    "default": {
        # These are the default options for all documents.
        "input-root": "doc_src",
        "output-root": "doc",
        "template": "doc_src/templates/multipage.html",
        "no-css": true,
        "page-flows": ["sections"]
    },
    "documents": [
        { "input-root": "", "output-root": "", "input": "index.txt", "title": "Home" },
        { "input": "about.txt", "title": "About" },
        { "input-root": "tech_src", "output-root": "tech", 
            "input": "debug.txt", "output": "debugging.html", 
            "title": "Debug", "page-flows": [] }
    ],
    "plugins": {
        "variables": {"logo": "<img src=\"logo.png\" />" },
        "page-variables": {},
        "relative-paths": { "resource_path": "doc/" },
        "page-flows": {
            "otherLinks": [
                { "link": "https://daringfireball.net/projects/markdown/", 
                    "title": "Markdown Home", "external": true },
                { "link": "https://en.wikipedia.org/wiki/Markdown", 
                    "title": "Markdown Wiki", "external": true }
            ]
        },
        "index": {"index": {"output": "index_page.html", "title": "Index", 
            "index-cache": "index_cache.json" }
    }
}

Argument file format is JSON [json].

The following is the detailed argument file format description by sections:

options section

to section list

Properties:

default section

to section list

These parameters will be applied to the document definitions if they are not defined explicitly. See the documents section for the details.

Properties:

documents section

to section list

Array of objects with properties:

plugins section

to section list

May contain multiple properties:

The plugins data and the plugins themselves are described in the separate sections.