Generate Documentation Indexes

Overview

The generate-indexes.sh script automatically creates or updates index.md files for documentation subdirectories. These indexes provide organized, categorized views of all documentation with status badges and metadata.

When to Use

Run the index generator when:

• Adding new documentation: After creating new markdown files
• Updating document status: When changing Draft → Approved, etc.
• Reorganizing documentation: After moving or renaming files
• Before committing: To ensure indexes are up-to-date (can be automated with pre-commit hooks)

Running the Script

Manual Execution

From the repository root:

./docs/scripts/generate-indexes.sh

Output Example:

=== Documentation Index Generator ===

Processing architecture/
  ✓ Generated /home/chris/workspace/syrf/docs/architecture/index.md
Processing decisions/
  ✓ Generated /home/chris/workspace/syrf/docs/decisions/index.md
Processing features/
  No markdown files found, skipping
Processing how-to/
  ✓ Generated /home/chris/workspace/syrf/docs/how-to/index.md
Processing planning/
  ✓ Generated /home/chris/workspace/syrf/docs/planning/index.md

✓ Index generation complete

What Gets Generated

The script creates indexes for these directories:

• docs/architecture/ - Architecture & Reference Documentation
• docs/decisions/ - Architecture Decision Records (ADRs)
• docs/features/ - Feature Briefs & Technical Plans
• docs/how-to/ - How-To Guides
• docs/planning/ - Planning & Discussion Documents

Each generated index.md includes:

1. YAML Frontmatter: Proper metadata for validation
2. Directory Title: Human-readable title and description
3. Statistics: Last updated date and total document count
4. Document Listings: Organized by doc-type with status badges
5. Status Legend: Explanation of badge meanings
6. Footer Note: Indicates auto-generation (warns against manual edits)

Index Structure

Example Generated Index

---
doc-type: "Reference"
status: "Approved"
author: "Auto-generated"
created: 2025-11-24
updated: 2025-11-24
zenhub-ticket: "N/A"
tags: ["index", "how-to"]
---

# How-To Guides

Step-by-step guides for common tasks and procedures.

**Last Updated**: 2025-11-24
**Total Documents**: 19

---

## How-To Documents

- 🟢 [CI/CD Workflow Overview](ci-cd-workflow.md) - *Approved*
- 🟡 [Setup Sentry Integration](setup-sentry-integration.md) - *Draft*
- 🔴 Deprecated: Old Setup Guide - *Deprecated*

---

**Status Legend:**
- 🟡 Draft - Work in progress
- 🔵 In-Review - Under review
- 🟢 Approved - Reviewed and approved
- ✅ Completed - Implementation complete
- 🔴 Deprecated - No longer applicable

---

*This index is automatically generated by `generate-indexes.sh`. Do not edit manually.*

Status Badges

Status	Badge	Meaning
Draft	🟡	Work in progress
In-Review	🔵	Under review
Approved	🟢	Reviewed and approved
Completed	✅	Implementation complete
Deprecated	🔴	No longer applicable

How It Works

1. YAML Frontmatter Extraction

The script reads each markdown file and extracts:

• doc-type: Used to group documents by type
• status: Determines the status badge
• Title from first # heading (after frontmatter)

2. Document Grouping

Documents are grouped by doc-type:

• ADR: Architecture Decision Records
• Feature: Feature briefs and plans
• Technical: Technical implementation docs
• How-To: Step-by-step guides
• Reference: Reference documentation
• Discussion: Planning and discussion docs

3. Index Generation

For each directory:

1. Scans for markdown files (excluding index.md)
2. Groups by doc-type
3. Sorts alphabetically within each group
4. Generates formatted markdown with badges
5. Writes to index.md

Automation Options

Option 1: Pre-Commit Hook (Recommended)

Add to .pre-commit-config.yaml:

  - repo: local
    hooks:
      - id: generate-indexes
        name: Generate Documentation Indexes
        entry: ./docs/scripts/generate-indexes.sh
        language: script
        files: ^docs/.*\.md$
        pass_filenames: false

Benefits:

• Indexes always up-to-date before commits
• No manual intervention needed
• Catches missing index updates

Option 2: CI/CD Integration

Add to GitHub Actions workflow (.github/workflows/docs-validation.yml):

- name: Generate documentation indexes
  run: ./docs/scripts/generate-indexes.sh

- name: Check for index changes
  run: |
    if [[ -n $(git status --porcelain docs/**/index.md) ]]; then
      echo "❌ Indexes out of date. Run ./docs/scripts/generate-indexes.sh"
      git diff docs/**/index.md
      exit 1
    fi

Benefits:

• Validates indexes are current on PRs
• Prevents stale indexes from merging
• No performance impact on local development

Option 3: Manual (Current Approach)

Run the script manually when needed:

./docs/scripts/generate-indexes.sh
git add docs/**/index.md
git commit -m "chore(docs): update documentation indexes"

Benefits:

• Full control over when indexes update
• No automation overhead
• Good for initial setup

Troubleshooting

Script Not Found or Not Executable

Problem: Permission denied or command not found

Solution:

chmod +x docs/scripts/generate-indexes.sh

Wrong Titles or Descriptions

Problem: Index shows generic titles like "Unknown Documentation"

Solution: Check that title_map and description_map in script include your directory name

Missing Documents in Index

Problem: New files not appearing in index

Solution:

1. Verify file has YAML frontmatter with doc-type field
2. Ensure file is in correct directory (not nested)
3. Check file ends with .md extension
4. Run script with verbose mode (if added) or check script output

Duplicate Entries

Problem: Same document appears multiple times

Solution: This shouldn't happen. If it does, check for:

• Duplicate files with different casing
• Symbolic links
• Files with special characters in names

Customization

Adding New Directories

Edit generate-indexes.sh and add to SUBDIRS array:

SUBDIRS=(
    "architecture"
    "decisions"
    "features"
    "how-to"
    "planning"
    "your-new-directory"  # Add here
)

Also add custom titles/descriptions:

declare -A title_map=(
    # ... existing entries ...
    ["your-new-directory"]="Your Custom Title"
)

declare -A description_map=(
    # ... existing entries ...
    ["your-new-directory"]="Your custom description."
)

Changing Status Badges

Edit the badge case statement in generate-indexes.sh:

case "$status" in
    "Draft") badge="🟡" ;;
    "In-Review") badge="🔵" ;;
    "Approved") badge="🟢" ;;
    "Completed") badge="✅" ;;
    "Deprecated") badge="🔴" ;;
    "Your-Status") badge="🟣" ;;  # Add custom status
    *) badge="⚪" ;;
esac

Best Practices

1. Run before committing: Ensure indexes are current
2. Don't edit indexes manually: They're auto-generated and will be overwritten
3. Check git diff: Review index changes before committing
4. Commit indexes with document changes: Keep them in sync
5. Use automation: Consider pre-commit hooks for convenience

Related Documentation

• Documentation Framework Guide - YAML frontmatter requirements
• Setup Pre-Commit Hooks - Automation configuration
• CI/CD Validation Workflow - CI integration

Script Location

• Script: docs/scripts/generate-indexes.sh
• Documentation: This file
• Generated Files: docs/{subdirectory}/index.md