markdown-authoring

# 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

1. Structure first, wording second.
2. Keep Markdown lint-clean and deterministic.
3. Use code fences with explicit language tags.
4. Keep file-level conventions consistent across the repository.

## Deterministic Workflow

1. Identify document type (README, guide, API doc, changelog).
2. Apply template and section order from references.
3. Write content with concise headings and actionable examples.
4. 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`
5. Validate CI/pre-commit integration for regression prevention.

## Quick Commands

### Lint all Markdown files

```bash
bunx markdownlint-cli2 "**/*.md"
```

Expected result: no errors for staged or target files.

### Lint one skill folder

```bash
bunx markdownlint-cli2 "skills/documentation/markdown-authoring/**/*.md"
```

Expected result: folder-specific Markdown issues reported or zero errors.

### Run repository checks

```bash
bunx @biomejs/biome check .
```

Expected result: non-Markdown formatting/lint issues also caught.

### Evaluate this skill quality

```bash
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

```bash
./scripts/read-reference.sh syntax-headings
```

Expected result: displays reference content for the requested topic.

### Check document style compliance

```bash
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](references/syntax-headings.md)
- [Syntax: Lists](references/syntax-lists.md)
- [Syntax: Code Blocks](references/syntax-code-blocks.md)
- [Syntax: Links & Images](references/syntax-links-images.md)
- [Syntax: Formatting](references/syntax-formatting.md)
- [Syntax: Other Elements](references/syntax-other-elements.md)
- [Docs: README](references/docs-readme.md)
- [Docs: Organization](references/docs-organization.md)
- [Docs: Writing Style](references/docs-writing-style.md)
- [Docs: API](references/docs-api.md)
- [Docs: Changelog](references/docs-changelog.md)
- [Lint: Config](references/lint-config.md)
- [Lint: Rules](references/lint-rules.md)
- [Lint: CLI](references/lint-cli.md)
- [Lint: CI](references/lint-ci.md)
- [Lint: API](references/lint-api.md)