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.
• 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 convert local image references to base64 data URIs automatically so exported Markdown stays self-contained.

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.

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).

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.

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.