Templates

Templates let different source folders use different headers, footers, stylesheets, icons, scripts, metadata, and conversion options. Settings in a parent folder can be inherited or changed by its subfolders.

Pass the template directory with --templates:

markshup --templates templates doc site

Here, doc is the input directory, site is the output directory, and templates contains the settings described in this guide. A relative template path is resolved from the current working directory.

How the directory hierarchy works

The template directory mirrors the input directory. A template subdirectory named dev applies to Markdown files in the input directory's dev subdirectory. Its settings also apply to deeper directories below dev unless more specific settings replace them.

Suppose the input directory contains these files:

doc/
    index.md
    dev/
        guide.md
        internal/
            notes.md
    user/
        profile.md

The corresponding template and output trees could look like this:

Template directory Output directory
templates/ site/
    footer.html     index.md.html
    dev/     dev/
        header.html         guide.md.html
          internal/
              notes.md.html
    user/     user/
        header.html         profile.md.html
        footer.html  

MarkShup chooses settings for each output file by walking through the matching template directories from the root towards the source file:

A missing settings file means "keep the setting inherited from the parent". If there is no parent setting, MarkShup uses the value supplied on the command line. A file in a deeper template directory changes only its own source directory and descendants.

Template directory names always match the original input directory names. This remains true when --mangle changes names in the output directory.

Files recognized in a template directory

MarkShup recognizes the following settings files:

This guide calls css.txt, js.txt, icon.txt, icon-light.txt, and icon-dark.txt link list files. meta.txt has similar inheritance behavior, but contains name-value pairs instead of links. All of them may use the inheritance markers explained below.

header.html and footer.html contain HTML rather than lists. They follow simpler rules and are covered separately.

Each non-blank, non-comment line in a link list file is one reference. Lines whose first non-space character is # are comments.

For example, css.txt may contain:

# Styles used throughout the site
${OUTDIR}/assets/site.css
https://example.com/fonts.css

Similarly, js.txt contains script references and the three icon files contain icon references. MarkShup turns each reference into the appropriate HTML element. Known file extensions also receive a matching MIME type attribute.

Entries in link list files work like the command-line -ref options: css.txt entries work like --css-ref, js.txt entries work like --js-ref, and icon entries work like --icon-ref, --icon-light-ref, or --icon-dark-ref. They are references written into the generated HTML, not local files for MarkShup to find and copy.

This differs from --css, --js, --icon, --icon-light, and --icon-dark. Those options accept paths to existing local files and resolve relative paths from the current working directory. MarkShup then writes a reference from each generated HTML file to the original local file. It adjusts that reference for the HTML file's directory depth, adding ../ components where necessary. It does not copy the stylesheet, script, or icon.

Link list files cannot make that adjustment automatically because their entries are references, not paths to files MarkShup can locate. Their entries are not resolved from the current working directory or from the template directory. ${OUTDIR} provides the corresponding automatic adjustment when a reference points to a fixed location below the output root.

These files contain references, not paths relative to the template directory. Unless a reference contains ${OUTDIR}, the browser resolves it relative to the generated HTML file:

This distinction matters for nested documents. In site/dev/guide.md.html, assets/site.css points to site/dev/assets/site.css, not site/assets/site.css.

Use ${OUTDIR} when a referenced file belongs at a fixed location below the output root:

${OUTDIR}/assets/site.css

For site/index.md.html, MarkShup writes assets/site.css. For site/dev/guide.md.html, it writes ../assets/site.css. Both references therefore point to site/assets/site.css.

The same ${OUTDIR} placeholder may be used in header.html and footer.html.

Replacing, extending, and restoring lists

Without a marker, a link list file replaces the inherited list. An empty file replaces it with an empty list, so no links of that type are generated. Either choice is inherited by descendant directories.

To combine lists instead, put one of these markers on the first non-blank, non-comment line:

The marker itself is an instruction and does not become a link. Only +, --, and --+ are valid. Forms such as +-- and -- + are errors.

For example, assume MarkShup is called with a command-line stylesheet:

markshup --css-ref print.css --templates templates doc site

The root template replaces that command-line list:

# templates/css.txt
${OUTDIR}/assets/site.css

The dev template extends the root list:

# templates/dev/css.txt
+
${OUTDIR}/assets/dev.css

The user template restores the command-line list and then adds its own stylesheet:

# templates/user/css.txt
--
${OUTDIR}/assets/user.css

The resulting stylesheet references are:

Use --+ in place of -- when a child must retain its inherited template links as well as restore any command-line links that an ancestor replaced.

Headers and footers

header.html and footer.html contain raw HTML. A file replaces the corresponding value inherited from a parent template directory or supplied with --header, --footer, or overrides.txt.

For example:

<!-- templates/header.html -->
<nav><a href="${OUTDIR}/index.html">Home</a></nav>

An empty header.html means "generate no custom header". An empty footer.html does the same for the footer. This choice is inherited by descendant directories until a deeper template provides another file.

Headers and footers cannot be appended, so + and --+ are invalid in these files. A file containing -- restores the corresponding command-line --header or --footer value. If no such value exists, it produces no custom header or footer.

An overrides.txt file can change the header or footer fallback for its directory. In that case, -- in header.html or footer.html restores the value selected by the applicable overrides. See the option override example below.

Metadata

meta.txt contains one metadata entry per line in this form:

name: value

For example:

author: CodingMarkus
description: Developer documentation
"custom:name": "  value with preserved outer spaces  "

Each entry becomes a <meta name="name" content="value"> element. Names and values are HTML-escaped.

Ordinary spaces within an unquoted name or value are kept. Spaces at the beginning or end are removed. Quotes are needed only when leading or trailing spaces must be preserved, or when a metadata name contains a colon. Literal double quotes and backslashes must be escaped as \" and \\.

The supported escapes are \", \\, \n, \r, and \t, both inside and outside quoted text.

meta.txt follows the same inheritance marker rules as the link list files. Without a marker, it replaces metadata supplied by a parent template or with --meta. An empty file removes all metadata. Use +, --, or --+ to extend, restore, or combine metadata in the same way as link lists.

Option overrides

overrides.txt changes conversion options for one source directory and its descendants. It is useful when, for example, developer documents need a different title or Markdown flavor.

Each non-blank, non-comment line contains one option and, when required, its value:

--title Developer documentation
--flavor extended
--header header with spaces.html
--no-default-css

Values do not need quotes merely because they contain spaces. For example, these two lines produce exactly the same header path:

--header header with spaces.html
--header "header with spaces.html"

Quotes are useful when leading or trailing spaces are part of the value:

--title "  Title with outer spaces  "

The supported escapes are \", \\, \n, \r, and \t, both inside and outside quotes. A backslash cannot escape a space because spaces already belong to the value.

The following options are supported:

Each option replaces the current value of that option. Options not mentioned in the file keep their current values.

An ordinary, non-empty overrides.txt starts again with the original command-line options and then applies its lines. This means it replaces option changes made by an ancestor's overrides.txt. An empty file has no effect.

Use a marker when a child directory needs different behavior:

For example:

# templates/overrides.txt
--title Documentation
--no-default-css

# templates/dev/overrides.txt
+
--title Developer documentation

The root documents use the title Documentation without the built-in stylesheet. Documents below dev inherit the disabled stylesheet and change only the title to Developer documentation.

If templates/dev/overrides.txt omitted the +, it would first restore every command-line option. It would therefore restore the command-line setting for the built-in stylesheet before applying the developer title.

Relative --header and --footer paths in overrides.txt are resolved from the directory containing that file. Relative paths supplied on the command line are resolved from the current working directory. Absolute paths are used unchanged.

Smart Image Bundle detection and the built-in stylesheet are enabled by default. --no-detect-img and --no-default-css disable them; --detect-img and --default-css restore them in a descendant directory.

Use meta.txt, not overrides.txt, to change metadata.

Complete example

This example gives every document a shared stylesheet and footer. Developer documents add a stylesheet and use the extended Markdown flavor. User documents replace the shared footer and add metadata.

doc/
    index.md
    dev/
        guide.md
    user/
        profile.md

templates/
    css.txt
    footer.html
    dev/
        css.txt
        overrides.txt
    user/
        footer.html
        meta.txt
File Content
templates/css.txt ${OUTDIR}/assets/site.css
templates/footer.html <p>Copyright 2026</p>
templates/dev/css.txt +
${OUTDIR}/assets/developer.css
templates/dev/overrides.txt +
--flavor extended
templates/user/footer.html <p>Questions? Contact support.</p>
templates/user/meta.txt +
section: User documentation

The generated files receive these settings: