gh-mvdmakesthings-skills-markdown-optimizer/skills/markdown-optimizer/references/optimization-patterns.md

Advanced Markdown Optimization Patterns

This reference provides patterns for manual markdown optimization beyond what the automated script handles.

Content Restructuring Patterns

Verbose Prose → Structured Format

Pattern: Convert explanatory lists to tables

Before:

The API supports three authentication methods. OAuth2 is recommended for web applications and provides secure token-based authentication. API keys are suitable for server-to-server communication and are simpler to implement. Basic Auth should only be used for testing as it's less secure.

After:

| Method | Use Case | Security |
|--------|----------|----------|
| OAuth2 | Web applications | High (recommended) |
| API Keys | Server-to-server | Medium |
| Basic Auth | Testing only | Low |

Pattern: Convert sequential steps to definition lists

Before:

To deploy the application, first build the Docker image using the Dockerfile in the root directory. Then push the image to your container registry. After that, update the Kubernetes deployment manifest with the new image tag. Finally, apply the manifest using kubectl.

After:

**Build**
: Create Docker image from root Dockerfile

**Push**
: Upload image to container registry

**Update**
: Modify K8s manifest with new tag

**Deploy**
: Apply manifest via kubectl

Consolidate Redundant Examples

Pattern: Merge similar code examples

Before:

# Example 1: Create user
user = create_user(name="Alice")

# Example 2: Create another user
user2 = create_user(name="Bob")

# Example 3: Create admin user
admin = create_user(name="Charlie", role="admin")

After:

# Create users with optional role
user = create_user(name="Alice")  # default role
admin = create_user(name="Charlie", role="admin")

Strip Unnecessary Markdown Syntax

Pattern: Remove emphasis that doesn't add semantic value

Before:

**Note:** The API endpoint is **very important** and you should **always** include authentication.

After:

Note: Include authentication with all API requests.

Pattern: Simplify excessive nested lists

Before:

- Step 1
  - Substep A
    - Detail i
    - Detail ii
  - Substep B

After:

**Step 1**
- A: Detail i, Detail ii
- B: [description]

Diagram Creation Patterns

Process Flows → Flowchart

Indicators: "step 1", "then", "next", "process", "workflow"

flowchart TD
    A[Start] --> B[Authenticate]
    B --> C{Valid?}
    C -->|Yes| D[Make Request]
    C -->|No| E[Error]
    D --> F[Process Response]

Relationships → Graph

Indicators: "depends on", "inherits from", "composed of"

graph LR
    A[User Model] --> B[Base Model]
    A --> C[Timestamped Mixin]
    D[Admin Model] --> A

Architecture → Component Diagram

Indicators: "architecture", "components", "system design", "layers"

graph TB
    subgraph Frontend
        A[Web UI]
    end
    subgraph Backend
        B[API Layer]
        C[Business Logic]
        D[Data Layer]
    end
    A --> B
    B --> C
    C --> D

State Transitions → State Diagram

Indicators: "status", "state", "transitions", "lifecycle"

stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Approved
    Review --> Rejected
    Approved --> Published
    Rejected --> Draft

Content Compression Techniques

Remove Filler Phrases

Remove:

• "It's important to note that..."
• "As mentioned previously..."
• "In order to..."
• "Due to the fact that..."
• "For the purpose of..."

Replace with direct statements.

Use Domain Abbreviations

When context is clear:

• Authentication → Auth
• Application → App
• Configuration → Config
• Documentation → Docs
• Environment → Env
• Repository → Repo

Consolidate Repeated Context

Before:

## User Creation Endpoint
The user creation endpoint allows you to create new users.

## User Update Endpoint
The user update endpoint allows you to update existing users.

## User Delete Endpoint
The user delete endpoint allows you to delete users.

After:

## User Endpoints

| Endpoint | Purpose |
|----------|---------|
| POST /users | Create |
| PUT /users/:id | Update |
| DELETE /users/:id | Delete |

Front-Matter Best Practices

Essential Fields

Always include:

---
title: "Document Title"
tokens: 1234  # Estimated token count
optimized_for_llm: true
---

Optional but Valuable Fields

related_docs:
  - auth.md
  - api-reference.md

dependencies:
  - python>=3.8
  - requests

audience: developers  # or: beginners, experts, etc.

status: draft  # or: review, published, deprecated

TOC Depth Guidelines

• For documents <500 tokens: H1, H2 only
• For documents 500-2000 tokens: H1, H2, H3
• For documents >2000 tokens: Full hierarchy

Optimization Decision Tree

Is the document <200 tokens?
├─ Yes: Minimal optimization (front-matter only)
└─ No: Continue

Does it contain repetitive examples?
├─ Yes: Consolidate examples
└─ No: Continue

Are there process descriptions?
├─ Yes: Consider flowchart diagram
└─ No: Continue

Are there relationship descriptions?
├─ Yes: Consider graph diagram
└─ No: Continue

Is prose verbose?
├─ Yes: Convert to tables/lists
└─ No: Continue

Apply final polish:
- Normalize headings
- Remove noise
- Add front-matter

When NOT to Optimize

Avoid optimization for:

• Creative writing (stories, poems)
• Legal documents (precision required)
• Already-concise technical specs
• Code with extensive comments (explanatory value)
• Documents with careful narrative structure

Quality Checks

After optimization, verify:

1. ✅ All key information preserved
2. ✅ Logical flow maintained
3. ✅ Code examples still functional
4. ✅ Cross-references intact
5. ✅ Front-matter accurate
6. ✅ Token count reduced or value added