Documentation Website

## 1. Learning Objectives By the end of this project, you will be able to design a documentation website with nested routes, side navigation, content collections, search metadata, versioning basics, and static deployment behavior. Difficulty: Intermediate. ## 2. Prerequisites - File routing. - Layouts. - MDX or content loading. - SEO basics. ## 3. Overview A documentation website is a structured content product. It needs stable URLs, nested navigation, fast static pages, good search indexing, code examples, and clear versioning decisions. ## 4. Why This Topic Matters Docs are often the first product surface developers use. A well-built docs site reduces support load, improves adoption, and proves that your routing and content model can scale. ## 5. Real-World Analogy A docs site is a map with trails. The homepage shows the region, the sidebar shows nearby paths, and each page gives precise instructions for one stop. ## 6. Core Concepts | Concept | Role in Docs | |---|---| | Catch-all route | Renders nested docs paths. | | Section layout | Shared sidebar and table of contents. | | Content registry | Maps slugs to files, titles, and order. | | Metadata | Helps search engines and previews. | | Static generation | Makes docs fast and reliable. | ## 7. Syntax & API Reference

## 8. Visual Diagram

## 9. Live Example - Full Working Code

What just happened? A catch-all route renders every nested docs URL from a content registry while still allowing each page to have its own metadata. ## 10. Interactive Playground Try this: - Add section ordering to the content registry. - Add a docs sidebar layout. - Add previous and next links. - Generate a search index during build. ## 11. Common Mistakes | Mistake | Why It Happens | Correct Approach | |---|---|---| | Unstable doc URLs | File names are changed freely. | Treat slugs as public contracts. | | Sidebar hardcoded in many files | Navigation starts small. | Generate navigation from metadata. | | No 404 for missing docs | Content lookup fails silently. | Use `notFound()`. | | Client-rendering all docs | Search/filter needs JS. | Render content server-side and isolate search. | ## 12. Best Practices - Keep docs pages static when possible. - Use stable slugs and redirects for moved pages. - Generate sidebar navigation from one source of truth. - Add page metadata, sitemap entries, and Open Graph defaults. - Make search progressive: content first, JavaScript enhancement second. ## 13. Browser Compatibility | Feature | Browser Impact | Notes | |---|---|---| | Static docs pages | Excellent | Content loads without app-like delays. | | Search UI | JavaScript enhancement | Docs should remain browseable without it. | | Code blocks | HTML plus CSS | Avoid heavy client highlighters when possible. | ## 14. Interview Questions **Easy:** Why use a catch-all route for docs? Answer: It lets one route render many nested documentation paths. **Medium:** Why generate navigation from metadata? Answer: It avoids duplicated sidebar definitions and keeps ordering consistent with content. **Hard:** How would you support versioned documentation? Answer: Include the version in the route or content registry, generate params per version, preserve old URLs, and keep redirects for moved pages. ## 15. Debugging Exercise Bug report: "Search engines index duplicate docs pages with and without trailing slashes." Solution Choose a canonical URL format, emit canonical metadata, and redirect alternate paths so each document has one authoritative URL. ## 16. Practice Exercises - Easy: Add a docs catch-all route. - Medium: Generate sidebar navigation from docs metadata. - Hard: Add versioned docs with redirects for moved pages. ## 17. Scenario-Based Challenge Your docs need product guides, API references, changelog pages, and versioned URLs. How should the content model work? Walkthrough Create a registry with section, slug, title, description, order, version, and source path. Generate routes, navigation, metadata, sitemap entries, and search records from that registry. ## 18. Quick Quiz 1. What route handles nested docs paths? Answer: `app/docs/[...slug]`. 2. What should missing docs call? Answer: `notFound()`. 3. What should define sidebar ordering? Answer: Content metadata. 4. What makes docs fast? Answer: Static generation. 5. What should moved pages use? Answer: Redirects. ## 19. Summary & Key Takeaways - Documentation sites are structured content systems. - Catch-all routes work well for nested docs. - Static generation keeps docs fast and resilient. - Metadata and canonical URLs protect SEO quality. - A content registry keeps routes, navigation, search, and sitemaps aligned. ## 20. Cheat Sheet | Need | Pattern | |---|---| | Nested docs route | `app/docs/[...slug]` | | Build all pages | `generateStaticParams` | | Page SEO | `generateMetadata` | | Missing page | `notFound()` | | Sidebar | Generated from metadata | ## 21. Further Reading - Next.js Docs: Layouts and Pages. - Next.js Docs: Metadata and OG Images. - Next.js Docs: Static Generation. ## 22. Next Lesson Preview Chapter 9 is complete. Next, you will prepare for Next.js interview questions and review the full course.