Templates

Preliminary note

Currently, the quick start script may be used for initial project setup, so manual template manipulation is usually not required. This page may be useful for understanding the program's principles and for creating new templates or modifying existing ones.

What is a template

This program uses the Mustache template engine [mustache] for processing HTML templates. 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 kinds of processing actions. In this simple example, only substitutions are defined. The tags with three pairs of curly braces (like {{{content}}}) will be substituted with the provided values as is. The tags with two pairs of curly braces (like {{exec_name}}) 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 executable name reported by the program (like "md2html_py")
`{{exec_version}}`	The program version (like "1.0.8")
`{{generation_date}}`	The generation date (YYYY-MM-DD)
`{{generation_time}}`	The generation time (hh:mm:ss)
`{{source_file}}`	The source text file path resolved relative to the current HTML page

Other keys may be provided by plugins.

Important

The number of curly braces pairs (two or three) is meaningful. Please use them for the certain keys as presented in the table above.

Provided templates

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

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

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

The provided template supports defining and using color themes. A theme is a subdirectory of the doc/themes/ directory. 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. Currently, 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 $MD2HTML_HOME/doc/themes/dark directory from the distribution into the project directory doc/themes/dark;
assign the value dark to the variable theme in the md2html_args.json file;
perform a full site regeneration with the f/--force flag.

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

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