---
name: processing-markdown
description: Creates, reads, restructures, and converts Markdown files. Use when the user asks to write, edit, reorganize, lint, or fix a .md file, update a specific section of a README or docs page, generate a table of contents, or convert Markdown to or from HTML, DOCX, or PDF with pandoc. Do not use for writing user-facing release notes in house style (the writing-release-notes skill covers that) and not for HTML files.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Processing Markdown

## When to use / when NOT to use
- **Use for:** creating or editing `.md` files (READMEs, docs, notes), structure-aware edits ("update the Installation section"), generating tables of contents, and converting md ↔ html/docx/pdf.
- **Do NOT use for:** user-facing release notes in house style (use the writing-release-notes skill) or HTML files (use the HTML skill).

## Quick reference

**Default:** Markdown is plain text — create and modify by writing/editing the file directly. No library needed. **Conversion:** pandoc (`brew install pandoc`; PDF output also needs a LaTeX engine: `brew install basictex`).

```bash
# Convert
pandoc README.md -o README.html                 # md → HTML
pandoc report.md -o report.docx                 # md → Word
pandoc report.md -o report.pdf                  # md → PDF (needs LaTeX)
pandoc page.html -t gfm -o page.md              # HTML → md
pandoc document.docx -t gfm -o document.md      # Word → md
```

**Structure-aware edit** — locate sections by heading lines, then edit only that slice:

```python
lines = open("README.md").read().splitlines(keepends=True)
starts = [i for i, l in enumerate(lines) if l.startswith("#")]
# a section runs from its heading to the next heading of same-or-higher level
```

## Rules
- **Match the file's existing conventions** when editing: heading style (`#` vs underline), bullet marker (`-` vs `*`), emphasis (`_` vs `*`), code-fence style. Never reformat untouched sections.
- One H1 (`#`) per document, at the top; sections descend without skipping levels (`##` → `###`).
- Fenced code blocks always carry a language tag (```python, ```bash, ```text for plain).
- Blank line before and after headings, lists, and code fences — most renderers require it.

## Workflow
1. Identify the operation: create / read-extract / section edit / convert.
2. For edits, read the file first and note its conventions (heading style, bullets, fence style).
3. Perform the edit on the smallest possible region (recipes in references/recipes.md).
4. For conversion, verify every relative link and image path referenced in the file exists before running pandoc; report missing targets.
5. **Validate:** re-read the result — heading hierarchy has no skipped levels, all fences are closed (even count of ``` lines), links/images resolve. For conversions, confirm the output file exists and is non-empty. Fix and repeat until clean.

## Edge cases & failure modes
- **pandoc missing** → `brew install pandoc` (macOS) / `apt-get install pandoc` (Linux); PDF errors about `pdflatex` → `brew install basictex`.
- **Unclosed code fence** → everything after it renders as code; check for an odd number of ``` lines before editing by heading.
- **Duplicate section names** → confirm with the user which occurrence to edit; never guess.
- **Markdown flavor mismatch** (tables, task lists, footnotes) → target GitHub-Flavored Markdown (`-t gfm` in pandoc) unless the user states another renderer.
- **Huge files (>5,000 lines)** → edit by line-range around the located heading; never rewrite the whole file for a one-section change.

## References
Deeper copy-paste recipes (section replace, TOC generation, link checking, pandoc options): see [references/recipes.md](references/recipes.md).