MarkShup usage

MarkShup accepts a Markdown file or directory and writes generated HTML to an output directory. See Features for its conversion, customization, asset, and syntax capabilities.

Command-line reference

USAGE

    markshup [[options] ...] <input> <output>

DESCRIPTION

    Convert Markdown files to HTML.

OPTIONS

    --recursive             Convert Markdown files in input subdirectories.
    --mangle STYLE          Name style: kebab, snake, or keep (default).

    --title TEXT            Prefix every generated document title.
    --header PATH           HTML file to insert into every document header.
    --footer PATH           HTML file to insert into every document footer.
    --meta NAME VALUE       Add a metadata tag. May be repeated.
    --strip-fragment FRAG   Remove FRAG from HTTP(S) links.

    --css PATH              Link a stylesheet path. May be repeated.
    --css-ref REF           Stylesheet reference. May be repeated.

    --icon PATH             Link an icon path. May be repeated.
    --icon-ref REF          Icon reference. May be repeated.
    --icon-light PATH       Link a light-mode icon path. May be repeated.
    --icon-light-ref REF    Light-mode icon reference. May be repeated.
    --icon-dark PATH        Link a dark-mode icon path. May be repeated.
    --icon-dark-ref REF     Dark-mode icon reference. May be repeated.

    --js PATH               Link a JavaScript path. May be repeated.
    --js-ref REF            JavaScript reference. May be repeated.

    --js-helper DIR         Write optional JavaScript helpers to DIR.
    --js-helper-mode MODE   Helper policy: auto, local, or external.

    --templates PATH        Template directory for per-folder document assets.

    --flavor FLAVOR         Markdown flavor: common, common+, extended,
                            markshup (default).

    --copy-files            Copy referenced local files (default).
    --no-copy-files         Reference local files without copying them.
    --detect-img            Detect Smart Image Bundles (default).
    --no-detect-img         Do not detect Smart Image Bundles.
    --default-css           Include the built-in stylesheet (default).
    --no-default-css        Do not include the built-in stylesheet.

    --selfupdate            Update within the current major version.
    --selfupgrade VERSION   Update to major VERSION, or use "latest".

    --                      Do not interpret following arguments as options.
    -h, -help, --help       Show this help page.
    --version               Show the MarkShup version.

Convert files recursively

Convert one Markdown file and the local Markdown files it references:

markshup README.md site

Convert every .md file directly inside a directory:

markshup doc site

Add --recursive to include its subdirectories:

markshup --recursive doc site

The output is always a directory. Standard input, standard output, custom output file names, and fragment output are not supported.

By default, output paths retain their relative source directories and names, followed by .html. For example, Developer Guides/README.md becomes Developer Guides/README.md.html.

Use --mangle kebab to convert output file and directory names to lowercase words separated by hyphens. Use --mangle snake for lowercase words separated by underscores. --mangle keep preserves the source names and is the default.

Customize documents

--title TEXT adds TEXT before the title taken from each Markdown document. For example, a document titled Installation becomes My site: Installation with --title "My site".

--header PATH and --footer PATH insert the raw contents of an HTML file into every generated document. Relative paths are resolved from the current working directory. The files are read from their original locations and are not copied to the output directory.

--meta NAME VALUE adds <meta name="NAME" content="VALUE"> to every generated document. Repeat the option to add multiple entries. Names and values are HTML-escaped.

markshup --title "My site" --header header.html --footer footer.html doc site

Remove an HTTP(S) link fragment

Use --strip-fragment FRAGMENT to remove one exact fragment from generated HTTP and HTTPS links. The leading # is optional.

markshup --strip-fragment '#from-markdown' input.md site

See Link fragment removal for its purpose and scope.

Add stylesheets

--css PATH accepts the path of an existing local stylesheet. Relative paths are resolved from the current working directory. MarkShup references the original file and calculates the correct relative link for every generated document, adding ../ components for nested output directories when necessary. It does not copy the stylesheet.

--css-ref REF writes REF into every generated document unchanged. Use it for a URL, a web-root reference, or a reference that is already correct relative to every generated document. Both options may be repeated. Local-path stylesheets retain their order and are followed by the references, which also retain their order.

markshup --css assets/site.css doc site

Add icons

--icon PATH accepts the path of an existing local icon. Relative paths are resolved from the current working directory. MarkShup references the original file and adjusts the relative link for each generated document. It does not copy the icon.

--icon-ref REF writes REF unchanged. Use --icon-light and --icon-dark for local icons intended for light and dark color schemes, or use their -ref variants for unchanged references. Each option may be repeated.

markshup --icon assets/favicon.ico doc site

Add JavaScript

--js PATH accepts the path of an existing local JavaScript file. Relative paths are resolved from the current working directory. MarkShup references the original file and calculates the correct relative link for every generated document, adding ../ components for nested output directories when necessary. It does not copy the script.

--js-ref REF writes REF into every generated document unchanged. Use it for a URL, a web-root reference, or a reference that is already correct relative to every generated document. Both options may be repeated. Local-path scripts retain their order and are followed by the references, which also retain their order.

markshup --js assets/site.js doc site

Control copying of Markdown references

By default, MarkShup copies local files referenced from within Markdown content to the corresponding location in the output directory. This includes files used by Markdown links and images.

--no-copy-files leaves those files in the source tree and writes a relative reference from each generated HTML document to the original file instead. --copy-files selects the default behavior explicitly or restores it in a template override.

These options affect only local files referenced from Markdown content. They do not affect stylesheets, scripts, icons, headers, or footers supplied through other command-line options or templates.

Configure optional JavaScript helpers

Use --js-helper-mode auto, local, or external to select the policy for optional JavaScript helpers. auto is the default. Local mode also requires a destination directory set with --js-helper and either curl or wget.

For example, this stores the currently supported Mermaid helper locally:

markshup --js-helper site/js/lib/mermaid --js-helper-mode local doc site

Helpers are only added to documents that need them. See Optional JavaScript helpers for the available behavior.

Use templates

Use --templates PATH for advanced per-folder customization and inherited settings. See Templates for the directory layout, supported files, ${OUTDIR} links, and option overrides.

Choose a Markdown flavor

Use --flavor with common, common+, extended, or markshup. The default is markshup.

markshup --flavor common+ README.md site

See Markdown syntax flavors for the features enabled by each value.

Configure Smart Image Bundles

Smart Image Bundles are detected by default. Use --no-detect-img to turn off their detection. Use --detect-img to restore detection in a later template override. See Smart Image Bundles for the directory format, naming rules, and generated HTML.

Disable the default stylesheet

The built-in stylesheet is included by default. Add --no-default-css to omit it. Use --default-css to restore it in a later template override.

Update a standalone executable

Update within the current major release:

markshup --selfupdate

Move to a specific major release or the latest available release:

markshup --selfupgrade 2
markshup --selfupgrade latest

These commands only work with a standalone executable created by ./run deploy. See Self-update for supported update paths and requirements.