MarkShup features

MarkShup converts Markdown files and directories into complete static HTML documents. See Usage for commands and options.

Document conversion

MarkShup can convert a single Markdown file, all Markdown files in a directory, or an entire directory tree. Starting with a single file also discovers and converts locally referenced Markdown files.

Generated documents retain the source directory structure. Relative links between Markdown documents are rewritten to their generated HTML destinations, and referenced local assets are copied when necessary. Output paths can retain their source names or be normalized to kebab case or snake case.

MarkShup reports broken local references after generating all available pages. This makes it possible to supply separately managed assets without preventing the rest of a site from being built.

Document customization

Generated documents can include a title prefix, custom metadata, HTML headers and footers, stylesheets, icons, and JavaScript. Assets can use local filesystem paths, output-relative references, site-root references, or URLs. Light-mode and dark-mode icons are also supported.

MarkShup includes a small default stylesheet for readable standalone documents. Custom stylesheets can override it, or it can be omitted entirely.

Templates

Templates customize generated documents per folder with inherited headers, footers, stylesheets, icons, JavaScript, metadata, and option overrides. See Templates for the directory layout, inheritance rules, and supported files.

Smart Image Bundles

Smart Image Bundles automatically select the best image for each visitor.

• Light and dark variants follow the visitor's color-scheme preference.
• High-density displays use @2x and @3x images.
• Modern formats such as AVIF and WebP are preferred when supported.
• The Markdown-referenced image remains a reliable fallback.

See Smart Image Bundles for naming and selection rules.

Optional JavaScript helpers

MarkShup can add JavaScript helpers only to documents that need them. Mermaid diagrams can use a pinned external Mermaid Tiny bundle or a locally downloaded copy. Local helpers, their adapters, and their licenses can be collected in a chosen directory.

Link fragment removal

MarkShup can remove one configured fragment from generated HTTP and HTTPS links while preserving it in the Markdown source. This lets a target page behave differently when opened directly from Markdown. Other fragments, query strings, and image references remain unchanged.

Self-update

Standalone MarkShup executables can update within their current major release, move to a specified major release, or find the latest available major release. Intentional downgrades are supported. The repository shim does not update itself. Updates require curl or wget and a supported archive extraction tool.

Markdown syntax flavors

Syntax support is organized into cumulative flavors. common provides the base syntax, common+ adds widely supported extensions, extended adds less common extensions, and markshup enables every supported feature. See Usage to select a flavor and the showcase for rendered examples.

Common Markdown (common)

• ATX and Setext headings.
• Paragraphs, soft breaks, and hard breaks using a trailing backslash or two spaces.
• Thematic breaks.
• Emphasis and strong emphasis.
• Inline code, indented code blocks, and backtick- and tilde-fenced code blocks with language classes.
• Inline links, reference links, shortcut reference links, and reference definitions.
• Inline and reference images, including image titles.
• Ordered, unordered, and nested lists.
• Block quotes and nested block quotes.
• Backslash escapes for ASCII Markdown punctuation.
• HTML blocks, inline HTML tags, HTML comments, and HTML entities.

Common extensions (common+)

These extensions are supported by GitHub, Codeberg, and the VSCodium Markdown preview.

• Double-tilde strikethrough: ~~text~~.
• Links to headings: [Text](#heading).
• Automatic URL and email links.
• Pipe tables with column alignment.
• Footnotes.
• Common GitHub-style emoji shortcodes.
• Mermaid diagram code blocks when a JavaScript helper policy is configured.

Less common extensions (extended)

These extensions are not supported by all of GitHub, Codeberg, and VSCodium.

• Explicit heading identifiers: ### Heading {#identifier}.
• Highlighted text: ==text==.
• Task lists: - [ ] and - [x].
• Definition lists.
• Single-tilde strikethrough: ~text~.
• GitHub-style admonitions: > [!NOTE].

MarkShup extensions (markshup)

These convenience extensions were introduced by MarkShup.

• Extra-tilde strikethrough: ~~~text~~~.
• Subscript: _{text}.
• Superscript: ^{text}.
• Smart dashes: -- becomes an en dash (–) and --- becomes an em dash (—).

Still missing

See Still missing for unsupported Markdown features and known compatibility limitations.