fe0365757a
- 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.
129 lines
3.2 KiB
Markdown
129 lines
3.2 KiB
Markdown
# 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
|
|
|