Update documentation structure and enhance .gitignore

- Added generated index files and report directories to .gitignore to prevent unnecessary tracking of transient files. - Updated README links to reflect new documentation paths for better navigation. - Improved documentation organization by ensuring all links point to the correct locations, enhancing user experience and accessibility.
2025-12-12 21:18:55 -08:00
parent 664707d912
commit fe0365757a
106 changed files with 4666 additions and 2294 deletions
--- a/docs/meta/MARKDOWN_INDEX_README.md
+++ b/docs/meta/MARKDOWN_INDEX_README.md
@@ -0,0 +1,128 @@
+# 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](./MARKDOWN_REFERENCE.md)**
+   - Human-readable index of all Markdown files
+   - Organized by category
+   - Includes headings, line numbers, and file details
+
+2. **[MARKDOWN_REFERENCE.json](./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](./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
+
+```bash
+# 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
+
+```bash
+# List all files in a category
+cat docs/MARKDOWN_REFERENCE.json | jq '.by_category["proxmox"]'
+```
+
+### Find Cross-References
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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](./README.md) - Main documentation index
+- [Deduplication Report](./MARKDOWN_DEDUPLICATION_REPORT.md) - Detailed analysis
+