Blog AuditorAdd missing frontmatter to root-level documentation files

[github-actions]

Problem

11 root-level documentation files in the docs/ directory have missing or incomplete YAML frontmatter, which causes issues with the Just the Docs Jekyll theme navigation and rendering.

Files with Missing Frontmatter (4 files)

These files have NO frontmatter at all and should either:

• Be moved to an excluded directory (if internal/development docs), OR
• Have frontmatter added with nav_exclude: true (if they should exist but not show in nav)

1. docs/AIRFLOW-COMPLETE-VISION.md
2. docs/AI_ASSISTANT_VERSIONING_STRATEGY.md (already has nav_exclude: true on line 3, but missing proper YAML block)
3. docs/AI_ECOSYSTEM_DEMO.md
4. docs/AI_ECOSYSTEM_ROADMAP.md

Files with Missing title Field (7 files)

These files have frontmatter but are missing the required title field:

1. docs/AI-MODEL-CONFIGURATION.md
2. docs/GETTING_STARTED.md
3. docs/MCP-DEVELOPER-GUIDE.md
4. docs/RAG-TOOL-GUIDE.md
5. docs/RAG-TOOL-QUICK-REFERENCE.md
6. docs/README.md
7. docs/SSH-TUNNELING-GUIDE.md

Also missing nav_order (recommended but not required).

Recommended Frontmatter Template

For files that should be published (visible in navigation):

---
title: "Getting Started with Qubinode Navigator"
nav_order: 1
description: "Quick start guide for deploying Qubinode Navigator"
---

For files that exist but should NOT appear in navigation:

---
title: "Internal Document Title"
nav_exclude: true
---

Example Fix

File: docs/GETTING_STARTED.md

+ ---
+ title: "Getting Started"
+ nav_order: 1
+ description: "Quick start guide for deploying the full stack"
+ ---
+
# Getting Started
...
````

## Priority Order

1. **High priority** (user-facing entry points):
   - `GETTING_STARTED.md` - should have full frontmatter
   - `README.md` - should have full frontmatter
   - `SSH-TUNNELING-GUIDE.md` - should have full frontmatter

2. **Medium priority** (specialized guides):
   - `MCP-DEVELOPER-GUIDE.md`
   - `RAG-TOOL-GUIDE.md`
   - `RAG-TOOL-QUICK-REFERENCE.md`
   - `AI-MODEL-CONFIGURATION.md`

3. **Low priority** (exclude from nav):
   - `AIRFLOW-COMPLETE-VISION.md` - add `nav_exclude: true`
   - `AI_ASSISTANT_VERSIONING_STRATEGY.md` - fix YAML block
   - `AI_ECOSYSTEM_DEMO.md` - add `nav_exclude: true`
   - `AI_ECOSYSTEM_ROADMAP.md` - add `nav_exclude: true`

## Root Cause

The root-level `docs/` directory has accumulated 12 markdown files without consistent frontmatter standards. Consider:

1. **Documenting frontmatter requirements** in a `CONTRIBUTING.md` guide
2. **Moving internal/development docs** to `docs/development/` or `docs/internal/`
3. **Using `nav_exclude: true`** for aspirational/incomplete docs

## Related Recommendation

Consider reorganizing the docs structure to reduce clutter:

````
docs/
├── index.markdown          # Site landing page
├── getting-started.md      # Renamed from GETTING_STARTED.md
├── explanation/            # ✅ Well organized
├── guides/                 # ✅ Well organized
├── how-to/                 # ✅ Well organized
├── reference/              # ✅ Well organized
├── tutorials/              # ✅ Well organized
├── fixes/                  # ✅ Well organized
└── internal/               # New: for VISION/ROADMAP docs

Verification

After adding frontmatter:

cd docs
# Check all .md files have frontmatter
for file in *.md; do
    if ! head -1 "$file" | grep -q "^---$"; then
        echo "Missing frontmatter: $file"
    fi
done

---

Detected by: Blog Auditor workflow (2026-02-25)
Impact: Low-Medium - Affects navigation rendering and site organization
Audit Phases: Phase 2 - Frontmatter Compliance

Generated by Blog Auditor - GitHub Pages Site Quality

[github-actions]

Re-audit Update (2026-03-04)

⚠️ Status: Issue persists - no changes since 2026-02-25

docs/README.md still missing:

• title field
• nav_order field

All other 31 published files have proper frontmatter with correct title, parent, nav_order, and has_children values.

Recommended fix:

---
title: Documentation Overview
nav_order: 2
description: Qubinode Navigator documentation landing page
---

Generated by Blog Auditor - GitHub Pages Site Quality