Documentation Website in Next.js with Nextra

in the modern webd world we have the luxury of having a bunch of different options for how we can quickly spin up some docks if you're an asro fan maybe it's Starlight but nextro which is built on top of nextjs and uses MDX is compelling for not only how quickly and easily you can spin up the Docks but how great of the ux it provides this is what I've been using for my documentation sites like nexcloud which gives me as an individual maintainer a really easy way to manage and provide information to the developers so let's just Dive Right In for a new site when you're in nextra you kind of have two options where you have a documentation theme and a theme and you can even create your own custom theme but we're going to go with documentation of course where now you have two options where we can start off from the next docs template or you can install it fresh as a new project now I personally prefer to just start it off from the template as it makes it a lot easier to use but what I'm going to do is I'm going to copy this URL and I'm going to use it as a nextjs template and in my terminal I'm going to say npx create next app I'm going to pass in minus E for the examples flag I'm going to paste in that URL for the GitHub repository then I'm going to add one more option and I'm going to name my project my docs site once that's ready I'm going to navigate into my new Doc site I'm going to run mpm run Dev I'm going to open up that Local Host and we can see as easy as that we now have our new Doc site so if we start to navigate around we can kind of see some of the features that come out of the box with this such as if I navigate around we can see some of the elements and we can even see that we can do things like manage state if we want to create custom components but we can even search for through our documentation where if I wanted to look for this external component we can see that it pops right up and allow to easily navigate and we could probably expect this from most starter templates these days but we can see that we can select our dark mode theme and it looks just as good in dark mode as it does in light I prefer light mode but that's one of the compelling things about nextra for me is not only is it very functionally it has a lot of features inside of it but it also looks really good and is a great way of communicating information in a clean way so let's see how we can actually start customizing this thing looking inside the code we can start to see how the project is actually structured where we do have a components directory but that doesn't really have much in it right now that's just the counter example that we saw earlier but we have our Pages directory which has all the informational Pages like our homepage and we can see that it's just MDX getting added to the page in order to have more advanced ways of controlling this sidebar we have this meta Json file which we can see all the pages are listed out as well as the information for each and maybe even the way that we actually present that information but as we can see we get additional options when we're actually defining these out we can specify the type of file or page that this is and we can see about for instance is considered a page which means that it puts it up in the top level navigation not necessarily the sidebar and in that navigation we can even provide external links such as contact which would then of course go to that external link which in this case goes to the creator of nextra but before we try to start messing around with any of this if we scroll down even further we have this theme. config file which is going to give us some more options for the UI such as this GitHub link and the Discord icon or if I want this to go to my eventual site I want to have this at github.com where it's going to be my docs site and while of course this site isn't quite available yet we can see if we click it it'll go to that link or if I want to update the chat link to my space jelly Discord we can see clicking it is going to start opening up that invite now the nice thing about the logo is this is going to render out as a react component so I can really put anything I want in there but for now let's just add this as my docs and we can see immediately it updated but if I wanted an icon to go along with it such as maybe I want to include a rocket and I'm going to copy this jsx I'm going to paste it in right before my docks here we can see that while it needs a little bit of styling it dropped right in or if I add a few styles in there I think we're good to go if we head to the nextra site we can see all the options under the theme configuration like some of the more compelling options like being able to customize our SEO as well as how our head tags are actually rendering but we also get some simpler options for how we can customize our theme where it provides a hue or saturation which isn't necessarily as intuitive maybe we could provide a hex or something but if we change this Hue such as if I wanted to make it more like a purple we can see that I can grab this 277 and I set my primary Hue to 27 27 we can see that my doc site was updated to that new purple so how about actually updating some of the content so if I head back over let's start off with the homepage on the homepage I want to provide something a little bit more interesting and visual if we look in the nextra doc similar to the theme we get a lot of options for how we can customize the actual page now a lot of this has to do with how it's actually organized inside the sidebar but if we get down to the advanced section we have some options for the theme components as well as the layouts where we can see that we get this raw layout as well as a full layout where raw is going to not inject any Styles as it typically does and full is just going to give us more of a fullwidth layout now we set that configuration inside of this meta Json file where first we need to actually start to break down this section where I'm going to Define an object for the configuration and we Define our title as our introduction but then if we Define our theme options for this page we can say that we want the layout to be raw now if we look at the site we can see it it's exactly that and we don't get any Styles along with our content but if instead I just want to have a fullwidth layout I don't want it to be completely bare of styles let's make this instead full and we can see to start we have our content back in here with all the Styles but it made it full width as opposed to some of the other Pages where we can see that we have this sidebar but we can even start to remove some of the other elements such as if we want to get rid of this sidebar along with some of these other options such as breadcrumb footer sidebar table of contents let's set sidebar to false and we can see that we get it full width I probably also don't need this pagination so I'll also set my pagination to false we can see this is cleaning it up a lot so now I have full flexibility for how I actually build the content and styles inside of this section such as if I want to add a hero Banner how about if I create a new component I can export a new constant called hero let's set this equal to a new component where maybe I wanted to drop an image in there so I imported CL image and then I actually render this out on the page we can see how easy it was to actually add a component or maybe I also want to create a wrapper for all my docs such as if I want to contain the layout and while I probably don't want to do inline Styles I probably want to install something like Tailwind which is probably for another video I can now take this wrapper and actually start to wrap all my content with it and we can see everything is nicely contained I can even start to add some text on it and while this is just a silly simple example we can really start to see how our layout will come together for our homepage and whatever way that we want that to look while still be able to provide access to the other documentation that is in the more organized and structured format which is just really easy to create all the different pages that we need for all of our different content where then we can start to tap into even some of the built-in components that nextra provides like the tabs that are really nice and easy to drop in or simply rendering a table which can be a critical component for being able to provide reference documentation or maybe that critical component for your docs is being able to show some dashboard visualization such as maybe usage statistics so let's see how we can do that with tremor

Channel: Colby Fayock

Views: 1,668

Keywords: next js website, next js documentation site, next js documentation, nextjs docs, documentation website, create documentation website, documentation website design, nextra

Id: mVDMvYQL7-A

Length: 6min 57sec (417 seconds)

Published: Thu Nov 09 2023