Sankofa/docs/meta/MARKDOWN_INDEX_README.md

Markdown Documentation Index

Last Updated: 2025-01-09

This directory contains comprehensive indexes and analysis of all Markdown documentation in the Sankofa Phoenix project.

---

Quick Reference

Index Files

1. MARKDOWN_REFERENCE.md

   • Human-readable index of all Markdown files
   • Organized by category
   • Includes headings, line numbers, and file details

2. MARKDOWN_REFERENCE.json

   • Machine-readable comprehensive index (186KB)
   • Detailed mapping of content to files and line numbers
   • Includes: headings, sections, code references, links, cross-references

3. MARKDOWN_DEDUPLICATION_REPORT.md

   • Analysis of duplicate and similar content
   • Recommendations for consolidation
   • Organization assessment

---

Statistics

• Total Markdown Files: 279
• Unique Files: 278 (1 duplicate removed)
• Total Headings Indexed: 6,439
• Cross-References: 498 links between files
• Categories: 9 main categories

Files by Category

• docs/: 113 files (root level documentation)
• proxmox/: 53 files (Proxmox-specific documentation)
• archive/: 50 files (historical/archived documentation)
• status/: 18 files (status reports)
• other/: 26 files (miscellaneous locations)
• architecture/: 6 files (architecture documentation)
• runbooks/: 7 files (operational runbooks)
• api/: 4 files (API documentation)
• portal/: 1 file (Portal documentation)

---

Most Common Headings

1. "Overview" - 82 occurrences
2. "Related Documentation" - 76 occurrences
3. "Next Steps" - 75 occurrences
4. "Troubleshooting" - 48 occurrences
5. "Summary" - 37 occurrences

---

Usage

Find Content by Heading

# Search in JSON index
cat docs/MARKDOWN_REFERENCE.json | jq '.by_heading["your heading"]'

# Example: Find all files with "deployment" heading
cat docs/MARKDOWN_REFERENCE.json | jq '.by_heading | to_entries | map(select(.key | contains("deployment")))'

Find Files by Category

# List all files in a category
cat docs/MARKDOWN_REFERENCE.json | jq '.by_category["proxmox"]'

Find Cross-References

# Find all files that link to a specific file
cat docs/MARKDOWN_REFERENCE.json | jq '.cross_references | to_entries | map(select(.value[].target | contains("DEPLOYMENT.md")))'

View File Details

# Get detailed information about a specific file
cat docs/MARKDOWN_REFERENCE.json | jq '.by_file["docs/DEPLOYMENT.md"]'

---

Regenerating the Index

To regenerate the index after adding/modifying Markdown files:

# Run the analysis script
python3 scripts/analyze-markdown.py

# Generate the reference mapping
python3 scripts/generate-markdown-reference.py

---

Tools

1. scripts/analyze-markdown.py

   • Finds duplicate files by content hash
   • Analyzes file structure
   • Identifies similar content

2. scripts/generate-markdown-reference.py

   • Generates comprehensive reference index
   • Maps content to files and line numbers
   • Creates cross-reference mapping

---

See Also:

• Documentation README - Main documentation index
• Deduplication Report - Detailed analysis