Nextra 2.0: Create a Full-Featured Documentation Site in 5 Minutes

Rate this content
28 min
02 Dec, 2022

AI Generated Video Summary

Next.js and Nextra are powerful tools for generating full-featured documentation websites with ease. Nextra offers features like dark mode, full-text search, and React code integration. Next.js provides image optimization, SSG, SSR, and other powerful features. Nextra is highly customizable and supports localization, collaboration, and API integration. The future vision includes combining documentation and live views, adding social card generation and advanced search functionality.

1. Introduction to Next.js and Nextra

Short description:

Today I'm going to talk about a project called Next.js. It's a tool to generate full-featured documentation website in minutes. It's very easy to use. And it can generate very fancy or easy to use documentation site, and it powers many of our internal or open source projects as well. We love next.js. There are many people already familiar with next.js APIs, and it's super powerful. It's a solid foundation, and it's well maintained. We also have some new ideas to create docs, and we want to validate the ideas and iterate them, and try to build something incredible as a product. It can be just more than documentation. It can support more use cases like blog and portfolio websites as well. Nextra is a normal Next.js project where you can focus on your content, and Nextra handles the website architecture and all the compiler, bundler stuff.

Thank you, nice to be here. So next shot. Nice logo, right? Yeah.

Let me introduce myself first. So my name is Szu-Din, and I've been looking at, or working on open source projects for almost nine years. And I've spent four years at Versailles, and I've done both design and engineering work there. And currently I'm working on Next.js, and I created previously, I created libraries like SWR and Satori, and that's my Twitter handle if you want to contact me.

And today I'm going to talk about a project called Next.js. It's a tool to generate full-featured documentation website in minutes. It's very easy to use. And it can generate very fancy or easy to use documentation site, and it powers many of our internal or open source projects as well.

But why? Why are we creating a new project to generate documentation? So first, both Vercell and myself have too many projects to maintain, like every couple of months, we got a new project to work on. We got a new experiment or new open source stuff. And as an open source maintainer, my major time has been spent in maintaining documentation. And it's really important for our users and for the community. But every time we create an ad hoc doc site, and they are implemented differently by different people, so we need just one solution for ourselves. And there are already many solutions out there. Why are we creating a new? So first of all, we love next.js. There are many people already familiar with next.js APIs, and it's super powerful. It's a solid foundation, and it's well maintained. So we don't want to learn a new tool to generate our sites, because next.js can be good for documentation as well. Why not just use it? And then we also have some new ideas to create docs, and we want to validate the ideas and iterate them, and try to build something incredible as a product. And last, it can be just more than documentation. It can support more use cases like blog and portfolio websites as well.

So here's a quick look of Nextra. So it's just a normal Next.js project if you are already familiar with it. You have a pages folder, and instead of JavaScript files, you just have a list of markdown MDX files. And you can nest them in folders and name them, and they are just markdowns. And the good thing about Nextra is you can just focus on your content, and you don't need to care about the website architecture and all the compiler, the bundler stuff. Nextra handles it for you.

2. Features of the Project

Short description:

When you use this project, you can easily see your website structure mirrored in your file system. You don't need to configure anything, just create files and write your content. The project automatically generates a table of contents based on your files. It also offers features like dark mode, built-in full-text search, and fast navigation. You can even write React code inside your content. With Nexus integration, markdown links are automatically converted to Nexus links, providing link prefetching and instant page loads.

And the same project, when you got it running, you can see the website basically the same as your file system structure. And as you can see, your pages matches exactly as your website's sidebar. So you don't need to configure anything. You just create a new file and write your content. You can spend most of your time working on the content yourself. And you got a nice-looking website.

And there are more things than that, like the table of contents. It's generated automatically based on your file. And that's the first impression of the project. It's easy to set up because you just create files. And then you can focus on the content. And it's intuitive to manage routes because usually you need to create some complex configuration like specify those those pages and routes and folders and directories, and now you only need to maintain the filesystem, the folders.

And it looks pretty nice, but what else? So first of all, dark mode, why not, is something everyone loves. And this is something more powerful. It has a built-in full text search. You don't need to do anything. You just write your content, and you get a search out of the box because usually, you need to like configure some service and maintain a server and API and you do a bunch of stuff to get it running and then you have it automatically without writing anything. And it looks fast, right? It's not speed up. I can show you like directly. Is it fast? It's very fast. And you can jump to the position directly. Yeah, you get that for free basically. And since it's MDX, you can write React code inside your content.

And here is a heading two element, hello MDX, and you can just put a React component inside. In the v2 version of MDX, you can have markdowns inside your components, like that clicks. You can have both syntax there and it renders the style as well because previously you cannot them in every level. That's a nice thing about the v2 version and since it's Nexus powered because Nexus and extra, you get extra power from Nexus, like normal markdown links can be automatically converted to Nexus link. That means you have link prefetching out of the box and when you are hovering on a link, the target page gets prefetched. So when you click on it, it's instant. And if you are just writing markdown links, every click will result in a hard page load.

3. Next.js Features and Benefits

Short description:

With Next.js, markdown images are automatically turned into Next.js images, with built-in image optimization. This prevents layout shift and provides a blurred up placeholder during initial page load. Next.js also offers many other features, including SSG, SSR, and ISR for dynamic content, i18n support, CSS optimization, and the ability to mix JS routes with documentation. It even has features like preview mode, API routes, and middleware. Next.js is a powerful framework with a lot to offer.

You don't get SPA experience. And also markdown images. That's a hard thing. But with Next.js, it's turned into Next.js image automatically. And Next.js has the image optimization built in, which has two nice things. One is it prevents layout shift. So when you are loading the page, your content doesn't get pushed up or down, because the image doesn't get loaded initially. And then when it loads, your content will be moved. And that's a bad experience. Another thing is, it optimized the image.

And when you are initially loading the page, you see a blurred up placeholder there. And then the full content gets loaded later. Which is nice. And there's much more than this. Because Next.js is a framework with a lot of different features that some are powerful, some are very nice and small things.

So one major thing here is SSG, SSR and ISR. Because usually you don't write everything as static files. Sometimes you want the content to be a little bit dynamic. Say I have a page that shows how many stars my project has on GitHub. And you don't want that to be SSR'd every time because it's slow. You don't want it to be fully static, because then the content doesn't get refreshed. And it's tricky to implement that by yourself because it's complicated. You got cache, revalidation, other things. Next.js has a built-in, so why not? You can have that in Next.js as well. And then i18n and other Next.js features, CSS optimization, fonts. And you can have normal JS routes as well mixed with your documentation. So it's helpful when you are, like, adding documentation to your existing website project. And it has more features like preview mode, API route, middleware, you name it. And this is an example of doing ISR, incremental static regeneration, in MDX with Next.js. So it looks like a JavaScript file, but it's actually a MDX file.

4. Static Generation and Next.jar Features

Short description:

You can define a get static props function to fetch API data and render it in a component. The use SSG hook ensures fast, static page loads with regular regeneration. Next.jar allows combining Next.js features, and the theme is extendable. Showcases like Minion.js and Turbo demonstrate the flexibility of Next.jar, with features like React code integration, search, and multi-zone architecture.

So you can define a get static props function here, which fetches the API from GitHub to know how many stars your projects have. And then you define a component which renders the data. There's a use SSG hook which passes the props to your component as a context. And then you can render it there. And you might notice there's a Revalidate16. If you are familiar with Next.js, that means every minute your cache will be invalidated. And then you will statically regenerate that and cache that on the server. So every page load is fast, is instant, because it's static. And every 60 seconds it gets regenerated. So the number is always latest, always fresh.

And so I have a example. So it looks like this, it's a static page. And every time the number gets... No one starts it yet. Yeah. But see? It updates. And those are just some general features, but there are a lot more. You can basically combine every Next.js feature with Next.jar. The theme and documentation layout itself is very extendable as well.

So I have a few showcases, where ourselves and from our community, they made a lot of fancy documentation websites based on Next.jar. One is Minion.js. It looks nice, right? Because you can basically write any of your React code there, but it's a Next.jar site, and you get search, and it's very fast. You get a lot of features there. And Dark mode as well, looks nice. And Turbo, the Turbo website is a little bit more complicated. It has Turbo Repo and Turbo Pack projects. So you can have multiple documentation in one project. So you get some kind of multi-zones architecture there. They are in the same Next.js project, powered by Next.js. And then you can have block building as well.

5. Introduction to Nextra and the V2 Release

Short description:

And what you write is basically just markdown files, which is incredible. The Good is a community member doing something even fancier. They are an ecosystem of open source projects, making each project a documentation site under the main website. The architecture is highly extendable and easy to get started with. The V2 version of Nextra is being released with many new features. The vision is to improve the user experience of documentation websites without complexity. If you're already happy with Nextras, give Nextra a try for your documentation needs.

And what you write is basically just markdown files, which is incredible. And we got a community member, the Good. They are doing something even fancier. They are a ecosystem of a lot of open source projects. And many companies does do that. You have a lot of projects, a lot of things to maintain. And they make every one of the project a documentation site under the main website. And they are all Nextra projects. They are all nested in the main organization. As you can see, the architecture can be very, very extendable. And you can do a lot of things with it. And the most important thing is it's very easy to get started. And today we are releasing the V2 version of Nextra, which has a lot of good things built in. And yeah, that's one of our region. Our vision is to bring more ideas of improving your user experience of your documentation website without making the process boring and complex. And if you are already happy with Nextras, you might want to try out Nextra to build your documentations.


Q&A about Extra and Nextra

Short description:

Yep, that's my talk. You can try it out. We have some questions about Extra. Can it replace Storybook for component library docs? It can be configured for other use cases like a blog site generator. React components don't show up in the built-in search. Nextra is considering support for the new app folder and React server components.

Yep, and that's basically my talk. And you can try it out. Woo! Woo! Woo! Woo! Woo! Woo! Woo! Woo! Woo! Yeah. Do you want to join me? Yeah. Yeah. Step into the hot seat. Thank you for that talk. That was great. I feel like I learned a lot. Now I want to go write stuff.

We have a few questions for you already, so that's great. A couple are about hypotheticals, usage, et cetera. For example, can Extra replace Storybook for component library docs, perhaps? Yeah, we do provide some built-in components, like tabs and some basic container component. But we can for sure make some component preview and editor building, yeah. And similarly, sort of on the same line, could it be configured for other use cases? For example, it looks like it has all the features to be an amazing blog site generator. Yeah, my personal blog is probably an Extra as well. So, yeah, it's a good use case.

Where can people find that? You can find out on my Twitter link. You heard it here first, folks. How do React components interact with the built-in search? Does their content show up? So, the search only indexes the markdown content. So, React components will not be indexed because they are using code. Yeah. Cool. Is Nextra going to support the new app folder and React server components? We are thinking about it. But it's a big change. And it somehow feels different than maintaining a directory of content. It's more like a nested application thing. But the good thing is you can use pages and app at the same time. They are not conflicting with each other. So, yeah.

Localization, Collaboration, and Customization

Short description:

I love the future of how all the things mix together. Nextra supports localization with multiple files for different locales. Collaboration on documentation sources is made easy with built-in features like the provide feedback link and the ability to create GitHub issues directly from the documentation. The simplicity of using markdown files and the GitHub-friendly nature of Nextra have encouraged more contributions to the Docs. Personalizing the Docs UI is possible by configuring the main color or providing CSS to override existing components.

Cool. I love the future of how all the things mix together. I'm sure some day it'll all be very interdependent.

Do you recommend anything for localization support with Nextra, or is the built-in way sort of easier?

It's already supported. You can put multiple files with different extensions of the locales. So, you'll have the language switch automatically. I would recommend that way. It's on the docs.

Cool. Amazing.

Which way do you recommend to work on the documentation sources collaboratively?

That's a good question. Because when we were initially designing Nextra, we wanted to be a project aimed for open source websites. We have a lot of features built in, like you have on every page, you have the provide feedback link. And when you click on that link, it opens the GitHub issues page and automatically fills in the page and tags the issue with feedback tag, with the feedback label. So even if you don't have an API or database to store those user feedbacks, all your, all your documentation sections will have the Create Issue link. So it's very easy to work on that in public. And since every page is just a simple markdown file. So it's so easy for people to contribute.

Yeah. I think that's it's very GitHub friendly. Yeah. We actually have a community friend who said that after switching to Nexra and make the markdown files cleaner because previously it's something mixed with a bunch of configuration headers and now it's just simple markdown files, very clean and well structed. They actually got more pull requests to contribute to the Docs, which is very nice. Yeah. I love that. Doc contributions are so important.

Oh, this one's interesting. How easy is it now, or will it be in the future, to personalize the Docs UI wise? How customizable?

That's a tricky one. We actually have a way to let you configure the main color, the theme color of the website. But yeah, you can always provide the CSS to override all the existing components.

Customization, API Integration, and Deployment

Short description:

But since it's an opinionated framework or theme, we don't recommend you to change that. In a similar vein of the UI, you can customize the navbar and sidebar by using a meta.json file. Nextra can be combined with generated API docs on top of Next.js, providing SSR and SSG capabilities. Nextra supports RTL and accessibility, allowing the entire theme to be configured for RTL languages. It can be self-hosted.

But since it's an opinionated framework or theme, we don't recommend you to change that. So only very slightly. Yeah. But it's got sort of … they'll all be very recognizable, I guess. Yeah. Cool. Thank you for that.

In a similar vein of the UI, you showed a lot of cool sites in your demo. How do you configure the navbar slash top bar of the docs and the stuff that's around it? Yeah. So when you have all the files in the directory, if you want to customize which should be placed in the navbar or the sidebar, you can have a meta.json file everywhere in the pages folder. And then you can simply specify, okay, this file should be used as a page instead of a section in the docs. So, it's a small json file. Right. We love json. Thank you for that.

Oh, cool. What is your recommendation, and I don't know if this is possible, to combine Nextra with generated API docs? Yeah, that's a good question. This is actually on top of Next.js, so you can have SSR, SSG everywhere. So then you can fetch from your CMS source in the SSG function, and yeah, we will provide more examples about that, but it's possible. Yeah. Does that mean it's not indexed research? We are working on the docs, but we got some projects working in that way, but we are not documenting that well yet. Well I have a great tool you can use for that. Does it support RTL, which I assume is React testing library and not right-to-left? Don't use acronyms. The answer is yes. We are very serious about RTL and accessibility, so we spend a lot of time on that. The entire theme can be configured to display the RTL language and everything will be flipped. I love that. Should it be deployed on Vercel, or can we self-host? You can self-host. It's Next. You can self-host.

Combining Documentation and Live View

Short description:

Could Nexture be used for combining documentation and live view of components for non-React projects? We want Next.js to be on top of Next.js, adding small innovations to the documentation part. Planned features include building social card generation for every Docs page and a powerful search functionality. Integration with Storybook or other back-end APIs is not yet planned, but it may be considered in the future. Open source project maintainers often work on multiple projects to avoid burnout and gain fresh perspectives. Xu will be available for further questions at the speaker Q&A room.

Power to the people! Could Nexture be used for combining documentation and live view of components for non-React projects? Non-React project? I don't think that's possible. Maybe you can use a cosign box or something there, and then you can use any. That could be good.

There's a couple of questions in the queue which are sort of like, how do you see it being different from some of the alternatives, like DocuSource or a custom Gatsby doc site? Is there anything there that you want to share? I know these are always kind of hard questions.

Yeah, I think these are great tools, but when we are designing Next.js, we kind of like to avoid duplicated work. We want it to be on top of Next.js, so every Next.js feature will be in Next.js automatically, and then we can add some small innovations to the documentation part instead of a dev server or compiler or bundler stuff. So, for example, things we are planned to add, one is building social card generation for every Docs page, so when you are sharing those to social media, you get nice cards. And things like the searching search is something, as far as I know, the other Docs generator, they don't have. You need to configure it by yourself, at least. Yeah. So part opinionated, part plugs in well to the ecosystem, part we can do what we want, which we love. Yeah. Cool.

Let me see if we have any of these left. We talked about self-hosting. Any integrations planned with Storybook or anything else? Not yet, but yeah, we can consider the first milestone is to get it stable and full featured and then integrate into more back-end APIs. It's possible now, but we want to provide the best user experience so we can optimize for other cases. Cool.

I'm already swolled, let me tell you. I wish I had more docs to write. This one is nice. next while still working on other or smaller open source projects? Okay. So that's a common issue for open source project maintainers. So the way I work on things is, usually when you are working on one project for too long, you will get burned out very easily. So the way I work on things is when I feel being stuck on one thing for too long, I kind of like want to have a different project, like totally different, to just think about different things and maybe sometime after I can get better ideas on the previous one and then I can switch back. Yeah. That's cool. So they kind of inspire each other somehow. Yeah, and I can take a small rest to think about different things. Yeah. Fresh in the mind. Yeah. All right. Well, that is all the time we have for questions here but Xu will be at the speaker Q&A room over by reception if you have more questions about Nextra. Thank you so much for joining us and sharing. Thank you. Thank you.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

React Advanced Conference 2022React Advanced Conference 2022
25 min
A Guide to React Rendering Behavior
React is a library for "rendering" UI from components, but many users find themselves confused about how React rendering actually works. What do terms like "rendering", "reconciliation", "Fibers", and "committing" actually mean? When do renders happen? How does Context affect rendering, and how do libraries like Redux cause updates? In this talk, we'll clear up the confusion and provide a solid foundation for understanding when, why, and how React renders. We'll look at: - What "rendering" actually is - How React queues renders and the standard rendering behavior - How keys and component types are used in rendering - Techniques for optimizing render performance - How context usage affects rendering behavior| - How external libraries tie into React rendering
React Summit Remote Edition 2021React Summit Remote Edition 2021
33 min
Building Better Websites with Remix
Remix is a new web framework from the creators of React Router that helps you build better, faster websites through a solid understanding of web fundamentals. Remix takes care of the heavy lifting like server rendering, code splitting, prefetching, and navigation and leaves you with the fun part: building something awesome!
React Advanced Conference 2022React Advanced Conference 2022
30 min
Using useEffect Effectively
Can useEffect affect your codebase negatively? From fetching data to fighting with imperative APIs, side effects are one of the biggest sources of frustration in web app development. And let’s be honest, putting everything in useEffect hooks doesn’t help much. In this talk, we'll demystify the useEffect hook and get a better understanding of when (and when not) to use it, as well as discover how declarative effects can make effect management more maintainable in even the most complex React apps.
React Summit 2022React Summit 2022
20 min
Routing in React 18 and Beyond
Concurrent React and Server Components are changing the way we think about routing, rendering, and fetching in web applications. Next.js recently shared part of its vision to help developers adopt these new React features and take advantage of the benefits they unlock.In this talk, we’ll explore the past, present and future of routing in front-end applications and discuss how new features in React and Next.js can help us architect more performant and feature-rich applications.
React Advanced Conference 2021React Advanced Conference 2021
27 min
(Easier) Interactive Data Visualization in React
If you’re building a dashboard, analytics platform, or any web app where you need to give your users insight into their data, you need beautiful, custom, interactive data visualizations in your React app. But building visualizations hand with a low-level library like D3 can be a huge headache, involving lots of wheel-reinventing. In this talk, we’ll see how data viz development can get so much easier thanks to tools like Plot, a high-level dataviz library for quick & easy charting, and Observable, a reactive dataviz prototyping environment, both from the creator of D3. Through live coding examples we’ll explore how React refs let us delegate DOM manipulation for our data visualizations, and how Observable’s embedding functionality lets us easily repurpose community-built visualizations for our own data & use cases. By the end of this talk we’ll know how to get a beautiful, customized, interactive data visualization into our apps with a fraction of the time & effort!

Workshops on related topic

React Summit 2023React Summit 2023
170 min
React Performance Debugging Masterclass
Featured WorkshopFree
Ivan’s first attempts at performance debugging were chaotic. He would see a slow interaction, try a random optimization, see that it didn't help, and keep trying other optimizations until he found the right one (or gave up).
Back then, Ivan didn’t know how to use performance devtools well. He would do a recording in Chrome DevTools or React Profiler, poke around it, try clicking random things, and then close it in frustration a few minutes later. Now, Ivan knows exactly where and what to look for. And in this workshop, Ivan will teach you that too.
Here’s how this is going to work. We’ll take a slow app → debug it (using tools like Chrome DevTools, React Profiler, and why-did-you-render) → pinpoint the bottleneck → and then repeat, several times more. We won’t talk about the solutions (in 90% of the cases, it’s just the ol’ regular useMemo() or memo()). But we’ll talk about everything that comes before – and learn how to analyze any React performance problem, step by step.
(Note: This workshop is best suited for engineers who are already familiar with how useMemo() and memo() work – but want to get better at using the performance tools around React. Also, we’ll be covering interaction performance, not load speed, so you won’t hear a word about Lighthouse 🤐)
React Advanced Conference 2021React Advanced Conference 2021
132 min
Concurrent Rendering Adventures in React 18
Featured WorkshopFree
With the release of React 18 we finally get the long awaited concurrent rendering. But how is that going to affect your application? What are the benefits of concurrent rendering in React? What do you need to do to switch to concurrent rendering when you upgrade to React 18? And what if you don’t want or can’t use concurrent rendering yet?

There are some behavior changes you need to be aware of! In this workshop we will cover all of those subjects and more.

Join me with your laptop in this interactive workshop. You will see how easy it is to switch to concurrent rendering in your React application. You will learn all about concurrent rendering, SuspenseList, the startTransition API and more.
React Summit Remote Edition 2021React Summit Remote Edition 2021
177 min
React Hooks Tips Only the Pros Know
Featured Workshop
The addition of the hooks API to React was quite a major change. Before hooks most components had to be class based. Now, with hooks, these are often much simpler functional components. Hooks can be really simple to use. Almost deceptively simple. Because there are still plenty of ways you can mess up with hooks. And it often turns out there are many ways where you can improve your components a better understanding of how each React hook can be used.You will learn all about the pros and cons of the various hooks. You will learn when to use useState() versus useReducer(). We will look at using useContext() efficiently. You will see when to use useLayoutEffect() and when useEffect() is better.
React Advanced Conference 2021React Advanced Conference 2021
174 min
React, TypeScript, and TDD
Featured WorkshopFree
ReactJS is wildly popular and thus wildly supported. TypeScript is increasingly popular, and thus increasingly supported.

The two together? Not as much. Given that they both change quickly, it's hard to find accurate learning materials.

React+TypeScript, with JetBrains IDEs? That three-part combination is the topic of this series. We'll show a little about a lot. Meaning, the key steps to getting productive, in the IDE, for React projects using TypeScript. Along the way we'll show test-driven development and emphasize tips-and-tricks in the IDE.
React Advanced Conference 2021React Advanced Conference 2021
145 min
Web3 Workshop - Building Your First Dapp
Featured WorkshopFree
In this workshop, you'll learn how to build your first full stack dapp on the Ethereum blockchain, reading and writing data to the network, and connecting a front end application to the contract you've deployed. By the end of the workshop, you'll understand how to set up a full stack development environment, run a local node, and interact with any smart contract using React, HardHat, and Ethers.js.
React Summit 2023React Summit 2023
151 min
Designing Effective Tests With React Testing Library
Featured Workshop
React Testing Library is a great framework for React component tests because there are a lot of questions it answers for you, so you don’t need to worry about those questions. But that doesn’t mean testing is easy. There are still a lot of questions you have to figure out for yourself: How many component tests should you write vs end-to-end tests or lower-level unit tests? How can you test a certain line of code that is tricky to test? And what in the world are you supposed to do about that persistent act() warning?
In this three-hour workshop we’ll introduce React Testing Library along with a mental model for how to think about designing your component tests. This mental model will help you see how to test each bit of logic, whether or not to mock dependencies, and will help improve the design of your components. You’ll walk away with the tools, techniques, and principles you need to implement low-cost, high-value component tests.
Table of contents- The different kinds of React application tests, and where component tests fit in- A mental model for thinking about the inputs and outputs of the components you test- Options for selecting DOM elements to verify and interact with them- The value of mocks and why they shouldn’t be avoided- The challenges with asynchrony in RTL tests and how to handle them
Prerequisites- Familiarity with building applications with React- Basic experience writing automated tests with Jest or another unit testing framework- You do not need any experience with React Testing Library- Machine setup: Node LTS, Yarn