Markdown Writing Practices

Markdown Writing Practices

Application skill for Markdown style learning (from the archived awesome-guidelines style capsules). For HTML/CSS page templates, load frontend-markup-practices. For platform wiki syntax (Confluence), use stack conventions.

Core Principle

Documentation Markdown is maintainable plain text, one H1, wrapped prose, fenced code, descriptive links, minimal HTML.

When to Use / NOT

• README, skills, ADRs, handbook pages, repo docs under docs/ or references/.
• Reviewing doc PRs for structure and link hygiene.

NOT when:

• Generated API docs from source comments, validate generator templates.
• Rich wiki with non-Markdown macros only, use platform foundation.

Workflow

1. Layout, H1, intro, TOC, headings, 80-col wrap (markdown-style-document-layout.md).
2. Lists & code, lazy numbering, fences, languages (markdown-style-lists-code.md).
3. Links & media, paths, reference links, alt text (markdown-style-links-media.md).
4. Tables, 2D data only; Markdown not HTML (markdown-style-tables-portability.md).
5. Verify, markdownlint/remark + git diff --check on changed .md files.

Red Flags

• Multiple H1 or Setext headings
• [here](url) / bare URL link text
• ../../ relative link chains
• Indented code blocks without language
• Trailing whitespace for line breaks
• HTML layout where Markdown suffices
• Tables that should be lists
• Images without alt text

Verification

• markdownlint (or project remark config) on changed files
• git diff --check clean
• Render preview spot-check for TOC, fences, tables
• Capsule checklist on doc review

References

• awesome-guidelines/references/markdown-style-learning-note.md
• awesome-guidelines/references/markdown-style-document-layout.md
• awesome-guidelines/references/markdown-style-lists-code.md
• awesome-guidelines/references/markdown-style-links-media.md
• awesome-guidelines/references/markdown-style-tables-portability.md