Markdown Authoring Guidelines

Rules

• Always specify language on code blocks - Use

  bash

  ,

  yaml

  ,

  json

  ,

  text

  ,

  hcl

  ,

  go

  , etc. Never use bare

  ```

• No AI slop - Never use emojis, glyphs or emdashes
• Use headings, not bold for section titles - Use proper heading levels (

  ##

  ,

  ###

  , etc.) not

  **Bold**

  on its own line
• One H1 per file - Only one

  # Title

  at the top
• First line should be H1 - Start files with

  # Title

• Write to the formatter contract - A PostToolUse hook reformats markdown after every write. See

  /md-lint

  for what it rewrites and which lint rules it cannot fix
• Blank lines between styles - Put single blank line between different markdown types

Examples

Blank lines between styles

## Heading

paragraph

- list item one
- list item two

> block quote

## Heading


paragraph
- list item one
- list item two
> block quote

Headings not bold

### Heading

paragraph

**heading incorrect bold**

paragraph

Code Blocks

```bash
#!/bin/bash
```

```
#!/bin/bash
```

Trailing New Line

tail -c 1 file.md | xxd

0a