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

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

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

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.