Markdown Formatting Standards

Apply these formatting rules when creating or editing any markdown file.

General Rules

• •Use blank lines around block objects (headers, code blocks, lists, blockquotes)
• •Use YAML front matter for document metadata when appropriate
• •Include a blank line after the closing --- of front matter
• •Always specify a language/type for code blocks (use text for plain text)
• •End every file with a blank line

What to Avoid

• •Bold instead of headers for section titles
• •Bold to highlight field names in bullet lists
• •Horizontal rule lines (--- as separators between sections)
• •Tables unless explicitly requested or absolutely necessary
• •Multiple top-level (#) headings in a single document
• •Bare URLs or email addresses

Headers

Headers must have a blank line both before and after them. This applies to all header levels (#, ##, ###, etc.).

Good:

Some paragraph text.

## New Section

More text here.

Bad:

Some paragraph text.
## New Section
More text here.

Lists

Lists should be surrounded by blank lines.

Good:

Introduction paragraph.

- Item one
- Item two
- Item three

Conclusion paragraph.

Bad:

Introduction paragraph.
- Item one
- Item two
- Item three
Conclusion paragraph.

URLs and Emails

Never use bare URLs or email addresses. Always wrap them.

Options:

• •Angle brackets: <https://example.com> or <email@example.com>
• •Link syntax: [link text](https://example.com)

Keep angle brackets even when applying other markup like strikethrough or bold.

Good:

• •Visit https://example.com for more info
• •Contact us at support@example.com
• •See the documentation
• •old@example.com is deprecated, use new@example.com

Bad:

• •Visit https://example.com for more info
• •Contact us at support@example.com

YAML Front Matter

When using front matter, format tags as a list:

---
tags:
  - topic1
  - topic2
created: 2026-01-01
updated: 2026-01-01
---

Always include a blank line after the closing --- before the first header.

Code Blocks

Always specify a language or type:

• •markdown for markdown examples
• •yaml for YAML
• •json for JSON
• •text for plain text, emails, or other unformatted content
• •Appropriate language identifier for code (js, python, bash, etc.)

Good:

```python
def hello():
    print("Hello")
```

Bad:

```
def hello():
    print("Hello")
```

Tables

Avoid tables unless explicitly requested or truly necessary for the content. Convert tabular information to prose or bullet lists when possible.

When tables are necessary:

• •Leave a space between the column separator and content
• •Surround tables with blank lines

| Column 1 | Column 2 |
| -------- | -------- |
| value 1  | value 2  |

Document Structure

• •Use a single top-level # heading per document
• •Use ## and lower for sections
• •Prefer prose over excessive formatting
• •Let the content hierarchy emerge from headers, not visual tricks