pantheon-org Markdown Authoring
When to Use
Use this skill when the task involves Markdown content, linting, or documentation standards.
When Not to Use
Do not use this skill for non-Markdown document formats (for example .adoc or .rst) unless conversion is part of the task.
Principles
- Structure first, wording second.
- Keep Markdown lint-clean and deterministic.
- Use code fences with explicit language tags.
- Keep file-level conventions consistent across the repository.
Deterministic Workflow
- Identify document type (README, guide, API doc, changelog).
- Apply template and section order from references.
- Write content with concise headings and actionable examples.
- Run markdownlint locally and fix violations. Re-run until zero errors are reported. If a violation persists: identify the specific rule, fix the source content or apply a narrow, justified inline exception, then re-lint. Do not proceed until lint is clean.
- Lint-fix loop:
lint fails → identify rule → fix source or add justified exception → re-lint → proceed only when clean
- Lint-fix loop:
- Validate CI/pre-commit integration for regression prevention.
Quick Commands
Lint all Markdown files
bunx markdownlint-cli2 "**/*.md"
Expected result: no errors for staged or target files.
Lint one skill folder
bunx markdownlint-cli2 "skills/documentation/markdown-authoring/**/*.md"
Expected result: folder-specific Markdown issues reported or zero errors.
Run repository checks
bunx @biomejs/biome check .
Expected result: non-Markdown formatting/lint issues also caught.
Evaluate this skill quality
sh skills/agentic-harness/skill-quality-auditor/scripts/evaluate.sh documentation/markdown-authoring --json
Expected result: updated dimension scores and grade.
Read a specific reference
./scripts/read-reference.sh syntax-headings
Expected result: displays reference content for the requested topic.
Check document style compliance
bun run check-style "path/to/document.md"
Expected result: style validation report printed to stdout.
Anti-Patterns
NEVER ship Markdown with missing fence language tags
WHY: Untyped code blocks reduce readability and tooling support.
BAD: Use plain triple backticks for code samples.
GOOD: Use typed fences like ```bash or ```ts.
Consequence: Syntax highlighting and lint checks become inconsistent.
NEVER ignore markdownlint violations by disabling broad rules
WHY: Global suppression hides real quality and maintainability issues.
BAD: Turn off multiple rules to make CI green quickly. GOOD: Fix source content or apply narrow, justified exceptions.
Consequence: Documentation quality degrades release-over-release.
NEVER use heading levels out of sequence
WHY: Skipped heading levels break document hierarchy.
BAD: Jump from ## to #### with no ###.
GOOD: Increase heading levels one step at a time.
Consequence: Navigation and accessibility suffer.
Consider adding a table of contents for documents longer than 300 lines. Optionally include anchor links in headings to improve internal navigation.
NEVER mix inconsistent list and table styles in one document
WHY: Style drift makes docs harder to scan and review.
BAD: Alternate list markers and inconsistent table pipe spacing. GOOD: Keep one list style and normalized table formatting.
Consequence: Diff noise increases and review confidence drops.
References
- Syntax: Headings
- Syntax: Lists
- Syntax: Code Blocks
- Syntax: Links & Images
- Syntax: Formatting
- Syntax: Other Elements
- Docs: README
- Docs: Organization
- Docs: Writing Style
- Docs: API
- Docs: Changelog
- Lint: Config
- Lint: Rules
- Lint: CLI
- Lint: CI
- Lint: API