npm package: @jcohonner/mdwritertools
Description: Markdown Writer Tools is a set of tools to write doc in MarkDown and allow easy copy/paste to Google Docs
Author: Jérôme Cohonner
Latest version: 0.3.1

# 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:

```yaml
---
product: MDWriterTools
---
```

Lists are supported too:

```yaml
---
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.