1. Introduction to Next.js and Nextra
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.
2. Features of the Project
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
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.
4. Static Generation and Next.jar Features
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
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
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
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.
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
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
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.