14 added, 12 removed. Audit A to A.
---
name: markdown-writer
description: >-
- Creates or updates Markdown (`.md` / `.mdc` / `.mdx`). Use when writing or editing Markdown, fixing Markdown formatting, or editing YAML frontmatter in a Markdown file.
+ Write Markdown (`.md` / `.mdc` / `.mdx`). Use when creating or editing a Markdown file, or YAML frontmatter in one.
metadata:
version: 0.1.0
author: "Diego Oliveira"
tags:
- markdown
- markdown-writer
---
# Markdown writer
- Write Markdown that reads as intended and parses as written. Dest file conventions and dest lint config win.
+ Write Markdown that _scans_ and _parses_. Dest file conventions and dest lint config win.
## Workflow
- 1. **Match dest.** Path, document type, existing layout, lint config if any, and _prose wrap_ (one-line or wrap). Dest requires wrap when MD013 is on, `.editorconfig` sets `max_line_length` for Markdown, or the file already wraps. **Done when:** those five are named.
+ 1. **Match dest.** Path, document type (including `.mdc` / `.mdx` extras dest owns: JSX, rule schema), existing layout, lint config if any, and _prose wrap_ (one-line or wrap). Dest requires wrap when MD013 is on, `.editorconfig` sets `max_line_length` for Markdown, or the file already wraps. **Done when:** those five are named.
2. **Write.** Apply [Write](#write). Load [frontmatter.md](references/frontmatter.md) when YAML is at the top or dest requires it. **Done when:** every applicable Write rule is visible in the file.
- 3. **Prove.** Run `markdownlint` on changed `.md` / `.mdc` / `.mdx` paths when dest has the tool or a `.markdownlint.yaml`. **Done when:** that command exits 0, or dest has no linter. One-line dest: keep prose on one line if MD013 fires.
+ 3. **Prove.** Read the headings only. Check each list, table, and fence against Parse. Run `markdownlint` on changed `.md` / `.mdc` / `.mdx` paths when dest has the tool or a `.markdownlint.yaml`. **Done when:** the headings are the outline, each list/table/fence matches Parse, and that command exits 0 or dest has no linter. One-line dest: keep prose on one line if MD013 fires.
## Write
+ **Scan.** First sentence under the H1 names the file's job. Headings are the outline: ATX (`# Heading`), one H1 (first heading after frontmatter `---` if any), each heading one level deeper than its parent, unique text that names the section. H1 mirrors the filename. Blank line around headings.
+
+ **Parse.** Parallel facts → list. Records with the same fields → table. Copy-paste or syntax → fenced block. A link's text names the target.
+
**Prose.** One sentence, list item, or table cell per line. Break only on a heading, new list item, blank line, or fence. Wrap to a column only when Match dest named wrap.
- **Headings.** ATX (`# Heading`). One H1; with frontmatter, it is the first heading after the closing `---`. Each heading is one level deeper than its parent. Unique heading text. H1 mirrors the filename. Blank line around headings. Blank line above `---` so the previous line stays a paragraph.
+ **Lists.** Marker `-`. Ordered lists use `1.` (lazy `1.` on long or mutable lists). Nested items, continuations, and fences inside an item indent 4 spaces. Nest at most one extra level. Blank line before and after the list.
- **Lists.** Marker `-`. Ordered lists use `1.` (lazy `1.` on long or mutable lists). Nested items, continuations, and fences inside an item indent 4 spaces. Blank line before and after the list.
+ **Tables.** Header, hyphen delimiter, data rows. `|` on both ends of every row. Same cell count on every row.
**Code.** Fenced block with a language tag (`txt` when there is none). Blank line around the fence. Inline backticks for filenames, fields, commands, variables, and example paths.
- **Links.** `[descriptive text](url)` or `<url>`. Images: `` with alt that describes the image. Long URLs: reference links, defined just before the next heading or at file end if shared.
-
- **Emphasis.** `*italic*` and `**bold**`.
+ **Links.** `[label](url)` or `<url>`. Images: `` with alt that describes the image. Long URLs: reference links, defined just before the next heading or at file end if shared.
- **Blocks.** Blank line around quotes and tables. Multi-paragraph quotes keep `>` on the blank lines between them. Markdown over raw HTML.
+ **Emphasis.** `*italic*` and `**bold**`. Bold only words that change a decision.
- **Tables.** Header, hyphen delimiter, data rows. `|` on both ends of every row. Same cell count on every row. Tabular data only.
+ **Blocks.** Blank line around quotes and tables. Multi-paragraph quotes keep `>` on the blank lines between them. Markdown over raw HTML. A `---` thematic break only when dest already uses that pattern; blank line above `---` so the previous line stays a paragraph.
**Tasks.** `- [ ]` / `- [x]` at the start of the item.
**Whitespace.** Spaces for indent. File ends with one newline. A line break inside a paragraph is a trailing `\`.
- **Shape.** Brief intro under the H1. `[TOC]` only on Gitiles/MkDocs. See also at the end when dest already uses that pattern.
+ **Shape.** `[TOC]` only on Gitiles/MkDocs. See also at the end when dest already uses that pattern.