Nuxt Content Docs

Overview

A good documentation system is a key to a successful product. This is way we've decided to use ready built tools to build our documentation system.

We've decided to use Nuxt Content to build our documentation system.

With the power of Markdown, we can write our documentation in a way that is easy to read and write. Using frontmatter, we can add metadata to our documentation to make it more powerful.

Key Features

1. Folder-Based Categories

Categories are automatically determined by your folder structure. You can determine 3 levels of differentiations

2. Root level

Simply create a new markdown file (*.md) inside the content/docs folder, and it will automatically reflect in your navigation and documentation.

3. Category Level

Create a subfolder will create a category, you can add a index.md file to the folder to add a category name and description and order.

Example of an index.md file:

---
title: Webhooks
description: Real-time notifications via webhooks
name: Getting Started with Webhooks  # Category display name
categoryDescription: Learn how to implement and manage webhooks for real-time notifications
order: 1  # Category ordering
---

4. Accordion Level

At the third level, everything in a folder will result in an accordion. You can add a index.md file to the folder to add a category name and description and order.

Hierarchical Structure

First Level: Root files (like introduction.md) appear as uncategorized items
Second Level: Folders become categories with accordion-style navigation
Third Level: Subfolders within categories can also have their own index.md for accordion naming

Order System

The order field now works at multiple levels:

Category Level: Set in folder's index.md to order categories
File Level: Set in individual files to order items within categories
Accordion Level: Set in subfolder's index.md to order accordions

File Structure Example

content/docs/
├── introduction.md                    # Uncategorized (root level)
├── getting-started.md                 # Uncategorized (root level)
├── webhooks/                          # Category folder
│   ├── index.md                      # Category config (name: "Getting Started with Webhooks")
│   ├── setup.md                      # File in category
│   └── events.md                     # File in category
├── api/                              # Category folder
│   ├── index.md                      # Category config (name: "API Documentation")
│   ├── authentication.md             # File in category
│   ├── users.md                      # File in category
│   └── endpoints/                    # Accordion subfolder
│       ├── index.md                  # Accordion config (name: "Core Endpoints")
│       └── users-crud.md             # File in accordion
└── granular-permissions/             # Category folder
    ├── index.md                      # Category config (name: "Permission Management")
    ├── global-permissions.md         # File in category
    └── organization-level-permissions.md  # File in category

Schema Changes

Inside the content.config.ts file, you get the following schema:

schema: z.object({
  title: z.string(), // The title of the file shown in the navigation and the page title
  description: z.string(),  // The description of the file
  name: z.string().optional(),              // Category/accordion display name
  categoryDescription: z.string().optional(), // Category description, shown in the category header
  order: z.number().optional(),             // Universal ordering
})

Benefits

Intuitive Organization: Folder structure directly maps to navigation
Flexible Naming: Category names can be different from folder names
Rich Descriptions: Categories can have descriptive text
Hierarchical Support: Supports nested accordions for complex documentation
Consistent Ordering: Universal order field works at all levels
Maintainable: Easier to reorganize content by moving folders