Deep Nesting Example

This document demonstrates how EmberDocs handles deeply nested file structures and generates proper breadcrumb navigation.

Why Deep Nesting?

Deep nesting of documentation can be useful for:

1. Large projects - Organizing dozens of guides into logical hierarchies
2. Multi-product sites - Separating documentation for different products
3. Language-specific docs - Creating separate trees for different programming languages
4. Version branches - Managing multiple documentation versions

Navigation Breadcrumbs

This document is located at: docs/examples/deep/nesting/many/levels/deep-doc.md

The breadcrumb trail should display:

• Docs
• Examples
• Deep
• Nesting
• Many
• Levels
• Deep Nesting Example (current)

File Path Structure

Your documentation can use any nesting depth:

docs/
├── index.md
├── getting-started/
│   └── introduction.md
├── guides/
│   ├── basic/
│   │   └── hello-world.md
│   ├── intermediate/
│   │   └── state-management.md
│   └── advanced/
│       └── performance.md
└── deep/
    └── nesting/
        └── many/
            └── levels/
                └── deep-doc.md

URL Generation

EmberDocs automatically generates URLs based on file paths:

The slug in the frontmatter must match the file path structure.

Best Practices for Deep Nesting

1. Keep Navigation Discoverable

Don't nest more than 4-5 levels deep, as it becomes hard to navigate:

Good: docs/guides/api/authentication.md
Less Good: docs/v2/section/subsection/category/topic/specific/topic.md

2. Use Meaningful Directory Names

// Good
docs/advanced/performance-optimization/memory-management.md

// Bad
docs/a/b/c/topic.md

3. Maintain Consistent Slug Naming

Make slugs match the directory path for clarity:

---
slug: "deep/nesting/many/levels/deep-doc"  # Matches file location
---

4. Consider User Navigation

Deep nesting works, but users need clear breadcrumbs and navigation:

## See Also

- [Back to Guides](/docs/guides)
- [Advanced Features](/docs/guides/advanced-features)
- [Troubleshooting](/docs/guides/troubleshooting)

Technical Implementation

Static Route Generation

Next.js generates static pages from all documents:

export async function generateStaticParams() {
  const nav = generateNavigation('./docs');
  return Object.keys(nav.nodeMap)
    .filter(id => id.endsWith('.md'))
    .map(id => ({
      slug: id.replace('.md', '').split('/'),
    }));
}

Dynamic Route Segment

The catch-all route handles any nesting depth:

// src/app/docs/[...slug]/page.tsx
export default async function DocPage({
  params
}: {
  params: { slug: string[] }
}) {
  const slug = params.slug.join('/');
  // Load docs/examples/[slug].md
}

Search and Indexing

All documents, regardless of nesting depth, are indexed for full-text search:

const index = await buildSearchIndex('./docs');
// Recursively finds all .md files in any subdirectory

Search results include full path information:

{
  title: "Deep Nesting Example",
  path: "/docs/deep/nesting/many/levels/deep-doc",
  excerpt: "This document demonstrates...",
  score: 0.95
}

Sitemap Generation

For SEO, include all nested documents in sitemap:

<url>
  <loc>https://docs.example.com/docs/deep/nesting/many/levels/deep-doc</loc>
  <lastmod>2025-01-15</lastmod>
  <priority>0.8</priority>
</url>

Performance Considerations

Build Time

Deep nesting can increase build time slightly:

• Each additional level adds minimal overhead
• Navigation tree construction is O(n) where n = number of files
• Typical: 1000 documents = <1 second build time

Runtime Performance

Deeply nested pages load at same speed:

• Page content served from static HTML
• Navigation data optimized via JSON
• Search index pre-built and cached

Client Bundle Size

Nesting depth doesn't affect bundle size since:

• Only one page loaded at a time
• Navigation data lazy-loaded
• Search index loaded on-demand

Testing Deep Routes

Verify deep nesting works with:

# Development
npm run dev
# Visit: http://localhost:3000/docs/deep/nesting/many/levels/deep-doc

# Production build
npm run build
# Check: public/docs/deep/nesting/many/levels/deep-doc.html

Troubleshooting

Breadcrumbs not showing

Ensure slug matches path structure:

# ✓ Correct
---
slug: "deep/nesting/many/levels/deep-doc"
---

# ✗ Wrong
---
slug: "deep-doc"
---

Route not found

Check file location matches expected path:

File: docs/examples/deep/nesting/many/levels/deep-doc.md
Route: /docs/deep/nesting/many/levels/deep-doc

Navigation tree incomplete

Ensure all files have valid frontmatter:

---
title: "Document Title"
slug: "path/to/document"
published: true
---

Summary

EmberDocs supports arbitrary nesting depth for documentation organization while maintaining:

• ✅ Clear breadcrumb navigation
• ✅ Full-text search across all levels
• ✅ Static generation for performance
• ✅ SEO-friendly URLs
• ✅ Consistent routing

Use deep nesting thoughtfully to keep documentation organized and user-friendly.

Related Documentation:

• Basic Usage
• Navigation
• Advanced Features