# 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