Templates

Preliminary note

As for now the program provides a quick start script described here. This page may be useful for understanding the program's working principles, and for new templates creation or the existing templates modification.

What is template?

In this program Mustache template engine [mustache] is used for HTML templates processing. A simple template file may look like this:

<!DOCTYPE html>
<html>
<head><title>{{title}}</title>
<meta charset="utf-8">
{{{styles}}}
</head>
<body>
{{{content}}}
<hr />
<p style="font-size: smaller;">Generated by {{exec_name}} {{exec_version}}
{{generation_date}} {{generation_time}}</p>
</body>
</html>

It consists of static HTML code and Mustache tags that define substitutions and other kind of template processing actions. In this simple example only substitutions are defined. The tags with three pairs of curly braces will be substituted with the provided values without change. The tags with two pairs of curly braces will be substituted with the HTML-escaped provided values.

The program provides values for the following keys by default:

Tag key	Description
`{{title}}`	The page title
`{{{styles}}}`	Included and/or linked CSS
`{{{content}}}`	The result of the Markdown document processing
`{{exec_name}}`	The self name provided by the program
`{{exec_version}}`	The program version (meaning the numbers, not Python or Java)
`{{generation_date}}`	The generation date (YYYY-MM-DD)
`{{generation_time}}`	The generation time (hh:mm:ss)
`{{source_file}}`	The source text file resolved relatively to the current HTML page

The other tags may be provided by plugins that are described in the separate section.

Important

The number of curly braces pairs (two or three) is meaningful. Use them for the certain tags as it's presented in the table above.

Provided templates

This documentation is created using an extended template that can be easily reused in other documentation projects. The template file location is doc_src/templates/multipage.html.

There's also the other template located at doc_src/templates/default.html. This is a single-page template that is used by the Windows context menu scripts. It may also be used manually for single-page documents creation.

The above templates, in conjunction with the corresponding CSS, produce responsive HTML documents that are adapted for both desktop and mobile devices.

CSS

This documentation uses a set of CSS files. The information about this files location may be found in the template files. See the typical project structure for more details.

Color themes

There's a mechanism for defining and using color themes. A theme is a subdirectory of the directory doc/themes/. The theme subdirectory name is the theme's name.

The theme name is specified by the variable theme in the argument file md2html_args.json. The complete declaration may look like this: "theme": "light", where light is the desired theme name. As for now, two themes are defined: light and dark.

The quick start script creates and defines the light theme only. To use the dark theme:

copy the directory dark to the doc/themes directory;
assign the value dark to the variable theme in the file md2html_args.json;
fulfill forcible full documentation regeneration;
the dark theme will be applied.

A page may be separately rendered using the dark theme. For this, variable "theme": "dark" may be defined in the page variables section.

This documentation contains one page rendered in the dark color scheme as an example, see here.