Markdown authoring

Format and validate Markdown files following GitHub Flavored Markdown (GFM) standards, VS Code language features, and organizational conventions with automated structural fixes and manual semantic review.

When to use this skill

• Creating or modifying any Markdown file (.md )

• Fixing markdown linting errors

• Setting up markdown tooling in a new repository

• Validating markdown files before committing

• Converting content to conform to organizational markdown standards

Required tools

• read , edit — core file manipulation

• execute — run linting tasks and commands

• search — find markdown files and patterns

Workflow

Step 1: Run automated linting with fixes

Execute markdownlint with auto-fix to resolve structural issues:

npx markdownlint-cli2 --no-globs {filepath} --fix

Note: Use --no-globs when linting a single explicit file to prevent unintended glob expansion. For repository-wide linting or CI jobs, omit the flag or use explicit globs/CI-configured file lists.

What auto-fix handles:

• Bullet style (converts * and + to - )

• Header style (converts Setext to ATX)

• Blank lines around headers and code blocks

• Code fence style and language identifiers

• Nested code block fence lengths

What auto-fix does NOT handle (requires manual review):

• Sentence case in headers

• Sentence case in bold labels

• Content organization

• Link validity

• Semantic correctness

Step 2: Manual semantic review and fixes

Review the file for issues that automated linting cannot fix:

Headers:

• Convert to sentence case: "How To Use" → "How to use"

• Capitalize only first word + proper nouns (GitHub, TypeScript, MADR)

• Lowercase articles (a, an, the), prepositions (of, to, for), conjunctions (and, but, or)

Bold labels at list start:

• Convert to sentence case: "Next Steps:" → "Next steps:"

Reference syntax:

• Remove backticks from #file: references: #file:path → #file:path

• Remove trailing punctuation after #file: tokens

• Replace #file: with markdown links in entry point files (AGENTS.md)

Lists:

• Convert ordered lists to unordered hyphen lists for non-sequential items

• Ensure proper indentation alignment

Code blocks:

• Add language identifier to all fenced blocks (use plaintext if unknown)

• Ensure nested blocks have longer outer fences

See formatting standards for complete rules.

Step 3: Validate with linting

Run markdownlint without fixes to verify zero errors:

npx markdownlint-cli2 --no-globs {filepath}

Expected output: No errors or warnings

If errors remain:

• Review error messages for specific violations

• Fix issues manually

• Re-run validation

• Repeat until zero errors

Step 4: Content quality checks

Verify content-level requirements:

• Links: All internal links resolve to existing files

• Code fences: All blocks have language identifiers

• Headers: Sentence case, ATX style, sequential hierarchy (no skipping levels)

• Lists: Hyphen bullets only, proper indentation

• End of file: Blank line, --- separator, "Last updated: {date}" footer (see formatting-standards for exclusions: .github//*.md, README.md, AGENTS.md, .agents//.md, docs/adr/.md)

• Diagrams: Mermaid diagrams use stroke styling (not fill colors)

• HTML: Only allowed elements, all images have alt text

See validation checklist for complete quality checks.

Step 5: Optional continuous feedback

For iterative editing sessions, use watch mode for continuous feedback:

npx markdownlint-cli2 --no-globs {filepath} --watch

This provides real-time linting feedback during edits.

Step 6: Repository setup (if tooling missing)

If markdown tooling is not configured in the repository, set up the complete stack:

• Install VS Code extensions (vscode-markdownlint, github-markdown-preview, EditorConfig)

• Configure VS Code settings (defaultFormatter, formatOnSave, codeActionsOnSave)

• Create linting configuration (.markdownlint-cli2.jsonc with baseline rules)

• Add VS Code tasks ("Lint: Markdown", "Lint: Markdown (auto-fix)")

• Verify alignment (settings.json, extensions.json, tasks.json, editorconfig)

• Test setup (run linting on existing files)

See setup guide for step-by-step configuration.

Completion criteria

• All structural linting errors resolved (zero errors from markdownlint-cli2)

• All semantic issues fixed (sentence case headers, bold labels)

• All reference syntax corrected (#file:, markdown links)

• All content quality checks passed (links, fences, hierarchy)

• End-of-file formatting applied where required

• File committed to repository

Common pitfalls

Relying solely on automated linting:

• Auto-fix handles structure, not semantics

• Manual review for sentence case is mandatory

• Content organization requires human judgment

Using #file: in entry point files:

• AGENTS.md and root instructions auto-load in many contexts

• #file: references cascade and cause context bloat

• Use standard markdown links instead

Skipping validation after manual edits:

• Always re-run linting after manual changes

• New edits may introduce new violations

• Zero-error verification is required

Incorrect reference syntax:

• Backticks break #file: token parsing

• Trailing punctuation breaks token resolution

• Wrong #tool: format for MCP servers

One-time setup

See markdown tooling setup guide for markdownlint-cli2 installation and VS Code extension setup.

Additional references

• GitHub Flavored Markdown specification

• markdownlint-cli2 documentation