jungho-git/markdown

Markdown

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

Scope

Use this rule when:

• writing or editing .md files
• authoring READMEs, changelogs, reports, or documentation pages
• editing skill SKILL.md or references/EXAMPLE.md files
• reviewing Markdown rendering and structure

Markdown should be easy to scan and render predictably.

Core Rules

• Use ATX headings (#, ##, ###).
• Do not skip heading levels.
• Leave exactly one blank line before and after headings, code blocks, and lists.
• Use fenced code blocks with an explicit language tag.
• Keep one list-marker style per local list block.
• Use reference-style links when the same URL appears more than once.
• Keep prose lines at or below 120 characters where practical.
• Do not use raw HTML unless Markdown cannot express the structure.

Skill Docs

• SKILL.md keeps one H1 title at the top.
• Place the references/EXAMPLE.md pointer block immediately under the H1.
• Start main body sections at H2.
• In references/EXAMPLE.md, start with # Examples and a short intro.
• Use --- dividers before each H2 once the doc adopts the convention.
• Preserve numbered taxonomies only when the existing document needs stable ordered examples.

Tables

• Keep pipe-table columns readable.
• Use padding only inside table columns.
• Do not vertically align prose, code, YAML, JSON, or assignment blocks.

Tone

• Write in active voice.
• Prefer short declarative sentences.
• Use numbered lists only for true sequences.
• Avoid filler words.

Validation Focus

• heading hierarchy
• code fence language tags
• balanced code fences
• broken or redundant links
• trailing whitespace
• mixed local list markers
• missing H2 dividers in maintained instruction docs