markdown

name	markdown
description	Markdown Formatting Standards guidance for Fortress Rollback. Use when Markdown formatting, markdownlint configuration.

Markdown Formatting Standards

Commands

npx markdownlint "**/*.md" --config .markdownlint.json        # Check
npx markdownlint --fix "**/*.md" --config .markdownlint.json   # Auto-fix
python3 scripts/docs/check-wiki-consistency.py                      # Wiki links
python3 scripts/docs/check-links.py                                 # Link validation

ATX Heading Rules

WRONG:
#No space after hash
##  Two spaces after hash

CORRECT:
# Single space after hash
## Single space after hash

Rule	Fix
MD018: No space after #	Add single space
MD019: Multiple spaces after #	Use exactly one space
Skipped heading levels	Use sequential levels (# then ## then ###)

Link Syntax

WRONG:
[ Text with leading space](url)
[Text with trailing space ](url)
[](url)

CORRECT:
[Text](url)
[Descriptive link text](url)

Spaces inside link brackets cause rendering issues. Common cause: icon removal left trailing space -- update regex to include \s*.

Pipe Characters in Tables

Pipe | inside backticks in table cells MUST be escaped as \|. The table parser runs before inline code evaluation:

WRONG (MD056 "Too many columns"):
| `-workers <n|auto>` | Worker threads |

CORRECT:
| `-workers <n\|auto>` | Worker threads |

Heading Anchor Generation

For fragment links (#anchor), anchors are generated by:

1. Lowercase all letters
2. Spaces become hyphens
3. Remove (), [], most punctuation
4. / becomes --
5. ~ removed

Heading	Anchor
## Quick Start	#quick-start
## LAN / Local Network (~20ms RTT)	#lan--local-network-20ms-rtt
## P2P Session (peer-to-peer)	#p2p-session-peer-to-peer

Common MD051 mistake: #web-wasm-integration should be #web--wasm-integration (double hyphen for slash).

Code Fence Language

Content	Fence
Compilable Rust	```rust
Pseudo-code/patterns	```text
Shell commands	```bash
Config files	```toml, ```yaml, ```json

Using ```rust for non-compilable pseudo-code confuses users who copy-paste.

Relative Link Resolution

Links resolve from the directory containing the file:

From	To Root	Syntax
Root (/)	(already there)	(docs/user-guide.md)
docs/	../	(../README.md)
.agents/skills/<name>/	../../../	(../../../README.md)

Common mistake: a repository-root path without enough ../ segments resolves inside the skill directory. From any SKILL.md, use ../../../ to reach the root or ../other-skill/SKILL.md to link to a sibling skill.

Wiki Icon Stripping

When removing MkDocs icons, consume trailing whitespace to prevent malformed links:

# WRONG: leaves space in [Text]
re.sub(r":octicons-[a-z0-9-]+:", "", content)

# CORRECT: clean removal
re.sub(r":octicons-[a-z0-9-]+:\s*", "", content)

Configuration

Rules are in .markdownlint.json at the repository root. Pre-commit hooks run markdownlint with --fix on staged files.

Pre-Commit Checklist

• npx markdownlint '<file>' --config .markdownlint.json passes
• python3 scripts/docs/check-links.py -- no broken links
• Relative paths correct for file location
• If file moved/renamed: rg 'old-filename\.md' to find referencing files