Markdown Writer Tools

Markdown Writer Tools helps you compose large Markdown documents from smaller snippets.
It understands custom directives so you can include files, reuse sections, and substitute variables before exporting the final result or rewriting the source in place.

Features

• {!include(...)!} directives with optional section filtering and heading level adjustment.
• Variables defined in YAML front‑matter (including lists) and referenced with {!var(name)!} inside included files.
• Conditional blocks with {!if name=value!} ... {!elseif name=value!} ... {!else!} ... {!endif!} resolved using the entry document variables.
• CLI commands to export to a new file or run a destructive build that replaces the source.
• prebuild command to expand includes in place while keeping {!var(...)!} and list directives untouched.
• Optional --stripheaders flag to remove the leading front‑matter like block from the final output.
• Optional --stripcomments flag to remove HTML comment blocks outside fenced code blocks.
• Optional --img2b64 flag to embed local images as base64 so exported Markdown stays self-contained. Images are rewritten to reference notation (![alt][identifier]) with the base64 payload emitted once as a link reference definition ([identifier]: data:...) at the end of the document. Identifiers are derived from each image's path and file name, and the same image referenced multiple times is embedded only once and shares a single definition.

Installation

• Local development: npm link
• Global install: npm install -g @jcohonner/mdwritertools

Once linked or installed, the CLI is available as mdwt.

Usage

Export

mdwt export path/to/doc.md -o dist/output.md [--stripheaders] [--stripcomments] [--img2b64]

Reads the entry Markdown file, resolves includes and variables, and writes the result to the specified output (stdout if omitted).

Export to clipboard

mdwt export path/to/doc.md -o clipboard [--stripheaders] [--stripcomments] [--img2b64]

Reads the entry Markdown file, resolves includes and variables, and copies the result to the system clipboard.

Build (in-place)

mdwt build path/to/doc.md [--stripheaders] [--stripcomments] [--img2b64]

Resolves directives and writes the rendered content back to the same file. Useful when you need the source file without include directives.

Prebuild (in-place, directives preserved)

mdwt prebuild path/to/doc.md [--stripheaders] [--img2b64]

Expands include directives and resolves conditional blocks in place, while:

• keeping {!var(name)!} tokens in the body
• keeping list directives ({!list-add ... !} / {!list-table(...)!})
• keeping HTML comments (unless you post-process separately)
• merging variables collected from the include hierarchy into the root front-matter block

Directive Reference

Include

{!include(relative/or/absolute/path.md|# Section Heading|###)}

• Only the path is required.
• Provide a Section Heading that matches a Markdown heading to include just that section.
• Optionally set a target heading level (e.g., ###) to rebase heading levels in the snippet.
• You can insert variables into the path using <varName> placeholders that resolve against the upper variable values (after all includes are processed):

{!include(includes/product-<edition>.md)!}

Variables

Define variables in YAML front-matter like block:

---
product: MDWriterTools
---

Lists are supported too:

---
tags:
  - alpha
  - beta
---

Use in content with {!var(product)!}. Variables cascade through includes, so definitions in a parent file are available in children. When a variable is a list, items from included files are merged into the parent list (deduplicated).

Nested mappings can be reached with dotted notation. Given:

---
lists:
  checklist:
    drive-file: ABC
---

reference the leaf value with {!var(lists.checklist.drive-file)!} (resolves to ABC). Dotted paths work the same way in include paths (<lists.checklist.drive-file>) and conditionals ({!if lists.checklist.drive-file=ABC!}). A dotted path must resolve to a scalar (or list) leaf — referencing an intermediate mapping is reported as an error. The nested block itself is preserved verbatim in the rendered front matter.

Conditionals

Wrap sections that should only appear when an upper variable value matches a value:

{!if edition=pro!}
## Pro content
{!elseif edition=community!}
## Community content
{!else!}
## Default content
{!endif!}

• Conditions are evaluated when a file is included.
• The value from the top-level entry document is always used, even if a nested include defines its own variable with the same name.
• When a variable is a list, {!if name=value!} checks whether the list contains value.
• Use alongside includes to ship a single source file that produces different outputs depending on the entry variables.

Lists

• Add an item anywhere with a block that is removed from the final output:

{!list-add backlog
name: Item name
description: ...
status: ...
priority: ...
!}

• Render a table anywhere with the attributes and labels you need, and an optional path back to the section where the item was captured:

{!list-table(list=backlog|columns=name:Item,status,priority,path:Location)!}

• list defaults to items when omitted.
• columns is a comma-separated list of field[:Label]. Include path to add a breadcrumb that links to the heading anchor where the item was added.
• Headings are tracked across the whole document (after includes) so path links jump to the right section.

Inline items

A list-add block also emits the item as a standard markdown paragraph where the block appears, using an inline template configured for that list in the entry front matter. Inline output is on by default — it happens automatically whenever the list defines an inline template:

---
lists:
  backlog:
    inline: "**${name}** — priority ${priority}"
---

{!list-add backlog
name: Login
priority: P1
!}

• If a list has no inline template configured in the front matter, no inline paragraph is produced for its items.
• To skip inline output for a single item, add inline: false (or a bare noinline flag) to its list-add block.
• ${field} (and the bare {field} form) in the template are replaced with the item's attribute values; unknown references are left untouched.
• The inline flag is stripped from the item, so it never appears as a column in tables or exports.
• Inline output is only produced during build and export — prebuild keeps the raw {!list-add ... !} directive intact. The generated paragraph appears in build output; export simply drops the flag from the serialized data.

VS Code extension

The same engine is available as a VS Code extension in vscode-extension/. It exposes Build, Prebuild, Export to Clipboard, and Export Lists as CSV/JSON as commands (Command Palette and editor context menu) acting on the active Markdown file. Clipboard export defaults to img2b64: true and stripheaders: true (configurable in settings). See vscode-extension/README.md for development and packaging.

Examples and tests

• Sample documents demonstrating includes, variables, and conditionals live in examples/conditionals.
• Run npm test to render those examples and assert that conditional blocks respect the entry-level variables.

Development

1. Clone the repo and run npm install.
2. Link the CLI locally with npm link.
3. Run mdwt export ... or mdwt build ... while editing your docs.

Feel free to adapt the CLI to add new directives or automation that fits your documentation workflow.