If you're familiar with Next.js, you can use it to develop a documentation site with ease. The Nextra framework takes care of the nitty-gritty for you; all you have to do is add Markdown or HTML content and YAML or JSON data.

Walk through these steps to build a documentation site using Nextra, a Next.js-based static site generator. You’ll install and set up the necessary dependencies, then learn how to add new docs and pages, write Markdown, and include React components.

Requirements for Building a Doc Site With Nextra

Start by installing Node.js if you haven't done so already. The latest Node.js version comes with npm, the node package manager, which you'll need to install dependencies for this project.

Besides Node.js, you'll need to install Git. You need Git to deploy the site to GitHub pages, Netlify, or another hosting provider. You'll also need an advanced code editor, such as VS Code.

Installing Nextra

You can use a nextra docs template to bootstrap a documentation site. Launch a command prompt and navigate to the directory in which you want to set up your project. Then run the following command to bootstrap the documentation site:

        git clone https://github.com/shuding/nextra-docs-template

    

This command will scaffold an application inside the current directory. Next, run the following command to install the dependencies:

        cd nextra-docs-template
npm install

    

Once installation completes, start the application. Do so by running the following command on your terminal:

        npm run dev

    

This command starts a development server at localhost:3000. Follow the link on your terminal to view the documentation site. The homepage should look like this:

If you look on the left side of the page, you'll find the pages named Introduction and Another Page. Below these page links, you'll find a page named Satori, nested inside the Advanced (A Folder) directory. Finally, in the navigation area, you'll find links to the About and Contact pages.

To understand how these pages work, you'll need to first understand how Next.js renders pages.

Understanding the Directory Structure

Since Nextra uses the Next.js framework, it renders each file in the pages/ folder as a separate page.

Inside the pages directory, you'll find four template files: about.mdx, advanced.mdx, another.mdx, and index.mdx. Each of these files corresponds to a page on the website; for example, index.mdx corresponds to the home page. The URL localhost:3000/about corresponds to about.mdx, and so on.

Inside pages, there’s also a folder named advanced, housing a single file named satori.mdx. The URL for this file will be localhost:3000/advanced/satori.

Notice how each of these files ends with a .mdx extension.

What Is MDX?

If you have experience with React, you should know about JSX. This is an HTML-like language that you can use to describe the UI of React components.

MDX loads, parses, and renders JSX in a Markdown document. Thanks to MDX, you can write React components and import them into your Markdown documents when needed. MDX files end with the .mdx extension and can include both Markdown and JSX.

MDX lets you combine your knowledge of Markdown with React to create reusable components. You can create CSS modules to style the components. This helps to you organize your components to improve readability and maintainability.

How to Edit Existing Pages in the Documentation Site

To edit an existing page, simply open the corresponding file and make changes to it. Supported languages are Markdown and JSX.

For example, open the index.mdx file and replace the content with this:

        # Welcome To My Documentation
I'm happy to see you here. Thanks

## My Socials
Follow me on [Twitter](https://twitter.com/kingchuuks) and [LinkedIn](https://linkedin.com/in/kingchuks)

    

This example uses Markdown to format the content. It contains a level-one heading, a level-two heading, and two social media links.

Save the file and visit the homepage of your documentation site. The page should now look like this:

At the bottom of the page, you can also find the document's last updated date.

Adding a New Page

Before adding a new page, you need to first decide if the page will be in the pages/ directory or inside a folder within it. Use folders if you want to categorize your pages or develop a hierarchy.

In this case, create a standalone page at the top level. Open a file named installation.mdx in your code editor and paste the following Markdown code into it:

        # Installation Guide
Follow this guide to install my package in your project

## 1. Install Node.js

To install Node.js, visit the
[Node.js documentation site](https://nodejs.org/en/download)

    

Save the file and check the browser. You'll find the Installation label in the side menu. When you click on the link, the content of installation.mdx renders on the page:

You can change the label and carry out other configurations in the _meta.json file within the pages directory. To learn more about this, refer to the Organize Files section of Nextra's documentation.

Using React Components

MDX files can include JSX, which is the language that React uses. You can create a component inside the components folder and import it in any of the documents on your site.

You can see an example of how you can embed components in Markdown in the another.mdx file:

        ## Component
import {useState} from 'react'
import styles from '../components/counters.module.css'

export const Counter = () => { 
  const [count, setCount] = useState(0); 

  return( 
    <div> 
      <button onClick={() => setCount(count+1)} className={styles.counter}> 
        Clicked {count} times 
      </button> 
    </div> 
  )
}

<Counter />

## External Components
import Counters from '../components/counters'

<Counters />

    

This Markdown file contains a definition for the Counter component. After that, it imports the Counters component from the components directory.

If you’re going to use the same component across your documentation site, it's best to create it as a standalone component and import it when you need it.

Learn More About Markdown

To create content for your documentation site, you need to know how to use Markdown. The good news is that the Markdown syntax is quite easy to pick up. When you combine your knowledge of Markdown with React, you can create really robust documentation sites.