Markdown Optimization

Patterns and techniques for analyzing and optimizing markdown documentation.

Quick Start

Size Check

Check single file

wc -l docs/README.md

Check all markdown in folder

find docs -name "*.md" -exec wc -l {} ; | sort -n

Find files over 500 lines

find . -name "*.md" -exec sh -c
'lines=$(wc -l < "$1"); [ "$lines" -gt 500 ] && echo "$1: $lines"' _ {} ;

Structure Validation

Check for common issues:

• Missing TOC (files > 100 lines)

• Heading hierarchy violations (h1 → h3, skipping h2)

• Sections over 200 lines

Document Profiles

Different document types have different optimization rules.

Authoritative limits: For Claude Code artifacts (agent , skill , command , guidelines ), size limits are defined in GUIDELINES.md. This skill enforces those limits.

Profile Target Key Focus

claude-md

Project context Concise, table-heavy

architecture

System design Diagrams external, decisions linked

domain

Business docs Entity tables, numbered rules

feature-spec

Feature docs Separated concerns

readme

Entry points Quick start, links

agent

Agent prompts Lean, reference skills

skill

Skill docs Progressive disclosure

command

Slash commands Focused action

guidelines

Meta-knowledge Modular structure

Full profile definitions: See profiles.md

Core Analysis Patterns

1. Size Analysis

Size Metrics

Actions for oversized files:

• Split by topic/domain

• Extract examples to separate files

• Convert prose to tables

• Move detailed content to references

2. Duplication Detection

Look for:

• Identical paragraphs across files

• Same concepts explained differently

• Copy-pasted code blocks

• Repeated tables/lists

Duplication Findings

3. Structure Assessment

Heading Hierarchy:

Title (h1) - Only one per file

Section (h2)

Subsection (h3)

Detail (h4) - Use sparingly

Issues to flag:

• Multiple h1 headings

• Skipped levels (h1 → h3)

• Sections > 200 lines without subsections

• Missing TOC for files > 100 lines

4. Link Validation

Find all markdown links

grep -oP '[.?](.?)' file.md

Check if targets exist

Internal: text or text

External: text

Common issues:

• Broken relative paths

• Missing anchor targets

• Orphaned files (not linked anywhere)

5. Compaction Opportunities

Identify verbose patterns that can be condensed.

Full techniques: See compaction-patterns.md

Quick reference:

Pattern Before After Savings

Prose list Paragraph with items Bullet list 40-60%

Explanation table Multi-paragraph Table 50-70%

Code comments Heavily commented Self-documenting 30-50%

Repeated structure Copy-paste sections Template + instances 60-80%

Optimization Techniques

Convert Prose to Tables

Before (12 lines):

The system supports three user roles. Administrators have full access to all features including user management, system configuration, and reporting. Managers can access reports and manage their team members but cannot modify system settings. Regular users can only access their own data and perform basic operations within their assigned scope.

After (6 lines):

Extract Examples

Before (inline, 50 lines):

API Usage

Here's how to use the API:

# 40 lines of code

**After** (referenced, 5 lines):
```markdown
## API Usage

See [examples/api-usage.md](examples/api-usage.md) for complete examples.

Quick start:
```python
client.get("/api/resource")

### Use Progressive Disclosure

**Before** (everything inline):
```markdown
## Feature X
[200 lines of content]

After (layered):

## Feature X

[Core concept - 30 lines]

**Advanced configuration**: See [feature-x-advanced.md](references/feature-x-advanced.md)
**API reference**: See [feature-x-api.md](references/feature-x-api.md)

Custom Profiles

Define custom profiles in .claude/config/md-profiles.yaml
:

profiles:
  # Custom profile for API docs
  api-docs:
    patterns:
      - "docs/api/**"
      - "**/api-*.md"
    max_lines: 400
    rules:
      - require_toc: true
      - require_examples: true
      - max_section_lines: 150
    compaction:
      - prose_to_table: true
      - extract_examples: true

  # Custom profile for internal docs
  internal:
    patterns:
      - "internal/**"
    max_lines: 800  # More lenient
    rules:
      - require_toc: false

Report Templates

Audit Report Structure

# Markdown Optimization Report

## Target: {path}
## Profile: {profile}
## Generated: {timestamp}

## Executive Summary
- Files analyzed: N
- Issues found: N (X critical, Y warnings)
- Estimated optimization potential: N lines (X%)

## Detailed Findings

### Size Issues
[Table of oversized files]

### Structure Issues
[Table of structural problems]

### Duplication
[Table of duplicated content]

### Broken Links
[Table of link issues]

## Recommendations
[Prioritized action items]

Integration with Commands

This skill supports:

- /docs:optimize-md
 - Primary command (use --profile guidelines
 for GUIDELINES.md ecosystem)

Related

- GUIDELINES.md - Authoritative source for artifact size limits and quality standards

- Profile Definitions - Detection patterns and optimization rules per profile

- Compaction Patterns - Techniques for reducing verbosity