The markup prelude is a macro-only authoring layer. It uses ¤ (U+00A4) as its sigil so it does not collide with ordinary % project macros or the ^ sigil used by weaveback-macro sources.

The implementation is intentionally split by output markup:

The .wvb files contain only macro definitions. They are meant to be injected before document sources by weaveback.toml, then the ¤ expansion produces ordinary .adoc or .md text that the same logical tangle pass consumes.

See two-pass markup migration for the project migration plan, parity requirements, and staged conversion policy.

Config Shape

The intended pass shape is:

[[pass]]
dir = "docs-src/"
ext = "wvb"
sigil = "¤"
macro_prelude = ["prelude/asciidoc.wvb"]
expanded_ext = "adoc"
expanded_adoc_dir = "expanded-adoc"
open_delim = "<["
close_delim = "]>"
comment_markers = "//"
chunk_end = "@"

For Markdown output, use:

macro_prelude = ["prelude/markdown.wvb"]
expanded_ext = "md"
expanded_md_dir = "expanded-md"

The expanded directories are intentionally visible, not hidden. Normal tangle mode writes expanded .adoc or .md files there and then tangles the same expanded text. macro_only = true writes the expanded documents and stops before tangling.

Macro Surface

Both prelude implementations define the same names:

  • ¤code_block(language, body)

  • ¤h1(title)

  • ¤h2(title)

  • ¤h3(title)

  • ¤rust_chunk(name, body)

  • ¤graph(format, name, body)

  • ¤xref(target, label)

  • ¤note(body)

  • ¤code_doc(path, title, language, body)

  • ¤pastafarian_warning()

  • ¤rust_file(path, body)

¤rust_file(path, body) emits one Rust @file chunk and prepends the standard generated-file path and safety warning comments.

Example

¤rust_file(crates/demo/src/lib.rs, ¤[
pub fn answer() -> u8 {
    42
}
¤])

With the AsciiDoc prelude, the macro-only expansion produces a normal AsciiDoc listing block containing noweb chunks. The tangle phase then extracts crates/demo/src/lib.rs.

Authoring Rules

  • Use ¤ only for the markup-prelude layer.

  • Keep ordinary project macros on % or the crate-specific sigil they already use.

  • Prefer verbatim blocks for bodies: ¤rust_chunk(name, ¤[ …​ ¤]).

  • Do not abstract prose. Abstract only markup that affects portability: code blocks, diagrams, links, admonitions, and document/code references.