Adding new Documentation

This guide walks you through the steps required to add new pages or topics to your Nextra documentation site. Whether you’re a maintainer or a contributor, following these steps will help you expand the documentation structure efficiently.

Prerequisites

1. Node.js and npm: Ensure that Node.js (>= v22.0.0) and npm are installed on your system.

2. Nextra Installed: Confirm that your site uses Nextra. If not, install it using:

   npmpnpmyarnbun

   npm i nextra nextra-theme-docs

3. Git Access: Make sure you have write access to the repository or the ability to fork and submit pull requests.

Adding a New Documentation Page

Locate the Documentation Directory

Nextra organizes pages in the pages directory at the root of your project. This directory mirrors the site’s URL structure. For instance:

pages/
├── index.md               // Home page
├── guide/
│ ├── installation.md      // /guide/installation
│ └── setup.md             // /guide/setup
└── api/
└── reference.md           // /api/reference

Create a Markdown React File

To add a new page:

1. Locate the appropriate subdirectory within the pages/folder. If the topic does’t fit an existing structure, create a new subdirectory with a meaningful name, e.g., pages/new-topic/.
2. Inside the directory, create a .mdx file with a descriptive filename, e.g., introduction.mdx.
3. Write your documentation using MDX, which combines Markdown and React for flexible content creation. Follow this structure for a consistent style:

# Introduction to New Topic
 
Welcome to the documentation for **New Topic**. This page provides a detailed overview of the topic, its purpose, and how it can be utilized effectively.
 
## What is New Topic?
 
Explain the core concept of the topic. Use clear and concise language. Include definitions, background information, and any relevant context.
 
For example:
 
> "New Topic" is a feature/module/tool designed to simplify workflows by providing XYZ capabilities.
 
## Key Features of New Topic
 
Highlight the main features, benefits, or applications:
 
- **Feature 1:** Brief description of the feature.
- **Feature 2:** Highlight its value.
- **Feature 3:** How it helps users.
 
## How to Use New Topic
 
Provide step-by-step guidance or examples on how to use the feature/module/tool:
 
### Example 1: Basic Usage
 
```javascript
// Example of how to implement or use the feature
import { NewTopic } from 'your-library';
 
const demo = NewTopic({ key: 'value' });
console.log(demo);
```

Content Writing Tips

• Use Clear Headings: Organize the document with clear and descriptive headings (e.g., #, ##, ###).
• Highlight Code: Use fenced code blocks (```) with appropriate syntax highlighting (javascript, bash, etc.).
• Add Visual Aids: When applicable, include diagrams, images, or tables.
• Reference Internal Links: Use relative paths to link other pages in the documentation (e.g., ../guide/setup).
• Maintain Consistency: Follow the project’s tone and style guide to ensure uniformity across the documentation.

Adding Page Sidebar Metadata

In Nextra, sidebar metadata helps organize your pages and topics in the navigation menu. This is managed using _meta.ts files within directories or directly via theme.config.ts (not recommended).

Adding Metadata to _meta.ts

To ensure your new page appears in the sidebar:

pages/
├── guide/
│ ├── \_meta.ts
│ ├── installation.mdx
│ └── setup.mdx

export default {
  installation: 'Installation Guide',
  setup: 'Setup Instructions',
  newtopic: 'New Topic Documentation',
};

export default {
  index: 'Home',
  guide: {
    'new-section': 'New Section Title',
  },
  api: 'API Reference',
};

Adding a New Topic (Parent Directory)

If your new topic doesn’t fit within existing sections, create a new parent directory to house it.

mkdir -p pages/tutorials

export default {
  'getting-started': 'Getting Started',
  'advanced-tutorials': 'Advanced Tutorials',
};

export default {
  index: 'Home',
  guide: {
    _meta: import('./guide/_meta'),
  },
  tutorials: {
    _meta: import('./tutorials/_meta'),
  },
  api: 'API Reference',
};

Testing Your Changes

After updating or adding new pages and metadata, test your changes locally to ensure they appear as expected.

npm run dev

npm run lint
npm run format

npm install --save-dev --save-exact prettier

pnpm add --save-dev --save-exact prettier

yarn add --dev --exact prettier

bun add --dev --exact prettier

npx prettier --version