markdown-integration

What this skill does

<objective>

# markdown-integration

ePublisher integration patterns for Markdown++ source documents. This skill covers how Markdown++ documents fit into ePublisher projects, Stationery, AutoMap builds, and Reverb output — not the format spec itself.

**Format syntax lives elsewhere.** For Markdown++ syntax (variables, styles, aliases, conditions, includes, markers, multiline tables), validation rules, and authoring best practices, use the **markdown-plus-plus** skill in the [`quadralay/markdown-plus-plus`](https://github.com/quadralay/markdown-plus-plus) plugin. This skill assumes that knowledge and focuses on what changes when those documents become source files in an ePublisher project.

**Do not use training data for ePublisher integration of Markdown++.** Markdown++ is a WebWorks extension and the integration points (Variables window, Conditions window, Stationery style mapping, helper adapter) are proprietary. Use only this skill's references, the `epublisher`/`automap`/`reverb2` skills, and vendor documentation (`static.webworks.com`).
</objective>

<overview>

## Overview

ePublisher routes Markdown++ source files through the **helper adapter** (`Adapters/helper/markdown/`). Each Markdown++ extension maps onto an ePublisher concept:

| Markdown++ extension | ePublisher integration point |
|----------------------|------------------------------|
| `$variable;` | Variables window / Stationery defaults / target overrides |
| `<!--style:Name-->` | Stationery style definitions → format CSS/XSL |
| `<!--condition:name-->` | Conditions window / per-target visibility / job file overrides |
| `<!--include:path-->` | Source document group resolution (paths relative to including file) |
| `<!--marker:...-->` | Output-format processing (search keywords, index entries, CSH) |
| `<!--#alias-->` | Stable URL endpoints in Reverb output (`url_maps.xml`) |

The format-level rules for each are documented in the `markdown-plus-plus` skill from `quadralay/markdown-plus-plus`. This skill documents the ePublisher-side configuration each one requires.
</overview>

<variables>

## Variables — Sources and Resolution

A Markdown++ variable reference (`$product_name;`) is unbound until ePublisher resolves it. There are four sources, in increasing override priority:

1. **Stationery defaults** — defined in the `.wxsp` Stationery project, applied to every project derived from that Stationery.
2. **Project Variables window** — defined in the `.wep`/`.wrp` project, override Stationery defaults for that project.
3. **Target-specific overrides** — defined per target inside the project, override project-level values for one output target.
4. **Job file overrides** — `.waj` job files can override variables per target through the `<Variables>` element under each `<Target>`. These take precedence over all in-project values (target-specific, Project Variables window, and Stationery defaults).

See `references/integration-patterns.md` for the full priority table and per-environment / CI-CD layering patterns.

**Diagnosing unresolved variables:**

- Variable renders as literal `$name;` in output → not defined at any level for that target.
- Variable resolves differently across targets → check job file overrides first (if a `.waj` is in use), then target-level overrides, then project, then Stationery.
- Variable renders correctly in one project but not another derived from the same Stationery → check the project's local override is not blanking the value.

Use the `epublisher` skill's `parse-targets.py` to extract target definitions from the project file.

</variables>

<styles>

## Styles — Mapping to Stationery

A `<!--style:Name-->` comment names a style; the actual visual rendering comes from the Stationery's style definitions and the format's CSS/XSL transforms.

**Resolution path:**

1. Style name in Markdown++ document
2. Stationery `.wxsp` defines the style (inherited by all projects derived from this Stationery)
3. Format's CSS (Reverb, HTML) or XSL-FO templates (PDF) renders the style in output

**Practical rules:**

- Style names are **case-sensitive** and must match a style defined in the Stationery exactly.
- A style referenced in Markdown++ but not defined in the Stationery falls back to default Markdown rendering (no error, no warning).
- New styles require a Stationery edit, not a Markdown++ edit. Adding `<!--style:NewWarningBox-->` to a `.md` file does nothing until `NewWarningBox` exists in the Stationery's style definitions.
- Per-format style overrides live under `[Project]/Formats/[FormatName]/` in the file resolver hierarchy (see `epublisher` skill `references/file-resolver-guide.md`).

**Diagnosing a style that does not render:**

1. Confirm the style is defined in the Stationery (`.wxsp`).
2. Confirm the case matches exactly.
3. Confirm the comment is **attached** to its element (no blank line between) — see the format-level rules in the `markdown-plus-plus` skill.
4. Confirm the format's CSS/XSL actually renders that style class.

</styles>

<conditions>

## Conditions — Configuration and Per-Target Visibility

`<!--condition:name-->...<!--/condition-->` blocks are inert until ePublisher knows which conditions are active for the current target.

**Configuration sources:**

1. **Conditions window** — defines the set of available conditions for the project.
2. **Per-target visibility settings** — each target enables or disables conditions independently, controlling which content appears in that output.
3. **Job file overrides** — `.waj` job files can override condition visibility per target using `<Conditions>` under each `<Target>`.

**Common patterns:**

- **Output-format conditions** (`web`, `print`, `pdf`, `chm`) — enable per target so each target emits only its format-relevant content from the same source file.
- **Audience conditions** (`internal`, `external`, `beta`) — typically toggled across all targets together when producing audience-specific output.
- **Platform conditions** (`windows`, `mac`, `linux`) — useful when a single target serves multiple platforms with conditional sections.

**Diagnosing conditional content not appearing:**

1. Check the target's visibility settings for that condition name.
2. If using a job file, check the `<Conditions>` block under the target — it overrides project settings.
3. Confirm the condition name in the document matches exactly (case-sensitive).

</conditions>

<includes>

## File Includes — Source Document Group Resolution

`<!--include:path/to/file.md-->` directives resolve relative to the **including file**, not the project root.

**ePublisher implications:**

- A topic-map source file added as a single document to a group will pull in all its includes during the build. The included files do not need to be added to the group separately.
- Conditional includes (`<!--condition:web--><!--include:web-only.md--><!--/condition-->`) participate in the per-target condition resolution above.
- Circular include detection happens at build time in the helper adapter; AutoMap reports the cycle in its build log.

**When to add an included file to the group anyway:** if you want it to also build standalone (e.g., as a separate Reverb topic with its own URL), add it to the group separately. If it should only appear as part of a parent document's flow, leave it out of the group.

</includes>

<markers_and_aliases>

## Markers and Aliases in Output

Markers and aliases are inert in source — their effect is entirely defined by the output format's processing.

**Markers in Reverb 2.0:**

- `<!--marker:Keywords="api, auth"-->` populates Reverb's full-text search index with extra terms beyond the visible content.
- `<!--marker:IndexMarker="primary:secondary"-->` creates entries in the generated index (Reverb index pane).
- Marker syntax (single `marker:` vs JSON `markers:{...}`) and ordering rules are documented in the format-level skill.

**Aliases and CSH:**

- `<!--#alias-name-->` creates a stable URL endpoint in the generated