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

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.

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.

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.

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.

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.

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.

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.

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.

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.