write-markdown

Markdown Style Guide

Apply the Markdown conventions from ./references/MARKDOWN.md when creating or editing Markdown files. This guide targets GitHub Flavored Markdown (GFM) and aligns with markdownlint-cli2 rules.

Common Mistakes

These two issues cause the most formatting churn and lint failures. Check every Markdown file for them.

Tables: aligned pipes, from Prettier where it runs

A committed table has every pipe aligned, every cell padded to its column width, and delimiter hyphens filled to match. Who does the padding depends on the project.

<!-- Committed form: pipes aligned, cells padded -->

| Name    | Type   | Default |
| ------- | ------ | ------- |
| timeout | number | 30      |
| retries | number | 3       |

<!-- Ragged: fine as a draft only where Prettier will format it -->

| Name | Type | Default |
| --- | --- | --- |
| timeout | number | 30 |
| retries | number | 3 |

Determine ownership for each edited file. Verify that Prettier is available as a project dependency or a global tool. Its settings may live in .prettierrc*, prettier.config.*, or a prettier key in package.json; config presence alone does not prove that formatting runs. If project format commands exist, inspect their paths, globs, working directory, and options: a command restricted to JavaScript or other non-Markdown files does not own Markdown alignment. If no format command exists, configured and available Prettier can format the file through the direct CLI fallback in Validation. In either case, honor the chosen command's effective ignore files: .gitignore and .prettierignore by default, or the files specified by --ignore-path.

Before formatting a Markdown file with fenced code blocks, check the effective embeddedLanguageFormatting setting. Prettier's default auto may reformat recognized code blocks along with the tables. Use embeddedLanguageFormatting: "off" for the formatting pass, or inspect and accept those code-block changes explicitly.