markdown-document-structurer

Markdown Document Structurer

Reorganize and improve markdown documents while preserving content integrity.

Workflow

1. Analyze Current Structure

Automated analysis:

python scripts/analyze_structure.py <markdown_file>

Manual analysis:

• Read the document to understand content and purpose
• Identify document type (README, technical doc, tutorial, article)
• Note structural issues and inconsistencies

2. Identify Issues

Check for:

Heading Hierarchy:

• Multiple h1 headings
• Skipped heading levels (h1 → h3)
• Inconsistent heading progression

Table of Contents:

• Missing TOC when document has 3+ main sections
• Outdated TOC that doesn't match current structure
• Incorrect anchor links

Formatting Consistency:

• Mixed list markers (-, *, +)
• Code blocks without language specification
• Inconsistent emphasis styles (** vs __, * vs _)
• Inconsistent link formats

Content Issues:

• Missing standard sections for document type
• Duplicate or redundant sections
• Poor section organization
• Grammar and spelling errors

3. Plan Restructuring

Determine:

• Target document structure based on type (see [document-patterns.md](references/document-patterns.md))
• Which sections to add, merge, or reorganize
• Formatting standards to apply (see [markdown-best-practices.md](references/markdown-best-practices.md))
• Content improvements needed

4. Apply Restructuring

Follow this order:

Step 1: Fix Heading Hierarchy

• Ensure single h1 for document title
• Fix skipped levels
• Maintain logical progression

Step 2: Reorganize Sections

• Reorder sections for logical flow
• Merge duplicate sections
• Add missing standard sections
• Remove redundant content

Step 3: Generate/Update TOC

• Create TOC if document has 3+ sections
• Update existing TOC to match structure
• Ensure anchor links are correct

Step 4: Standardize Formatting

• Use - for unordered lists
• Specify language for code blocks
• Use bold and italic consistently
• Standardize link formats
• Fix spacing and blank lines

Step 5: Improve Content

• Fix grammar and spelling
• Improve clarity where needed
• Preserve all original information
• Maintain author's voice and style

5. Verify Results

Check:

• All content preserved
• Heading hierarchy correct
• TOC matches structure
• Formatting consistent
• No broken links
• Grammar improved
• Document flows logically

Document Type Guidelines

README Files

Standard structure:

1. Title and brief description
2. Table of contents (if 3+ sections)
3. Features/highlights
4. Installation
5. Usage examples
6. Configuration
7. Contributing
8. License

Required sections:

• Installation instructions
• Basic usage example
• License information

See [document-patterns.md](references/document-patterns.md) for detailed README patterns.

Technical Documentation

Standard structure:

1. Title
2. Overview
3. Table of contents
4. Prerequisites
5. Installation/setup
6. Basic usage
7. Advanced usage
8. API reference (if applicable)
9. Examples
10. Troubleshooting
11. Additional resources

Required sections:

• Prerequisites
• Installation/setup
• Basic usage examples

Long-Form Content (Articles, Tutorials)

Standard structure:

1. Title
2. Introduction/hook
3. Table of contents
4. Main content sections
5. Conclusion
6. References/resources

For tutorials specifically:

• Prerequisites section
• Step-by-step structure
• Verification/testing steps
• Next steps

Formatting Standards

Headings

• Single h1 (#) for title
• Sequential levels (no skipping)
• One blank line before and after

Lists

• Use - for unordered lists
• Proper indentation (2 or 4 spaces)
• One blank line before and after

Code Blocks

• Always specify language: ```python
• One blank line before and after

Emphasis

• Use bold for strong emphasis
• Use italic for emphasis
• Avoid mixing styles

Links

• Use inline format: [text](url)
• Use reference format for repeated links

Spacing

• One blank line between sections
• No trailing whitespace
• Consistent blank line usage

See [markdown-best-practices.md](references/markdown-best-practices.md) for complete formatting guidelines.

Content Preservation Rules

Always preserve:

• All factual information
• Code examples
• Technical details
• Links and references
• Author's key points

Safe to modify:

• Grammar and spelling
• Sentence structure for clarity
• Section organization
• Formatting consistency

Never:

• Remove content without user approval
• Change technical accuracy
• Alter code examples (except formatting)
• Modify links or URLs

Handling Redundancy

Identifying Duplicates

• Same section headings
• Repeated installation instructions
• Duplicate code examples
• Overlapping explanations

Consolidation Strategy

1. Identify all duplicate content
2. Keep the most complete version
3. Merge complementary information
4. Add cross-references if needed
5. Remove redundant sections

Example

Before:

## Installation
npm install package

## Installing the Package
Run npm install package

## Setup
Install with npm install package

After:

## Installation

Install the package using npm:

npm install package

Adding Missing Sections

Detection

Check document type and identify missing standard sections:

• README: Installation, Usage, License
• Technical docs: Prerequisites, Examples, Troubleshooting
• Tutorials: Prerequisites, Verification steps, Next steps

Adding Sections

1. Determine appropriate location in document flow
2. Add section with appropriate heading level
3. Include placeholder content or note that section needs completion
4. Inform user about added sections

Example

## Installation

*Installation instructions to be added*

## Usage

*Usage examples to be added*

Table of Contents Generation

When to Generate

• Document has 3+ main sections (h2)
• Technical documentation
• Long-form content (>500 lines)

Placement

• After title and description
• Before main content
• Use h2: ## Table of Contents

Format

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
  - [Subsection 2.1](#subsection-21)
  - [Subsection 2.2](#subsection-22)
- [Section 3](#section-3)

Anchor Generation

• Lowercase all text
• Replace spaces with hyphens
• Remove special characters except hyphens
• Example: "API Reference Guide" → #api-reference-guide

Grammar and Spelling

Approach

• Fix obvious errors
• Improve clarity without changing meaning
• Maintain author's voice and style
• Preserve technical terminology

Common Fixes

• Subject-verb agreement
• Tense consistency
• Article usage (a, an, the)
• Common spelling errors
• Punctuation

Caution

• Don't change technical terms
• Preserve code-related text exactly
• Keep domain-specific language
• Maintain intentional informal tone

Output Format

After restructuring, provide:

1. Summary of changes:
2. Structural improvements
3. Sections added/removed/merged
4. Formatting fixes
5. Content improvements

1. Restructured document:
2. Complete markdown with all changes applied

1. Notes:
2. Any sections needing user input
3. Recommendations for further improvement
4. Warnings about significant changes

Best Practices

Analysis

• Understand document purpose before restructuring
• Identify document type to apply appropriate structure
• Use automated analysis script for quick assessment
• Note all issues before making changes

Restructuring

• Make one type of change at a time
• Preserve all content unless clearly redundant
• Maintain logical flow and readability
• Follow established patterns for document type

Quality

• Verify all links work
• Ensure TOC matches structure
• Check heading hierarchy
• Confirm formatting consistency
• Test code blocks if possible