Create a Stylish documentation site effortlessly with Nextra

Nextra is a framework built on Next.js that allows you to create content-focused websites. It contains all of the amazing features of Next.js, plus the ability to produce Markdown-based text easily. It is designed specifically for documentation websites. It contains almost all the features that are needed to create a documentation site such as a search bar, table of contents, navigation bar, a nice sidebar and many more built-in features.

To utilize Nextra to establish a documentation site, you can follow the broad steps below, but we will have an in-depth look at how you can use Nextra in the "Step-by-Step Guide" section.

To create a documentation site we can use either the nextra default template directly or we can create a new template using the nextra default theme.

Create from Template

You can begin by developing your own Nextra documentation site and deploying it to Vercel by following the instructions. Vercel will fork the Nextra Docs template and launch the site for you. Once completed, all commits in the repository will be immediately deployed.

Fork the Template

You can also manually fork the template repository.

Create a New Project

• First, create a next.js app by running npx create-next-app in the terminal. Select the following options at the time of installing a next.js app:

• Now, install nextra and nextra-theme-docs by using the following codes

npm install nextra
npm install nextra-theme-docs

• Now it's time to config the nextra. Go to, next.config.js file and replace the codes with the following codes.

const withNextra = require("nextra")({
  theme: "nextra-theme-docs",
  themeConfig: "./theme.config.jsx",
});
module.exports = withNextra();

You may need to rename the next.config.mjs to next.config.js. Feel Free to do that.

• Now, create a theme.config.jsx file in your project’s root directory. This file will be used to configure the Nextra Docs theme. Now add the following codes:

export default {
  logo: <span>My Nextra Documentation</span>,
  project: {
    link: "https://github.com/shuding/nextra",
  },
  // ... other theme options
};

• Lastly, rename the pages/index.js file to pages/index.mdx file and remove all the codes inside it. Then, the following codes for testing:

# Welcome to Nextra
Hello, world!

In this stage, you should also rename pages/_app.js file to pages/_app.mdx file.

Now run the server by using npm run dev. Your site should open on localhost:3000. You can visualise your first documentation site there. But the process is not over yet. Let’s discuss how we can customize the pages and theme.

Page Configuration

The co-located _meta.json files in Nextra allow you to configure the site and page structure. There are several additional customization options available for the theme.

Pages

• All the .mdx files inside the pages folder will be listed as site sidebar items. By default, the page's title and order in the sidebar are arranged as the file name. But you can easily override it using  meta.json. Create a  meta.json file inside the pages folder. Suppose you have the following file structure:

📁Pages
   🗎 _meta.json
   🗎 contact.mdx
   🗎 blog.mdx
   🗎 index.mdx

Your configured _meta.json file will be like this:

// pages/_meta.json
{
  "index": "My Homepage",
  "contact": "Contact Us",
  "Blog": "Blog"
}

Folders

• You can configure Folders also. The process is the same as the Pages. For example:

📁Pages
   🗎 _meta.json
   🗎 contact.mdx
   🗎 about.mdx
   🗎 index.mdx
   📁 blogs
      🗎 _meta.json
      🗎 blog1.mdx
      🗎 blog2.mdx

The top-level _meta.json file contains the meta information for the top-level pages and directories. configured the file like this:

 // pages/_meta.json
{
  "index": "My Homepage",
  "contact": "Contact Us",
  "about": "About Us"
}

Furthermore, the nested _meta.json file holds the meta information for pages in the same folder:

// pages/blogs/_meta.json
{
  "blog1": "Blog 1",
  "blog2": "Blog 2",
}

But what should you do if you want to add data to the folder page? In our case for the blogs folder. We can add a .mdx file with the same folder name and in the same directory as the folder. So, you have to add the blogs.mdx file in the pages folder.

📁Pages
    🗎 _meta.json
    🗎 contact.mdx
    🗎 about.mdx
    🗎 blogs.mdx
    🗎 index.mdx
    📁 blogs
       🗎 _meta.json
       🗎 blog1.mdx
       🗎 blog2.mdx

Nextra recognizes that the blog's key in _meta.json refers to a folder with an index page. If you click on that folder in the sidebar, it will open it and display the blogs.mdx page at once.

Advance Page Setting

We can do some advanced settings also. We can configure the navbar, theme components, layouts and so on. Moreover,  We can also configure the style of breadcrumbs, sidebar, table of contents, pagination, and footer. Follow the link for more info about advanced page settings.

Theme Settings

The theme is configured with the theme.config.jsx file. We can configure the theme for things such as the logo, menus, searches, etc. All the theme items will be exported as an object in the theme.config.jsx file. Then, they should be configured. There are many scopes to configure the theme. An example of configuring the logo of the theme and project link  is given below:

//theme.config.json
export default {
  logo: (
    <>
      <svg
        width="24"
        height="24"
        viewBox="0 0 24 24"
      >
        <path
          fill="currentColor"
          d="M14.683 14.828a4.055 4.055 0 0 1-1.272.858a4.002 4.002 0 0 1-4.875-1.45l-1.658 1.119a6.063 6.063 0 0 0 1.621 1.62a5.963 5.963 0 0 0 2.148.903a6.035 6.035 0 0 0 3.542-.35a6.048 6.048 0 0 0 1.907-1.284c.272-.271.52-.571.734-.889l-1.658-1.119a4.147 4.147 0 0 1-.489.592z M12 2C6.486 2 2 6.486 2 12s4.486 10 10 10s10-4.486 10-10S17.514 2 12 2zm0 2c2.953 0 5.531 1.613 6.918 4H5.082C6.469 5.613 9.047 4 12 4zm0 16c-4.411 0-8-3.589-8-8c0-.691.098-1.359.264-2H5v1a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2h2a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2v-1h.736c.166.641.264 1.309.264 2c0 4.411-3.589 8-8 8z"
        />     
 </svg>
      <span style={{marginLeft: ".4em", fontWeight: 800}}> My Cool Project </span>
    </>
  ),
  project: {
    link: "https://github.com/shuding/nextra",
  },
  // ... other theme options
};

To learn more about theme configuration options, you should go to the nextra site.

Final thoughts

Nextra is an outstanding example of innovation whether you're developing a user manual, developer API reference, or personal documentation site to save your valuable time. It simplifies the documentation process and turns it into an art form by combining MDX, Tailwind CSS, and Next.js with ease. Interacting with audiences and empowering people has never been easier or more satisfying than with Nextra.

Want to Revolutionize your documentation site with Nextra? Elevate your project today with Staticmania!