Build a documentation site with Next.js using Nextra

If you’re familiar with Next.js, you can easily use it to develop documentation sites. The Nextra framework takes care of the nitty-gritty for you. Just add Markdown or HTML content and YAML or JSON data.

Follow these steps to build a documentation site using Nextra, a Next.js-based static site generator. Learn how to install and set up the required dependencies, add new documents and pages, create Markdown, and include React components.

Install Node.js first, if you haven’t already. The latest he Node.js version comes with npm, the node package manager that should install the dependencies for this project.

Besides Node.js, you’ll need to install Git. Git is required to deploy your site to GitHub Pages, Netlify, or another hosting provider. You’ll also need an advanced code editor such as VS Code.

You can bootstrap your documentation site using the nextra docs template. Start a command prompt and navigate to the directory where you want to set up your project. Then bootstrap the documentation site by running the following command:

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

This command scaffolds the application in the current directory. Then run the following command to install the dependencies:

 cd nextra-docs-template
npm install
 

After the installation is complete, launch the application. To do this, run the following command in your terminal:

 npm run dev
 

This command will start the development server at localhost:3000. Follow the link on your device to view the documentation site. The home page looks like this:

If you look to the left of the page, you will find pages with the following names: prologue and another pageUnder these page links, there is a page named Satori, Advanced (A folder) directory. Finally, the navigation area contains almost and contact page.

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

About the directory structure

Nextra uses the Next.js framework, so each file is page/ View folders as separate pages.

internal page There are four template files in the directory: about.mdx, advanced .mdx, another .mdxand index.mdxEach of these files corresponds to a page on your website. for example, index.mdx It corresponds to the homepage. URLs localhost: 3000/approx corresponds to about.mdxand so on.

inside pageThere is also a folder named Altitudecontaining a single file named Satori.mdxThe URL for this file looks like this: localhost:3000/advanced/satori.

Each of these files ends with .mdx expansion.

What is MDX?

If you have React experience, you should know JSX. This is an HTML-like language that can be used to describe her UI for React components.

MDX loads, parses, and renders JSX in Markdown documents. Thanks to MDX, you can create React components and import them into your Markdown documents as needed. MDX files end with the .mdx extension and can contain 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 your components. This allows you to organize your components for better readability and maintainability.

How to edit an existing page on a documentation site

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

for example, index.mdx Replace the contents of the file with:

 # 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 1 headline, a level 2 headline and two social media links.

Save the file and visit the home page of the documentation site. The page looks like this:

At the bottom of the page you can also see when the document was last updated.

add a new page

Before adding a new page, make sure that the page is page/ in a directory or a folder within it. Use folders to categorize pages and create hierarchies.

In this case, create a standalone page at the top level.open a file named install.mdx In the code editor, paste the following Markdown code.

 # 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 your browser. There is an installation label on the side menu. Click the link to install.mdx Render on page:

You can change labels and perform other configurations in the _meta.json file in the pages directory. For more information, organize files A section of the Nextra documentation.

Using React components

MDX files can contain JSX, the language used by React. You can create components inside the components folder and import them into any document on your site.

An example of how to embed a component in Markdown is 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 the definition of the Counter component.Then add the Counters component to component directory.

If you use the same component throughout your documentation site, we recommend creating it as a standalone component and importing it when needed.

Markdown details

To create content for your documentation site, you need to know how to use Markdown. Luckily, Markdown syntax is pretty easy to understand. Combining your knowledge of Markdown with React allows you to create a very robust documentation site.