Markup conversion · Core reference

Markdown, AsciiDoc and reStructuredText.

@markup converts authored markup to an HTML fragment through embedded Markup++. Use an inline block for a short passage or a project-relative file for a document.

Two source forms, three formats

@markup("md"){
  ## Hello $[page.title]
}

@markup("md", "content/guide.md")
@markup("adoc", "content/guide.adoc")
@markup("rst", "content/guide.rst")

The accepted short names are md, adoc and rst; markdown, asciidoc and restructuredtext are equivalent long names. Conversion returns a fragment, not a second complete HTML document.

The evaluation boundary

resolve source → record dependency → evaluate Nift template language
               → convert once with Markup++ → append HTML directly

This means metadata, JSON bindings, loop values and ordinary Nift directives can produce markup input. It also means literal @... or $[...] text produced by conversion cannot unexpectedly execute as a second template pass.

Files and includes are tracked

A file-form source is automatically a dependency. AsciiDoc include:: targets and reStructuredText include resources are resolved by Nift, restricted to the project root, evaluated as templates, and recorded too. Editing any of those files can rebuild the affected output.

Conversion profiles

Markup++ is embedded as a standalone library boundary: it converts strings and performs no ambient file IO. Nift owns project paths, dependency tracking and template evaluation.

Failures stay build failures

Unknown formats, missing or escaping paths, include failures and converter diagnostics are reported with Nift source context. A failed conversion does not silently emit a partial replacement.