feat: Add full support for nested navigation in MkDocs configuration

[agpenton]

🚀 Feature: Full Support for Nested Navigation in MkDocs

📋 Summary

This PR implements complete support for nested navigation structures in the MkDocs nav section, allowing documentation to maintain its hierarchical structure when published to Confluence.

Closes: Addresses the limitation previously documented in README.md about flattening nested navigation.

---

🎯 Motivation

Previously, the action flattened all pages to a single level regardless of their nesting in the MkDocs configuration. This meant that hierarchical documentation structures were lost when publishing to Confluence, making it difficult to organize complex documentation.

Before:

Confluence:
├── Home (README)
├── Page 1
├── Page 2
├── Page 3
└── Page 4  (all at same level)

After:

Confluence:
├── Home (README)
├── Page 1
└── Guides
    ├── Getting Started
    └── Advanced
        ├── Configuration
        └── Deployment  (proper hierarchy maintained!)

---

✨ What's New

1. Hierarchical Page Structure

Pages now maintain their parent-child relationships as defined in mkdocs.yml:

nav:
  - Home: index.md                           # Root level (parent: Home page)
  - Getting Started: getting-started.md      # Root level
  - User Guides:                             # Section header
    - Installation: guides/install.md        # Child of "User Guides"
    - Configuration: guides/config.md        # Child of "User Guides"
    - Advanced Topics:                       # Nested section
      - Custom Themes: guides/adv/themes.md  # Child of "Advanced Topics"
      - Plugins: guides/adv/plugins.md       # Child of "Advanced Topics"
  - API Reference: api.md                    # Root level

2. Arbitrary Nesting Depth

Supports unlimited nesting levels - organize your docs however makes sense for your project!

3. Smart Parent Assignment

• The first page in a section becomes the parent page for that section's children
• Root-level pages are children of the home page (created from README.md or site_name)
• Preserves the logical document hierarchy in Confluence

---

🔧 Technical Implementation

Core Changes

1. Context Module (lib/context.js)

• Enhanced traverse() function to track parent-child relationships via parentPath parameter
• Recursively processes nested sections while maintaining hierarchy information

2. LocalPage Model (lib/models/local-page.js)

• Added parentPath property to store the section title that contains the page
• Properly serialized in JSON for test fixtures

3. Confluence Syncer (lib/confluence-syncer.js)

• Completely rewrote syncPages() to handle hierarchical structures
• Level-by-level processing: Ensures parent pages exist before their children
• Intelligent grouping: Groups pages by their parent section
• ID tracking: Maintains a map of synced page IDs for proper parent reference
• Orphan cleanup: Removes pages that no longer exist in the nav structure

4. Documentation (README.md)

• Updated Features section to highlight nesting support
• Removed limitation notice about flattening

---

📊 How It Works

MkDocs Nav Structure:
├── Home
├── Guides (section)
│   ├── Page A → parentPath: "Guides"
│   └── Advanced (nested section)
│       └── Page B → parentPath: "Advanced"
└── Page C → parentPath: null

Processing Flow:
1. Sync root level pages (parentPath: null)
   - Creates "Home" and "Page C" under home page
   
2. For each page that has children (is a section):
   - Sync its children using the page's Confluence ID as parent
   - "Page A" created under "Guides"
   
3. Recursively process nested sections:
   - "Page B" created under "Advanced"

---

✅ Testing

All Existing Tests Pass

• 148 tests passing
• 99.63% code coverage maintained
• No regressions in existing functionality

New Test Fixtures

Added comprehensive test fixture for nested structures:

test/fixtures/samples/nested/
├── mkdocs.yml (3-level nesting example)
├── README.md
└── docs/
    ├── index.md
    ├── guides/
    │   ├── getting-started.md
    │   └── advanced/
    │       ├── configuration.md
    │       └── deployment.md
    └── api.md

Test Evidence

$ npm test
148 passing (704ms)

File                  | % Stmts | % Branch | % Funcs | % Lines |
----------------------|---------|----------|---------|---------|
All files             |   99.63 |    98.01 |     100 |   99.63 |

---

🔄 Backward Compatibility

✅ Fully backward compatible!

Existing configurations with flat navigation continue to work exactly as before:

nav:
  - Page 1: page1.md
  - Page 2: page2.md
  - Page 3: page3.md

All pages are created at root level (under home page) with parentPath: null.

---

📖 Usage Examples

Simple Nesting

site_name: My Documentation
repo_url: https://github.com/user/repo

nav:
  - Home: index.md
  - Tutorials:
    - Getting Started: tutorials/start.md
    - Advanced: tutorials/advanced.md
  - API: api.md

Result in Confluence:

• My Documentation (home)
  • Home
  • Getting Started (child of Home)
  • Advanced (child of Home)
  • API

Deep Nesting

nav:
  - Overview: index.md
  - User Guide:
    - Installation:
      - Windows: guide/install/windows.md
      - Linux: guide/install/linux.md
    - Configuration:
      - Basic: guide/config/basic.md
      - Advanced: guide/config/advanced.md

Result in Confluence:

• Overview
• Windows (child of Overview)
  • Linux (child of Windows)
    • Basic (child of Linux)
      • Advanced (child of Basic)

---

🎨 Benefits

1. 📁 Better Organization: Documentation structure matches your repository organization
2. 🔍 Improved Navigation: Users can navigate hierarchical docs more easily in Confluence
3. 🎯 Logical Grouping: Related pages are grouped under common parent pages
4. ♻️ No Migration Needed: Existing flat structures continue to work without changes
5. ⚡ Performance: Efficient level-by-level syncing ensures minimal API calls

---

📝 Migration Guide

No migration required! This is a pure enhancement.

If you want to start using nested navigation:

1. Update your mkdocs.yml to use nested structure
2. Re-run the action
3. Pages will be reorganized in Confluence to match the new hierarchy

---

🔍 Code Quality

• ✅ All tests passing (148/148)
• ✅ ESLint validation passing
• ✅ Code coverage maintained (99.63%)
• ✅ Distribution files rebuilt
• ✅ Pre-commit hooks validated
• ✅ No breaking changes

---

📚 Related Documentation

• MkDocs Navigation Documentation
• Confluence Page Hierarchy

---

🙏 Acknowledgments

This implementation follows best practices for:

• Recursive tree traversal
• Level-order processing for hierarchical structures
• Maintaining referential integrity in parent-child relationships

---

📋 Checklist

• Code follows project style guidelines
• All tests pass
• Test coverage maintained
• Documentation updated (README.md)
• Backward compatibility ensured
• Distribution files built
• No lint errors
• Commit message follows conventional commits
• Branch name is descriptive