Build a Doc Site With Next.js Using Nextra
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.
Sign up forfree
Forgot your password?
Create an account
*Required: 8 chars, 1 capital letter, 1 number
By continuing, you agree to thePrivacy PolicyandTerms of Use.You also agree to receive our newsletters, you can opt-out any time.
Requirements for Building a Doc Site With Nextra
Start by installing Node.js if you haven’t done so already. Thelatest Node.js versioncomes with npm, the node package manager, which you’ll need to install dependencies for this project.
Besides Node.js, you’ll need to installGit. 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’re able to use anextra docs templateto 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:
This command will scaffold an application inside the current directory. Next, run the following command to install the dependencies:
Once installation completes, start the application. Do so by running the following command on your terminal:
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 namedIntroductionandAnother Page. Below these page links, you’ll find a page named Satori, nested inside theAdvanced (A Folder)directory. Finally, in the navigation area, you’ll find links to theAboutandContactpages.
To understand how these pages work, you’ll need to first understandhow Next.js renders pages.
Understanding the Directory Structure
Since Nextra uses the Next.js framework, it renders each file in thepages/folder as a separate page.
Inside thepagesdirectory, you’ll find four template files:about.mdx,advanced.mdx,another.mdx, andindex.mdx. Each of these files corresponds to a page on the website; for example,index.mdxcorresponds to the home page. The URLlocalhost:3000/aboutcorresponds toabout.mdx, and so on.
Insidepages, there’s also a folder namedadvanced, housing a single file namedsatori.mdx. The URL for this file will belocalhost:3000/advanced/satori.
Notice how each of these files ends with a.mdxextension.
What Is MDX?
If you haveexperience 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 cancreate CSS modulesto 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 theindex.mdxfile and replace the content with this:
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 thepages/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 namedinstallation.mdxin your code editor and paste the following Markdown code into it:
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 ofinstallation.mdxrenders 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 theOrganize Filessection ofNextra’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’re able to see an example of how you can embed components in Markdown in theanother.mdxfile:
This Markdown file contains a definition for the Counter component. After that, it imports the Counters component from thecomponentsdirectory.
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, it’s possible to create really robust documentation sites.
Markdown is the best way to write formatted content on the web. And Markdown is super simple! Here’s what you need to know.
Windows is great, but adding this makes it unstoppable.
This small feature makes a massive difference.
Turn these settings on, and your iPhone will be so much better than before.
Lose your laptop without this feature, and you’ll wish you had turned it on.
Flagship price, mid-range phone.
