Create and deploy a documentation website

Captions provided by White Coat Captioning (https://whitecoatcaptioning.com/). Communication Access Realtime Translation (CART) is provided in order to facilitate communication accessibility and may not be a totally verbatim record of the proceedings.

JASON: Hello, everyone, and welcome to another episode of Learn With Jason. Today on the show, we have Sebastien Lorber, and now it's on the next, next episode. Okay, my scenes are rebelling, everybody, and I don't know why. It's now showing me the next, next episode, which I'm struggling with a little bit. I don't know how or why it's doing that, but I guess we're just going to live with it, because otherwise I'm going to spend the whole episode debugging this. So, this is not Jessica Sachs. Jessica is on next time. This is Sebastien Lorber. And Sebastien, I apologize for the technical chaos that's happening right now. How are you today?

SEBASTIEN: I'm fine, thank you. Really happy to be here, because I actually know you for a very long time.

JASON: Yeah, so, thank you for taking the time. Before we get started, can you maybe just give folks who are unfamiliar with your work a quick overview of who you are, what you do?

SEBASTIEN: I'm a freelancer, I'm working with Facebook and Docusaurus for the last almost three years now. And I'm also the publisher of This Week In React newsletter, which is a newsletter I started two years ago, and I try to keep at the senior up to date on the regular basis, and it's working quite well. I have maybe 16,000 subscribers now. So, it's growing fast, and slowly it's taking it's becoming a sustainable project. So, I'm quite happy to do that on the side.

JASON: Excellent. I am very quickly throwing together like the worst little overlay thing to try to fix this, so people at least know what your name is. I am, again, kind of I'm a little embarrassed at how silly this is being for me. So, yeah, let's just just going to move this up a little bit, and I don't have a quick probably a great shape here that I can we're going to use a basic black, we're going to make that much smaller than it is now, which will allow me to cover this up. Jesus. This is awful. All right. You know what, this is good enough. All right, chat, that's how the sausage is made, I guess. So, Sebastien, I am really excited to have you on, because we are talking about something that I have kind of lightly used in the past, but haven't really had a chance to use heavily, and you just had a major release of it. So, you are talking today about Docusaurus 2.0. So, for those not familiar, can you give us a bit of a background on what Docusaurus is. What is it, how do people use it, why would you choose it, all those good things.

SEBASTIEN: Yeah, so, the idea of Docusaurus is that I wasn't there at the time, but at Facebook, they have a lot of Internet project and open source project. They need documentation for all of them. So, now they needed to document all of them, but it was a problem, because they had the static site generator, and they copy/pasted the same template over and over again for each project they had. So, at some point it was not very scalable, because any time they wanted to add some new features to the template, it was complicated to all the projects and keep them all to date. They wanted to make a tool to focus on the contents. So you just write markdown files, few things, configuration files in CSS, and then you have a doc site that looks great, is accessible, is performant, and has a great user experience. All the features that documentation site needs. So, the idea is really to I like to compare Docusaurus to where you spend less time and you get great from the tool you use. At the same time, it's expansible enough, so if you want to do the more advanced case, you can still implement them with Docusaurus.

JASON: Yeah, yeah. I mean, I feel like that's sort of the holy grail for any project, right, is you want it to be so easy to get started, you know, as close to one click as you can to get started, start writing, and have something up on the Internet. And, at the same time, you don't want to remove capabilities from developers who want to do more advanced use cases, who want to dig deeper and customize and try new stuff and add, you know, flashy features. And, so, how have you approached striking that balance? I guess how do you think about that? When you're approaching a feature in API design, something like that, how are you balancing the need for it to be really easy for somebody who doesn't want to write code, but still very customizable for somebody who does want to write code?

SEBASTIEN: So, for me, the idea is that we try to have a stronger opinions that make sense and try to infer whether user fields is intuitive. So, we have conventions that make things easy, and somehow it's the conventions that really exist, for example, when people write documentation on GitHub, for example, the idea is that, for example, you already have a documentation, and GitHub has markdown files, and you should be able to bring all that documentation to Docusaurus folder and just run command and it should be able to bring you some site. Sometimes you have to do some tweaks to make it work, but the idea is that it should be quite easy to get started. Particularly, if you already have some markdown files that you want to publish. And for the more advanced features, I think the idea for me is to do like a bit I don't remember the name, it was maybe the extensionable web manifesto, the idea to focus first on low level primitives, but make sense and that we know will not be refactored later, because they are good enough. And then if it makes sense to make it easier for the user to create some kind of shortcuts and preset some, so it gets easier to use these variable features. But for me the idea is somehow to create many escape hatches everywhere, so that no use case is impossible. Some use case will not be very straightforward, but they should be possible no matter what, whether user is trying to do so. The idea is to add the primitives, even if those primitives are not the most straightforward to use. I try to build on that, but we don't start from specific use case. We try to find primitives that make sense for anyone somehow.

JASON: Great. Yeah, I do like that as an approach. You know, it feels like a good way to give someone a jump start without removing their autonomy, right. I think that's a really nice way to approach that. So, let's talk a little bit about the 2.0 release. So, for Docusaurus 2.0, you've got a lot of new features. So, what are some of the highlights of what's coming in, in 2.0?

SEBASTIEN: So, first of all, Docusaurus is a static site generator, and the first version was based on React, but it was not like Next.js and Gatsby. It only used React as a server template. Somehow it was just used on the server, and React was never loaded on the client. It was not a single page application. We only used it as a server templating language. Version 2 is quite different, because somehow all the override from us, it will activate React from the client, and you will have a single page application navigation. So, this is one of the main difference, and also a difference that we have is we try to make it more modular. So, we have a plug in system which enables the community to create their own plug ins. And we made the customizations much more possible. The first version was more like a monolithic version, where you can't customize a lot of things outside the CSS of a site. But the CSS is quite limited. Sometimes we need more advanced customizations, like the elements we render, things like that. So, in Docusaurus, you can override basically everything. Some things are not really safe to override, because we consider those as implementation deters, but in any case, you can always override the implementation details and implement all direct components the way you want.

JASON: Got ya, okay, great. Well, this is, yeah, this is a very, like... I'm excited to dig in. So, maybe the easiest thing to do is just actually start building. Does that sound like the right call?

SEBASTIEN: Yeah, I think we can give it a try.

JASON: All right. Let's do it. So, I am going to very quickly copy my little hackie thing. I'm going to move us over into paired programming. I am going to what a nightmare with my tech today. Okay, here we go, yeah, we're going to save that. We're going to reload this page. It's going to show us the wrong details. Oh, it's just killing me, just absolutely killing me. I'm going to paste this in, and we're going to put that over the top here, put this over the top here, so that it is somewhat legible. And we're going to call that good enough. All right, so, this episode, like every episode, is being live captioned. So, let me pull over the details here. So, if you would like to follow along with the live captions, you can see the episode on Twitch. Click that closed caption button that is right there on the Twitch player to see them. And that is being made possible through the support of our sponsors, Netlify, Nx, New Relic, and Pluralsight, all kicking in to make this show more accessible to more people, which I really do appreciate. So, thank you all for kicking in to, you know, make this show better for everybody else. We are talking today to Sebastien. So, that is Sebastien Lorber. And nope I spelled it wrong. Spelled it wrong. There. That's the one. So, you can follow Sebastien on Twitter if you want your Docusaurus and other news. I know you're doing This Week in React, which is a cool newsletter that I'm actually just going to direct shout out to folks, if I can get it to load.

SEBASTIEN: Thanks.

JASON: There it is. Go get on that newsletter and learn what's coming in the React space. Outside of that, we're talking about Docusaurus. So, I'm going to make this screen a little bit bigger. I'm going to head over to the Docusaurus website. Here. That will drop that in the chat. And then I am at the end of my knowledge. What should I do next?

SEBASTIEN: What should you do next? So, we have two possible ways. I think one great way to get started with Docusaurus is to try it in your browser. So, we have a domain Docusaurus.new. I think it's the same link. When you have it in your browser, you should lead to this page. If you have Chrome, I think you have, you can try the playground, the one on

JASON: I'm in arc, which is still Chromium based, so we'll see if this works.

SEBASTIEN: I don't know.

JASON: We'll try it. If it doesn't work oh, good sign so far.

SEBASTIEN: For people that don't know, stack bit is a technology that runs from inside your browser, so you don't have to install anything. It's a quite convenient way to get started. It's not like Sandbox, because I think Sandbox is using a remote Docker containers, and Stackblitz is using web assembly technology to make it possible to run from Docusaurus inside your browser.

JASON: Yeah.

SEBASTIEN: What we load here in Stackblitz is the Docusaurus, the first thing you get when you initialize a project locally. I wanted to show you to give it a try. This technology works fine most of the time, but sometimes there are some glitches. I like for recruiting issues, but I wouldn't work for inside this. Maybe next year.

JASON: Gotcha. All right. So, we are going to go back to Docusaurus, and I'm going to hit, I'm assuming, get started is going to show me how to create a new one? This looks right. Okay. So, I'm going to go into my terminal here, npx create Docusaurus. Geez, I can't spell today. Docusaurus 2.0. We'll do Docusaurus 2, and then I'm going to pre fix with LWJ, because I probably can deploy something like that. Classic, is classic the theme?

SEBASTIEN: Classic is the theme, yeah. I think you can omit it, actually, just type the first and we'll ask you to fill the rest.

JASON: Nice.

SEBASTIEN: I think you can, for example, create young Docusaurus, but there are some things like npx, Next.js, not exactly the same format. So, we use what works for everyone, even if it's a bit longer. Hopefully, in the future, we will be able to shorten a bit this, because it's not really easy to remember.

JASON: Got it. Uh huh. Oh, this is cool. So, classic is probably what we were looking at on Stackblitz, is that correct?

SEBASTIEN: This is the thing you should choose. There are not a lot of third party terms that you can use. It's almost the same, but maybe you can use a TypeScript. I don't know if you choose TypeScript.

JASON: I did choose TypeScript.

SEBASTIEN: Okay.

JASON: This is growth. I think, you know, six months ago, I would have been like, oh, not TypeScript, that will slow us down, but I'm not going to say I'm good at TypeScript, but I am becoming functional. Yes, Vinny, it is growth. This will take us a moment. Let me make sure I'm not, like...

SEBASTIEN: Maybe you can try some things in the Stackblitz window in the meantime.

JASON: Here we go. It's moving now. We are going to move into the Docusaurus. And then we already have our dependencies, it looks like. So, yes. I can run an NPM start. Here, open it up. Look at that. We now have a running site. Okay, so, this is cool. So, maybe we can start with a bit of a tour. So, for somebody who's never seen Docusaurus before, yeah, Vinny, my overlays are broken today. In post we will edit this to have the right title, but unfortunately right now, it's showing the next episode, and I don't know why. I'm going to have to fix that after the show. In the meantime, sorry. So, all right. Let's do a tour of Docusaurus. For somebody looking at this for the first time, what are the major features I should be looking at, and kind of where should I be directing my eyes?

SEBASTIEN: So, what I did with Docusaurus, I wanted the getting started experience is really easy to understand. So, when you initialize the site, you have the tutorial inside the site. So, you just have to click on the button. If you follow the instructions, you should be fine. I tried to make it short, nothing complicated. You just have to follow the instructions.

JASON: Uh huh. Okay, so, we did this. We set up a new site. We've started it, we're running, great. We can drop into the basics. So, we can create pages and documents or groups of pages, okay. We've got a blog. So, if we go over to the blog, these are blog posts.

SEBASTIEN: Yeah.

JASON: That's great, okay. So, back in here, looking at the basics, we've got markdown features good, then we can deploy the site. All right. So, excellent. I will probably lean on you to be my tutorial here. So, I probably won't jump through this one. But let's dive in and say we want to... I don't know, what should we do first here? Should we be

SEBASTIEN: We have free plug ins that are content plug ins, so those plug ins are responsible for reading markdown files on your Docusaurus site, and creating rules and pages for your site. So, we have one plug in for the landing pages. For example, if you want just one individual page that is completely different from the other, you can create this page in markdown or in React. We have docs plug in that is for pages for a version, side bar, things like that, so you can navigate from one doc to another. For example, when you look at the tutorial, you are in the docs plug in, because those are sets of documents, and you can navigate backward and forward from one document to another. We also have features on top of that, like versioning. That means to version a set of documentation across time. This is great, for example, if you want to have an iOS or Android and both have different versions. You can do that with Docusaurus. We have the blog plug in, but that means you have to create the blog posts, page admissions, things like that. We can start simple with the landing pages. So, what I can suggest to you is go to the go to your idea and create some markdown file inside the SRC. You can look maybe at the folder switcher, I can extend to you how it is.

JASON: Give me just one second. It's going to be going to just suspend that for a second. I'm going to get a nit, otherwise VSCode will keep everything dim on us. No, no, I was almost there. One more time. Here we go. We're going to foreground that. Here we go. We can see the components in here. So, we've got a source directory, we've got the blog is its own folder. The docs are their own folder.

SEBASTIEN: We have all the little things. Maybe I can explain to you what each file is.

JASON: Yeah.

SEBASTIEN: So, the blog is for markdown files for the blog. We have one that registers regular photos of your blog, if you want, for example, to just reference them, you can do that. Avoids copy/pasting and editing multiple blog posts. We have the docs folder, which is for the documentation of

JASON: Oh. So, I'm actually going to pause you real quick just to show how cool this is. So, in the authors.YAML, you define an author, then you can refer to the author here. But you can also explicitly declare an author if it's somebody who's like a one off guest author, they are not going to be on the blog more than the once. That's really cool. That's very handy to be able to do that.

SEBASTIEN: You can do both at the same time, for example, you can have some regular authors. I mean, you can create a blog post with someone else and be a regular author of the blog post. So, you use yourself and then you this is going to be in line if it's not a regular author of the blog post. So, you have the freedom to reference or fill all the details of the author.

JASON: Really nice, yeah. That's really handy. If you were going to do that, just so I understand, because YAML is hard. You would do something like this, and then you would add like that?

SEBASTIEN: Yeah, I think it should work. Maybe take a look.

JASON: Okay, let's try. We have the site running, we can go and look at this.

SEBASTIEN: I think it's the last one.

JASON: First blog post. There it is!

SEBASTIEN: Seems to work.

JASON: Great. Yeah, okay. So, then we will undo that, and back it goes. All right. So, that's very cool. I mean, little stuff like that is just nice, because every time I build a blog, I always kind of talk myself into building my own front matters setup, and then I don't do things like pagination. If you look at my blogs now, they are just infinite lists, because I don't build pagination, I don't have these little shortcuts for things like authors. Granted, for me, it's my blog, so I don't have anybody but me on there. But, you know, I never take the time to build this stuff. So, it's so nice when a tool just hands you a suite of nice things like this, so you can just build and it's not at the expense of jank, like if you look at my custom rolled bog, it's just jank. Okay, so, I cut you off as we were talking about the blog. So, we've got the blog plug in here, put our markdown in here, got the authors.YAML. How does is this just magic, like if I create a blog folder, Docusaurus knows it's there, or do I have to specifically target folders with different types of Docusaurus plug ins?

SEBASTIEN: By default, Docusaurus will know this folder exists, but this is thanks to the configuration file. If you open Docusaurus config.js, you'll see there is a config file. This is the thing where you add all the details for the site. By default, we have something that loads the free content plug in that we provide by default. So, the docs, the blog, and the pages I don't see the pages. Maybe because there is no configuration to provide. This is quite simple, so you don't often customize the pages plug in, because you just have to drop a file in the pages folder and then it should work and create the appropriate page for you. So, there is no fancy configurations for this one.

JASON: Gotcha.

SEBASTIEN: You can add your site detail, the URL where it will be hosted once you know.

JASON: Okay, so, let's do this. We can keep that. Then we'll have it as, like, LWJ Docusaurus 2, that's going to be Netlify.app, as that's where we'll deploy this today. That seems okay. Then this would be like "Learn with Jason," the project name is going to be Docusaurus 2.

SEBASTIEN: Just to these informations are only required if you want to deploy to GitHub pages, which

JASON: Oh, GitHub pages, got it.

SEBASTIEN: The thing is, many people still want to use a host that doesn't have several Reacts and all those things. So, I don't understand them, but

JASON: Got it, got it. Can I delete this if I'm not going to use it?

SEBASTIEN: Yeah, you can delete it. But if you want to deploy to GitHub pages, we have a key to make it easier. You just have to run a component, it will build a site and deploy to your GitHub pages of your repository.

JASON: Really nice.

SEBASTIEN: The only thing that's complicated is to set up the Git permissions so you can actually push to the branch. This is a bit, or was a bit complicated, with the CI to set up. There are multiple ways to do this. It's easier to use Netlify.

JASON: Got it, got it. Okay. So, then down here, we're using the classic theme, and then we've set up the docs. So, there's a sidebar path, which we should talk about in a minute. This edit URL, which is really cool. So, does this mean if we want to edit this page, so looking at this one, going down, there's an edit this page link. Which is extremely cool. Now, for me to change this to be mine, in fact, maybe we should just deploy this real quick. Let's go to GitHub, go to Learn With Jason, go in here. We've already got this one set up, but let's add all, and we'll do a Git commit, work in progress, building out a Docusaurus 2.0 site. I'm going to GitHub repo create. And we're going to push an existing repository, which is this one here. I want the repository to live on my org, so we'll give it the org name, and we'll make it public. Get a remote, and we want to push. There it goes. Okay. So, now if I click this, it's going to open up our repo, right. So, if I want to make this editable, do I I just grab this link, or do I grab something else?

SEBASTIEN: This is just a link. So, what we provide is somehow the editor is just a prefix that we will append with the final path of your markdown file. So, you can point to whatever you want. It can be GitHub, it can be the file in edit mode, it can be the file in read mode, if you want. We allow you to provide a function if you have a more advanced need like, for example, this markdown file should go to GitLab and this one should go to GitHub. It's possible to do that. But the simplest is to just maybe replace the project and organization like you do and I think it should work fine.

JASON: Okay. This, if I click this, obviously, this is going to take me where I want to go, which is into the set. So, I'm going to save this. I'm going to come back out here, where it looks like this is set up. So, if I come down here then, it is, I think... oh, no. Doesn't contain the docs oh, I know what I did wrong. I included the docs suffix and shouldn't have done that. So, I can leave this out, all right. Then I'm going to go back to arc, close this one, and let's try again. And there it goes.

SEBASTIEN: Yep.

JASON: That is really that's really nice. So, okay, that configure is pretty straightforward. This also feels like we can do the same thing. We've got the edit URL here. And now our blog will have an edit option, as well, is that correct? So, if I go here, edit this page, it takes me over to the blog. Now you can make a suggested edit to the blog. All right. So, we're cooking with gas here. We've got this thing up on the Internet. It is actually functional. And if you want to check it out, chat, you can head over and look at the work in progress here, kind of follow along as we're building things. Okay. So, I'm with the config. Let's go down a little bit to the theme config. And maybe talk me through a little bit of what we're looking at here.

SEBASTIEN: So, the nav bar is the top of the layout of Docusaurus. So, what allows you to somehow configure the layout and things that are visual on your site, while the plug in configures for how we read markdown files and compute some properties like the edit URL and things like that. So, here we can change things to your infos, and you can change the top level bar of Docusaurus. Here you are in the build mode view, so it's a bit complicated to see it. Unfortunately, you have to expand. Yeah, so, now you see the nav bar at the top. If you are on the mobile version, you will have to open the unbugging menu to be able to see the nav bar items, but it's better maybe for the demo to show the desktop version. So, you can add the links to the nav bar. You can add we have additional types of nav bar items that you can use. The simple one is a link, but we also have things like your version topdown. We have a local drop down if your site is translated. Normally, you have the switch that is here by default. And if you enable the soft plug in, you will have a search bar being displayed in the corner of the nav bar.

JASON: And, so, maybe that's a good thing to try here right out of the gate. So, to enable search, do I need to do I have to set up an account or anything like that, or just I add the plug in and I'm good?

SEBASTIEN: So, the integration of Docusaurus is the the main integration is with Algolia. Many of open source sites are eligible to have a doc search for free. There are local plug ins that are unofficial, but many people use them. You can choose. We generally use Algolia, but if you don't want a free account, or are not eligible for a free account, you can use a local search plug in.

JASON: Yeah.

SEBASTIEN: So, maybe you can try it. You don't have a doc search account, but maybe you can try it. You can just, I think, in the config you have a preset.

JASON: In the config I have a preset here.

SEBASTIEN: Let me check the doc. I don't know exactly so, yeah, there is config somewhere.

JASON: Config here.

SEBASTIEN: So, at the same level of nav bar, you can add new attribute called Algolia. Algolia. You add app ID, yeah, the second one. And you add your Algolia app account, and there's an API key, the second one, I think. If I'm not wrong, the search bar should appear, hopefully.

JASON: So, this will break, because we don't have a search key in here.

SEBASTIEN: You have to have a search key? Maybe I can give

JASON: Algolia app ID is not allowed to be empty. That's okay.

SEBASTIEN: This is just a validation program, I think. Maybe there is another thing.

JASON: API key is not allowed to be empty. So, it is now... index name is required. Okay, we can add an index name. Can't resolve theme. We didn't add the search page, right, but we would need to install this?

SEBASTIEN: I think related to your browser, because I think it's there are some things where you have to restart your server maybe. So, I'm not sure exactly, but there are some cases where reload doesn't load the plug ins. When you change too much things in the config and add and remove plug ins, it's better to restart, I think.

JASON: Back on the homepage, and there is our search bar. This is broken, because we don't have valid data in there. But cool this thing works, has the command K shortcut. That's slick. Doc search, if you haven't used Algolia doc search, it's pretty pleasant to set up. It's free for any doc site. You got to make sure you take the right things. Let's see. Saw a joke in the chat if I wasn't sure somebody actually got hacked. Okay, so, yeah, doc search is very, very cool. We can do a whole episode later on how to set up a doc search. For now, I'm going to turn this off so we don't have a broken thing in here, but I'm really impressed with how quickly this stuff just kind of works. It's really, really nice whenever you just add the right config, then the right thing shows up. That is a very pleasant experience for me. Cool, okay. So, if I want to customize this homepage, where would I go to do that?

SEBASTIEN: So, you can go to the pages folder. Then you have index and this is just a direct component. Basically, you can do whatever you want, if you are a rack developer. If you are not a rack developer, you can create here we are customizing things, but I didn't tell you how to create pages. For example, there is the pages folder. If you want, you can create another filer, like JSON.MD, you can create a page with a markdown file. And you can write your markdown file, and there will be a page at /JSON, for example.

JASON: Okay.

SEBASTIEN: There's no link to it, so you have to go to the browser, but it should work.

JASON: Oh, cool. So, it's smart enough to auto theme, so wrap the page in there. I thought I was going to have to do some markdown front matter to set a layout and stuff like that. This is really clever. So, looking at this oh, and it already pulled the title across. How did it do that? Just noticed it grabbed the H1.

SEBASTIEN: Yeah, yeah, takes the H1 from your page, and it is able to put it as the title of the page, things like that.

JASON: That's slick, that's a nice touch.

SEBASTIEN: Yes, does in any color by default. You don't have to do many things, just have to write the content of the page, and customize some things, and just write a simple markdown files this way.

JASON: This is excellent.

SEBASTIEN: So, you have the choice to create markdown pages or React pages. Of course, if you do React pages, you have more flexibility. For the learning page, I think it's better to have a React page and try to polish a bit. If you want to style it, you can use CSS modules and things like that out of the box, or a plain CSS file. I think CSS module is a nice way to get started, because it doesn't involve a very complex setup. I think it's a nice default to style any React app. So, it's not too committed

JASON: Yeah, I feel really strongly that if you have not adopted a if you're not joining a team that's already adopted a styling format like if you join a team and everyone uses Tailwind, use it. But if you're starting a project from scratch, there's less and less reason to bring in a custom thing like SaaS or LESS when you can plug in modules, because they give you a wonderful like the CSS is scoped, which solves the complaint about vanilla CSS. It just works in so many modern frameworks where you import styles like this. You get to skip an abstraction, which I think is maybe my favorite part of it, where you're just writing this is valid CSS, put it anywhere, and it just works. And when you pull it in here, you just have to know the class names, and it just works. And that to me is such a powerful thing when you're jumping into a new tool, or you're trying to build something. One less thing on the pile that you have to keep in mind is slightly different from the web standard.

SEBASTIEN: I agree. Somehow the boring technology that's quite safe for any project. So, everyone is convinced that their way is better. Everyone is predictive. This one is maybe more verbose, but it gets things done. It works.

JASON: Yeah, it's really, really nice. All right, so, we created a plain markdown page. Let's talk about how you've got some cool stuff going on in this tutorial, where we've got these grouped sections in the side bar. Also looks like we can do something custom with the side bar, haven't looked in the side bar's JS yet. Let's talk about that, as I'm starting to get more advanced in my documentation, I want to add, you know, collections of docs, I want to add anything custom to docs, looks like we have some cool things here, like these buttons that show subpages and stuff. Yeah, let's dive in.

SEBASTIEN: So, we have a docs folder. You are currently browsing. Maybe you could take a look at this folder.

JASON: Okay, let's go over to... here's the basics, that's where we are now. So, we've got, I'm going to assume because of the underscores that this is kind of a magic file. Then we have markdown and MDX down here, which is nice. Okay, let's pop one of these open. The one we're looking at right now is create a page. Here's create a page.

SEBASTIEN: The idea is by default, Docusaurus will try to infer what you want to do from the folder structure, like most frameworks now do. We try to compute the URL of a document from its path on the file system, and you can customize some things with the front matter. This is the default behavior on the template, but you can also open the sidebars, the GS filer at the root of your site. And you can be explicit, for example, if you want to have control over the sidebar of your documentation, without being co related to the file system structure, you can also be very explicit and register each doc one by one to the sidebar. But I think it's great to be able to infer things from the file system structure. When you move one doc from one place to another, it adapts the documentation at the same time and put the folder in the right sidebar category.

JASON: Got it, okay. I'm going to try this. I'm going to make a collection called "how to boop." And we will make a little thing here. And then we'll make another one that says "boop it." And I'm going to make that MDX. And I think that's going to be good enough. So, I want this to show up. Look, it's already kind of doing what we want, which is pretty dope. So, we have the pieces. We don't have titles, so they are just using file names. They are not in the right order, but I saw in here that I can control the order. So, I'm going to grab this. And do one of these. One of these. So, we're getting closer now. How do I is this category JSON how I would customize this?

SEBASTIEN: The categories, yeah, for the categories like the folder. So, it's the folder. It configures the sidebar category, and you can also define more position for the top level position of the category. There are other things, for example, this is another thing that you can add.

JASON: Okay. Now we've got how to boop, right... oh, I should do the order so it actually shows up. So, here we go. So, that's one. Great. Oh, and then we've got this, this shows up here. I love that it shows this kind of auto generated thing. That's really nice. So, then going into one of my pieces here, I would like to let's see, step one, locate a snoot. Picks it up. That's so slick that it does that. Then we can go out here and do go to unsplash, get something that won't get me in trouble for using. One of these. And perfect. We're going to copy the image address. Probably look like this. Is it going to let me do the hot embed? It is. So, we've got our step one. Then we've got our step two. Now I made this MDX for a reason, because I want to have a little, like, try it.

SEBASTIEN: Yeah.

JASON: So, to do that, I'm going to need your help, because I've never added MDX to Docusaurus before. And this right now is not going to work, because this component doesn't exist.

SEBASTIEN: Yeah. Doesn't exist, but actually with MDX, you can eventually declare it in line. This is not a widely known MDX trick. But, for example, you can export it from this document, and it should be able to render.

JASON: I'm going to do one of these, and for now we'll just return view. Oh, look at that go. Okay. So, then we can do a little can I just is this going to work?

SEBASTIEN: Reformats a bit, because it doesn't like too much. But, yeah, maybe it will work. This is not something I would recommend for a real documentation site, but I think it should work here.

JASON: Cool, all right. Maybe we can do this and then you can help me refactor it into something that's a little less goofy. But we will start with boops greater than zero. Okay, get rid of this, close this. Over here we want a button, and the button will be an on click that will give us a set boops to be we'll just that will serve our purposes. Whoops, do it like that. I can't write code. There we go. We now have usable stuff, and we can even do like a button, unclick. Set boops to zero. And now we have reset. What did I miss? Boop it, reset it. Boop it, reset it. Now we have interactive docs, everybody, and that took me longer to write the JSS than to configure anything else, which is pretty wonderful stuff. Of course, this is this is not very sustainable, you know, we would make a huge mess if all of our docs were set up with in lined components and stuff like that. So, how would you recommend someone organizes their code for maybe a more production use case? Like I'm going to have some interactive code examples and stuff, where should I keep these?

SEBASTIEN: This really depends on how you do things, but I think the best way to get started is move this component to a separate file. There is a component that you can use, for example. And you can create a component there, then you can import it in the MDX file directly. This is where you maintain this component and use it in multiple documentations, multiple documents at once, and I think it's a bit cleaner, because you don't want to pollute the MDX files with too many React things.

JASON: Now, instead of this, I'm going to import "boop a snoot," quite possibly my best ever

SEBASTIEN: Here we have, if you want, you can start with @site/src/components. So, this way you can just have more stable things without a lot of dots everywhere. It depends what you prefer.

JASON: I broke it. Just like my did I miss a thing? Importing from React.

SEBASTIEN: React is not defined. You have to import React maybe.

JASON: Okay.

SEBASTIEN: Not in the MDX file, I think. It's in the over file. I think, yeah, you still have to import it. We don't have it imported for React yet.

JASON: Got it, got it. Okay. There we go. Now we've got a slightly less chaotic MDX, you know, interactive set of docs. That's so nice. It's so slick when you can just kind of throw these things together and not have to think about it. I will absolutely now I'm in my head thinking of all the times I've made my life harder by not just grabbing Docusaurus.

SEBASTIEN: Yeah, this is quite convenient. Actually, my newsletter is built on Docusaurus, because I didn't want to reinvent the wheel and create something from scratch while this was working fine.

JASON: Actually, that's This Week in React, right. This is a Docusaurus site?

SEBASTIEN: Yeah.

JASON: Oh, that's slick. Very cool, okay.

SEBASTIEN: This is not a regular Docusaurus site, because there are two blogs in the same site. And I don't have this is not the usual thing. So, this is just into Twitter.

JASON: Yeah, but this is clever, this is really good. This is a markdown page, and this is two separately configured blogs.

SEBASTIEN: Yeah, yeah, exactly.

JASON: Nice. I mean, it's a good idea, because you get all these things. Like search, you know, MDX configuration.

SEBASTIEN: Yeah, didn't want to spend time enlisting in recreating everything. You know the devil is in the details.

JASON: Yeah.

SEBASTIEN: You think it will be easy to implement your own blog, but then you want to add tags and pagination, and search, and localization, for example. For me, the very important things is menu is translated, so it's quite different from other newsletters that are only in English. I started it in French, I think localization is important. So, if you just switch the language, you have the content translated in two languages. And every week I send two emails to two different newsletter segments. So, I really needed this, and I didn't want to implement things with Gatsby or Next. Because I know it's complicated to implement this.

JASON: That's so cool. Yeah, this is just, you know, also the fact that you do this is a lot for every week in two languages. Holy crap.

SEBASTIEN: Yeah. This is completely I struggle a bit sometimes to find time to do everything.

JASON: Yeah, I can't imagine, yeah, I struggle to find enough time to do things like laundry. I don't know how people can doo oh, I'm going to write this 2,000 word blog post, and also I'm going to translate it into English from French. Holy crap. I'm lucky if I eat two meals a day.

SEBASTIEN: Translation is not the most complicated part of the newsletter.

JASON: Sure, sure.

SEBASTIEN: Everything adds up, and in the end everything takes time.

JASON: Uh huh. Yeah. So, I mean, this is slick. All right. So, if I want to I mean, incredible how fast that happened. I'm going to go and create a blog. I'm going to create a new blog, for today, it's now 2023, oh, my goodness. Today's the 19th. And we're going to say new boop docs. This is going to be a release note. Is there anything special about the blog post, or is it kind of the same game? I know there were a couple things that I saw like for the authors. I'm going to need to put in my name. I'm going to look at one of these to cheat. Oops, where did my blog post go? Here? And I can put this in. And we'll say host of Learn With Jason. And my URL can be links. And my image URL will be is this the one that I use now? There it is, cool. Okay, so I get that part. Which of these things are required, and which of these things are optional? I lost Sebastien there for a second. Let me get him back.

SEBASTIEN: I'm here.

JASON: All right. So, I have now I've put in my own author details. And then what I was looking at was whether or not of the rest of the pieces here, the slug, the title, and the tags, which things are optional and which things are required?

SEBASTIEN: I think nothing is required. Maybe just the title. If you have the date in the file name, I think it should be enough. If you don't provide a date, maybe we defer to the Git date. So, if you don't have a good date in Git, it's not a really great fallback, but at the same time, we need the date for the blog post to obey the blog post. Maybe you can try and create a blog post.

JASON: Okay, this, it automatically picked up the date, which is great. It automatically picked up the title, also great. It used my author info. What happens if I just get rid of this? Worked, doesn't fail at all. So, the only thing I have to do to blog is check out our new booping docs. Here we go. We've now built it. So, I can add one of these. The slug is here, kind of auto setup, but we can customize that. And then go back to the blog, because I just broke the URL. But now it's using our custom slug. We can have a title of so, if you override the title, it doesn't just change the sidebar. It overrides your H1. So, that is interesting. So, I can just then if I go over into here, I can copy the link address.

SEBASTIEN: The front matter slug is more for the metadata of the page. And if you want, for example, you can use the markdown title if you want, for example, to use inline code blocks and even maybe MDX inside it. So, you know, you can put React components inside the title, the metadata title of a page, but you can create an entire title if you want maybe for your blog post. I don't know who would use that, but it's possible to do, I think.

JASON: That's kind of fun. So, if I wanted to now I kind of want to try this. Hold on, if I do something... if I just do a

SEBASTIEN: No, this wasn't work.

JASON: No, that won't work.

SEBASTIEN: This is just a string. Normally, the markdown title inside the body, you can put bold and italic and things like that if you want.

JASON: Oh, I got ya, I got ya.

SEBASTIEN: Actually, I think it only works for docs. I'm not sure it works for blog. So, I think we just ignore it, because as we see, the front matter title overrides it, so I don't think it will do anything. If you do for blog, I think it works. I know there are some sites yeah.

JASON: Okay. That one doesn't work, but that's okay, because

SEBASTIEN: This doesn't work, because the blog is quite different from the docs. The blog, you see the content, we put in the middle of the title of your blog post. And the body, we put the author and metadata, so it has to be a string somehow, I think.

JASON: Yeah, that makes sense. So, if we wanted to play out here, we could theoretically make this into like this could be one of these. Then go over here, it works. It does look like it causes some problem for the sidebar.

SEBASTIEN: If you do that, we try to stringify it, because we have to put it in many other places where it can be a React component, so you have to put a title in a different matter to provide the string your version of it.

JASON: There's a lot of ways to do it, but this is the one I default to.

SEBASTIEN: Okay, I didn't know this one.

JASON: There we go. Now we've got strings work in the sidebar, and we've got a little Easter egg hidden on our...

SEBASTIEN: I could tell when you were doing that, find it useful.

JASON: Yeah. Maximum chaos is always a good choice when we're on Learn With Jason. So, let's see. What else do we need to do here? What else should we learn, what have we not covered yet?

SEBASTIEN: Maybe I can explain how the sidebar works.

JASON: Yeah.

SEBASTIEN: There is sidebar files. You will see that we use a single type called auto generated. So, this is what permits you to generate from the file system structure. We are quite flexible. It's possible, for example, to add another documentation. You can somehow, for example, generate from a separate folder if you want. If you don't want to generate from the old, you can use a name and generate from the folder. Somehow you can create explicit sidebar slices, where you define documents one by one that you reference by ID, so that you register them to the sidebar. Some folders where you want to use the file system conventions that we use by default, where you will just have to put subfolders instead of the name. And it will not generate from the root, but it will generate from the folder that you selected.

JASON: Gotcha. So, if I wanted to, let's say, pull in my custom page...

SEBASTIEN: Your custom page is a landing page, so it's not a doc. You have to put it in the docs folder if you want it to be a doc.

JASON: Oh, true. So, if I want it to be a doc, I would then say, like that's the blog, where am I going? I want to be in here. Go with, like, a custom thing, .MD. So, we get one of those. And now this is not showing up, right.

SEBASTIEN: It should.

JASON: Did something break? Oh, it didn't like something I did. I did something weird. Invalid sidebar file. These sidebar IDs do not exist. Yeah, I made it real mad when I did that. So, let's go with... I want

SEBASTIEN: You can add custom thing, I think.

JASON: Okay, are you still alive? Okay, we're good now. So, now it's double added, because it we're using the auto gen, but I'm also customizing it, and that's cool. And if I want to add something fully custom, can I because it looks like we've got a thing for categories.

SEBASTIEN: Yeah, you can create a category if you want and put the same documentation in it. The custom thing, you can put it in the items array. For example, it could be the

JASON: Okay. So, I can put any doc I want from the docs folder in here, but if I wanted to make a custom category, I would do a type category, and we would say label is my favorite, and then we would do items. And then in the items, we could do something like what?

SEBASTIEN: Can use the same document. Custom thing, how to boop. Whatever you want. It's not a problem to display twice the same document in the sidebar, but I don't know, I'm not sure you want to do this, but it's possible.

JASON: You could do pretty cool things here. If you had, for example, a really large doc site, one of the things that I've seen is you'll have sections on your features, right, so you've got 15 or more product features, major categories, each of which has their own docs and all those things. And those might include like a getting started quick start tutorial kind of thing. Maybe what you want to do is pull out those guides and do a guide section, so someone wants a rapid overview of the product can jump through each of those guides, right. So, there's lots of reasons why you would practically do this, despite me making a mess over here to prove the point. Definitely if you wanted to change it to be quick start guides, right, and we can pull in our basic quick start guides, put this up at the top, and that could be a whole thing, right. So, lots and lots of reasons why you might want to actually do something like this. It's not just me being silly. Ta da!

SEBASTIEN: Eventually, if you want to go further, if you have really large sites, what you can do also is maybe to separate your guides and your tutorials and things like that from your API reference, which is what we do on the Docusaurus site. The idea, for example, you don't want to have everything in the same sidebar, but maybe have separate sidebars for both different things. So, if you look at yeah, you can see it's not the same sidebar. So, in the sidebar.JS file, you can see you can register multiple sidebars. It's possible to have two sidebars for different parts of your sites.

JASON: Got it.

SEBASTIEN: You can create a second sidebar if you want and maybe add your custom thing in it, or another thing.

JASON: Yeah, so, we can do something like this. And maybe that's where our quick start lives, is down in here. Now, how would I add this somewhere?

SEBASTIEN: How would you add this somewhere? So, I think it should work if you do that. So, maybe you can try

JASON: Over here.

SEBASTIEN: There is just one problem, is that you have some documents that are in two sidebars now, because the auto generated generates from the root of your folder. So, all the documents in the docs folder are in the first sidebar. And you also registered some of them to the second one. So, there are documents that are in two sidebars. So, Docusaurus doesn't know which sidebar you want to display. So, this is a bit of a problem.

JASON: Oh. Okay. So, to fix that, can I so, let me propose this. We have the tutorial here, which has three top level things. We've got the intro, basics, and extras. If I want those to be on one sidebar, and then I want the how to boop and a custom thing to be on a second sidebar, I would not be able to use auto generated anymore. But can I specify the top level folder as opposed to so, we'll say

SEBASTIEN: Yeah, you can create folders, for example, one folder called guides and one subfolder called boop or something else. And use the auto generated sidebar for both folders. So, each sidebar will be auto generated from one subfolder. And, actually, you can auto generate it, just means you will read this folder and try to generate automatically the sidebar terms. But somehow you can use twice the same auto generated sidebar if you want. It will just duplicate everything. You can try maybe. Just copy this line and paste it just under. And you will understand how it works. Somehow it concatenates the sidebar slices together. If you want, you can change the name from which it's generated, and you can see it generates something like that. So, the idea you have some low level primitives that limits the way you compose the way you want to organize your site. And you can be explicit for some folders and use auto generated for the subfolders that where this makes sense.

JASON: Got it. So, how would I put looking here where I've got the intro, the basics, the extras, I want to make two sidebars. One that is this, and one that would be the how to boop and hello. I want to split these into two sidebars and when I'm in these docs I want this to show up, any of these I want this to show up.

SEBASTIEN: What you can do is maybe create one tutorial subfolder in the docs and move everything inside.

JASON: I would do that like this?

SEBASTIEN: No, you use your file system. Just create a folder inside the docs folder. You create a tutorial subfolder, you move the other folders inside it. And you create a boop subfolder and move the other things inside it.

JASON: Okay.

SEBASTIEN: So, now you should have just two root folders, and for each sidebar you will auto generate it from the subfolder instead of from the root.

JASON: I think I need to stop and restart, because I changed a bunch of folder locations.

SEBASTIEN: I think it's the idea of your document, it's something I don't really like in Docusaurus, is that when you move a file around, the ID changes, because it takes the folder as a prefix. So, you have to use boop/how to boop/ you have to add the "boop slash" in the side bar, because you have some references.

JASON: Okay. So, I'm here. Couldn't find any doc with ID intro.

SEBASTIEN: Yeah, so, this is this is not something that I'm proud of. You have to edit the configuration file of Docusaurus. Because your nav bar referenced a document that just changed IDs. So, you have to add maybe boop tutorial intro, and I think it should work now.

JASON: Okay, go over here.

SEBASTIEN: It's not very good, but...

JASON: Got it, got it. Okay, so, that works. And if I go into boops wait, is it just boop? It is just boop. So, we'll go into just plain old boop. Do I need to set a

SEBASTIEN: You can maybe create an index.MD file, but otherwise you will have to boop/how to boop.

JASON: Okay, that worked, but it's missing my sidebar, and that sidebar needs to be declared in here. Right? And I can do that by just saying... boop, give this the boop sidebar.

SEBASTIEN: Yep, right.

JASON: And now we've got it. Got it, okay. That's slick. You know, it takes a bit of doing, but nothing that we can't handle. And if I go in here and what was the what was the position, sidebar position one? Now? We have the booping thing. If I come into the nav, I can add this. So, we'll go to boop, index. I guess I don't need that. I can just do this?

SEBASTIEN: No, I think you do I'm not sure. I don't remember all the conventions that we have. But I think you need it, yeah.

JASON: There we go. Now we got a new docs section that has its own custom sidebar. Got this one. This is slick. It's great. I mean, this is everything I could want. It was way easier to figure out that config change than it would have been for me to build this from scratch, right. Oh, there is a question in the chat. Does Docusaurus 2.0 have is it using Vite?

SEBASTIEN: No, it's using Webpack. It's a bit complicated to change that, because we have a plug in system and have some plug ins that are relying on Webpack. So, if we do the changes, it would be complicated for the community, because they'll have to update all the plug ins. So, this is not something that we did so far. I don't know what will be done for the community. I think it's possible that we will do it. But, at the same time, there is other things that are coming. I'd like to take the time to think more about it. To see which is the best one.

JASON: Okay. So, I'm going to push this. And then the last thing to do, and we've got just a couple seconds left to do this before I have to wrap us up. If I want to deploy this, can I do anything special, or can I go to Netlify and say deploy this site?

SEBASTIEN: No, you can go to Netlify and deploy, I think.

JASON: Okay, import an existing project, go to GitHub. Go. And... go to my Learn With Jason here. Search for Docusaurus. Grab this one. Just going to hit the deploy button and we'll see how it goes.

SEBASTIEN: It should be fine, I think.

JASON: Then I think the other thing I want to do while we're waiting for that is I'm going to change the site name while I'm remembering to Docusaurus 2. Okay. And we can go back to our deploys. It's building, doing all the things that we want it to do. And while we're waiting for that to build, I'm going to ask you, where else should somebody go if they want to go further with Docusaurus?

SEBASTIEN: I think you can just read the documentation and maybe you take the tutorial that is in the initial template. There are some things that we didn't cover, like versioning and internationalization, if you want to understand how this works. And if you want to get some help, we have a very active Discord server, where people are very helpful. If you are locked on a specific problem, you can always ask there if you need help, and someone will likely answer. Otherwise, you can ask your question on GitHub, if nobody's able to answer on Discord, because, unfortunately, I don't have a lot of time to participate there. So, I try to delegate a bit for the community. And if nobody's able to answer, I try to help the users on GitHub.

JASON: Where does somebody go to get into the Discord?

SEBASTIEN: I think, yeah, there should be a link in the footer also.

JASON: Here. All right. So, head over to the Discord, get into the GitHub, and get out there and build some great stuff. Let's go see if my site built.

SEBASTIEN: Oh, no.

JASON: We found broken links.

SEBASTIEN: Yeah.

JASON: You know why we found broken links? My blog links to the docs, and I moved we moved all those. So, that's okay. That's an expected bug. I'll fix that after we get offline, so that the blog will deploy. But, I mean, this is actually great, because I would have never known that, and we would have just had broken links in the site. So, that's a really helpful feature. Wonderful. All right, so, Sebastien, anywhere else that people should go if they want to keep up with you? I'm going to drop another link to your Twitter here.

SEBASTIEN: Yeah, I think Twitter is fine, or you can subscribe to my newsletter if you are into React. Also, on Docusaurus. On the repo.

JASON: Yep, excellent. All right, y'all. Well, with that, we are going to call this one, I think, a success, despite my technical issues with the overlays. This episode, like every episode, has been live captioned. Thank you so much to White Coat Captioning and Ashly who's been doing that all day. That's made possible through the support of our sponsors, Netlify, Nx, New Relic, Pluralsight, all kicking in to make this show more accessible to more people, which I very, very much appreciate. We got a lot of good stuff coming up on the show. I am streaming solo on Tuesdays now, so make sure you tune into that, Tuesdays at 9:00 a.m. Pacific. And then on Thursday we're going to have Jessica Sachs coming on to teach us about Faker.js and component driven dev. All sorts of good things on the schedule. Make sure you like, subscribe, whatever it is that you want to do. There's a newsletter up here on this tips and insights if you want to get it that way. So many ways that you can be involved with Learn With Jason. Make sure you don't miss an episode, because we've got a whole lot of good stuff coming up. Sebastien, thank you again for taking time out today and teaching us. Chat, as always, thank you for hanging out. We're going to go find somebody to raid, and we'll see you all next time.

SEBASTIEN: Thank you.