Skip to content
Merlon Docs

Markdown formatting

Shards in this repository follow these Markdown conventions. Where a feature shard defines the rule behind a convention, the convention links to it.

Section titled “Headings and links”

Shards are GFM, and their headings use the ATX form. GFM scope sets that authoring contract and the heading subset compile recognizes. Link a heading by the slug of its text, as that section says. Don’t write a Pandoc ID ({#…}) after a heading: the local Vale rule MerlonDocs-PandocId fails pnpm docs:check on one.

Write each cross-link in the form that No placeholder links gives, and link a new file in the change that adds it. Link it from its directory’s index.md or from the guide’s manifest, and list a new glossary entry in glossary/index.md. Until something stitched links the file, pnpm docs:check doesn’t read its links, as Check gate stages says, and the site sync in pnpm site:build fails on its dead links.

Tables

Section titled “Tables”

Prettier aligns each GFM table in a shard with the root .prettierrc.json, which sets proseWrap to preserve. Compile re-aligns a table the same way after it rewrites a link in the table, and Tables after link rewriting says which tables it leaves out of line. In a shard’s tables:

  • When a link changes width in a table whose cells all fill their columns, compile leaves the table as written, and pnpm format:check fails on it in a committed output such as README.md. Shorten the text of one cell so Prettier pads it. pnpm format:check skips docs/_build/, which .gitignore lists.
  • Keep explicit {#id} anchors out of table cells, and keep a link to an insert out of code spans in table cells. The stripAnchors hook strips the anchor and inlineInserts rewrites the link, and Tables after link rewriting says that either change leaves the table out of line. The link passes and codeEvidence leave a link in a code span as written.

Give the first link to an insert in a guide a paragraph of its own, ahead of any table cell that links to the insert, as inlineInserts first inline says.

Formatting and linting

Section titled “Formatting and linting”

pnpm format runs Prettier on the repository with the settings in the root .prettierrc.json, and pnpm format:check fails on a file that Prettier would change. pnpm docs:check runs markdownlint and Vale on the docs, and Linting docs says which configs and styles it uses. The starter markdownlint configs and the MerlonDocs Vale style come from @merlon-docs/merlon-docs-presets, which has no Prettier config.

Note: GitHub and GitHub Flavored Markdown are trademarks of GitHub, Inc. This project is not affiliated with, sponsored by, or endorsed by GitHub, Inc.