Paul: Hi there, and welcome to PodRocket. Today, we're very fortunate to have Sebastien Lorber on with us. Welcome to the podcast, Sebastien. Sebastien Lorber: Thank you, Paul. Paul: So Sebastien, you've been a jack of all trades for most of your life. Before this podcast, I was saying, "Can I introduce you in the context of React?" because you've been the CTO, you've been creating this Docusaurus website and framework that we're going to be talking about today to produce beautiful documentation. But it sounds like you've focused a lot in the React space recently, and in React Native, right? Sebastien Lorber: Yeah, right. I started my career as a backend developer using Java and Scala and things like that. I didn't really like JavaScript in the beginning, but maybe something like eight years ago when there was the ES6 version of JavaScript being standardized, I started to like it. As I was a functional programmer, I quickly became attracted to React, because someone in the ClojureScript community, I think the creator of ClojureScript demonstrated that React was a really great framework for functional programmers. As you know, the model of UI is a function of the state. So this got me into React, and since then, I became a front-end developer and I almost don't do backend development anymore now. Paul: Complete shift, right? You went from one end of the spectrum to the other. Sebastien Lorber: Yeah. If you asked me maybe 10 years ago, I wouldn't have bet that I would become a front-end developer, because I really disliked JavaScript, actually. Paul: I think that's a pretty common reaction that a lot of backend-heavy people have when they see JavaScript. The paradigms and disorganization can throw a lot of people for a loop at first until you learn how to tackle the beast. But yeah, today we're going to talk about Docusaurus, which I'm very excited about personally to pick your brain, because I've probably used Docusaurus at every single company I've worked at, up until today. Sebastien Lorber: Yeah. Paul: And it's been an immense help, not only to our teams, but to people who are outside of our teams, because it's easy to navigate and easy to change. Before we get too into the weeds, Docusaurus is, in my eyes, it's a documentation and a framework to write really approachable pages that look really nice really quickly. I would love for you to define it, though, from your perspective as the creator. Sebastien Lorber: First, I'm not the creator of Docusaurus. It's a Meta opensource project somehow with Facebook. It was started maybe five years ago, when Meta had a lot of opensource projects and they wanted to document all of them. They started to copy/paste a [inaudible 00:03:23] template over and over again, but it was not very scalable, so they decided to create a tool that solved their own pain so that they can just focus on the content have a beautiful-looking documentation website. All the other documentation websites would be able to use the same stack that would stay in sync over time. You just have to upgrade the endgame package version and then all your documentations are upgraded. So the idea of Docusaurus initially is that you really want to focus on your content. You just write Markdown files and then there is a tool on top of that, that will take all your files and build a beautiful static website. So the first version of Docusaurus 1 delivered on that premise, and you have probably seen some sites using Docusaurus 1. There are still a few sites using Docusaurus 1 today, for example, in the JS Ecosystem, there is Babel and [inaudible], for example, which are still using the first version. But the thing is the first version was not very customizable so the version 2 project started in maybe 2018, and it was a long road because we work in alphas and betas for four years and we just released the second version as stable. But, the idea of this second version is that it is much more modular and you can really customize the UI and you can create [inaudible] and things like that so. The first version of Docusaurus was focus on your content, you create Markdown files and you have a beautiful website. The second version of Docusaurus is the same but instead you can really customize a lot of things. You can really build a custom documentation and if you compare the documentation version 1 sites with version 2, you can see that most version 1 sites will all look quite the same. Maybe the colors change a bit but if you look at the Docusaurus 2 sites, you will see that they are quite different, at least if the authors are willing to customize them. You can create very different experiences. Paul: Enjoying the podcast? Consider hitting that follow button for more great episodes. What's one experience that people can create, namely with the second version of Docusaurus, that stands out to as unique in your mind? Sebastien Lorber: Actually, we market Docusaurus as a documentation static site generator, but in practice it's more than that. It's more like a generic framework like Gatsby, on which we provide plug-ins that are for concentric websites. So, for example, we have a docs plug-in, we have a page plug-in for the landing pages and we have a blog package for creating a blog. But in the end, you are free to create your own plug-in. For example, if you want to create a digital garden or a second brain or whatever you want, you should be able to do this with Docusaurus because it's a flexible framework like Gatsby and XGS. We don't support server side rendering. We are limited to static site generation. But in the end, you can build your own plug-in to read the Markdown files and the file system and decide what to do with them and maybe you don't even have to create a plug-in. Within Markdown files you can also try to integrate with a CMS or generate documentation from an open API chat scheme or something like that so you have an API documentation or [inaudible] documentation. Paul: It's almost like I feel as if I'm getting the plugable widgets of Notion but I have complete control. Something like plugging in to a CMS for my documentation is something that I would turn to Notion for, historically because you can plug in to the database. But here you're saying that we can write plug-ins and dynamically have them update when the user visits. Sebastien Lorber: I don't use Notion much so I am not sure exactly to understand what you mean. Paul: Okay. Sebastien Lorber: But, yeah really you can create your own custom plug-ins and there are users that are creating quite interesting plug-ins. For example, there is a plug-in to integrate Redoc. Redoc is a tool to integrate an open API client in your documentation. So you can keep the Docusaurus layout for example, but have a real, functioning API client inside your documentation that users can interact with. There are also users that are documenting, for example, if you have a textbook project, you can use, I think it's called TypeDoc, something like that and you can for example, generate documentation based on textbook type definitions. And then some developers are creating plug-ins to generate all these documentation inside the Docusaurus site. So you have the Docusaurus layout but then you have the TypeDoc documentation inside Docusaurus and if you want you can customize the Docusaurus layout so in the end you are free to customize the content and also the main layout that we provide for free. You are not limited to what we build, you can actually provide your own layout if you want. Paul: Would you almost say this is a highly opinionated web framework? A static web framework that is just highly geared towards this [inaudible 00:09:18]? Sebastien Lorber: Yeah, this is exactly this. This is Gatsby but we have 3 or 4 official plug-ins and we don't have the GraphQL data layer because we thought it was a bit complex and I think the community agrees that we don't necessarily want a GraphQL data layer in Docusaurus because it complicates a bit things. But at the same time, Gatsby is able to do something that we currently don't do. For example, if you want to display the top 3 blog posts of your Docusaurus blog on the landing page, currently it's not automated. You can't query your blog data from your own page and get this data so easily. So, we will probably have to create a data layer at some point. But for now, we don't have it. Paul: But, like you said, just recently, if you really wanted to you could maybe have some plug-in that reads the Markdown file and does some crazy stuff. If you really wanted to, right? Sebastien Lorber: Mm-hmm(affirmative). Paul: Okay. Sebastien Lorber: The idea is that we build most of the most popular things that the community needs so that you don't really have to build these things. But in the end, if you are a power user you can create integrations. For example, it's not possible for us to provide an integration with everything so the plug-in system permits you to fill the gaps and build your own niche things if you want. Even if you have some proprietary CMS or something like that. You can try to integrate with it with your own code. Paul: So, all these features sound really great, something that I would want if I was maybe making an API or starting a new product at a company. But if you were maybe on a personal project, is Docusaurus, in your eyes, something that is low hanging? It's easy enough that no matter what project you're working on, it might be a good idea to start with that. Or it's maybe that once you're off of one README file, sure go make it. Sebastien Lorber: Actually the variety is very low, it's a bit of the point. You can just, for example, have one Markdown file on which you put everything if you want. But I think it's better to add it on Docusaurus because you can have syntax highlighting on blogs and a few interesting features like that and the layout around your content that you don't have on Github, for example. So, even if you just have one Markdown file, you should be able to display it inside Docusaurus. Maybe in less than a few minutes you will get it working. The thing is, for some people it's not so easy because they are not front-end developers. In the end you have to install JS, an MPM and things like that and be able to modify the config file that is currently in JS. So, if you are not able to configure a config file in JS maybe [inaudible] there are other projects like MkDocs that are [inaudible] and using YAML config file. Some people would find this simpler to get started because if you are a Beta developer, of course you are more used to using Beta packages and things like that. But otherwise, if you are a front-end developer it should be very straight-forward to start. And I think it's perfectly fine to start with Docusaurus even if you have 2 or 3 pages of documentation. You just have to put the Markdown files in a folder and then everything will work out of the box. For example, if there are 3 files in your docs folder, you will have a sidebar with the 3 documentations being available there. And if you want to change the order of the items in the sidebar, you will just have to add some front material which is the metadata, the top of the Markdown file. And you will be able to change the position of the items this way. We offer more advanced things but this is the easiest way to get started and also we see a lot of little opensource projects that, I mean, the author want the documentation website but he's not willing to create something custom from scratch and they heard of Docusaurus and it goes very fast to get the documentation online. And also, we see a lot of developers using Docusaurus as a portfolio because we have a blog [inaudible 00:13:50]. You can create a landing page and a blog quite easily and have quite interesting features. For example, if you want to have a guest on your blog post you can co-author the blog post with another person. You can have- Paul: Oh wow. Sebastien Lorber: Yeah, if you look, for example at the React Native website, they requested- Paul: Which website, one more time? Sebastien Lorber: The React Native website. Paul: React Native, okay thank you. Sebastien Lorber: Yeah, the React Native website is using Docusaurus too because there a lot of Meta developers working on React Native, they wanted that when they release a major update on the blog post they can add multiple authors because it's normal. But everyone is credited for the work that they did. So, we added this feature which that means to have multiple authors on a single blog post. And there are multiple things, for example you have a RSS feed for free, you have a site map and good SEO and things like that. So, if you are a developer looking for a blog, you can get started with Docusaurus very easily. And you will have the ability to also create your landing page like your "About" page or your homepage and things like that. It's quite easy to get started. Even landing pages can be created with Markdowns, so you just have a page folder and you just have to create some files there and they will be available automatically. Paul: That's very exciting for me because I feel like in all the times I have used Docusaurus, it always has a Markdown folder and not as a website. I guess, my entire opinion of Docusaurus has changed and maybe some other people feel the same way. It's a documentation website, that's what it has always felt like to me. But with Docusaurus 2 it's a Google Docs, essentially. It's any document, you can make whatever you want here and more. Sebastien Lorber: This is something to publish content online based on Markdown mostly. But you can also create a React landing page if you want [inaudible]. And yeah we have, for example, a showcase where we have maybe 300 sites now and there are maybe 20 exactly examples of developers creating their portfolio with Docusaurus. And I think it's quite interesting because they all look quite different. You can see that it's easy to get started but you can still create something that is custom enough so that your portfolio doesn't look like the one of another developer. Emily: It's Emily again, producer for PodRocket and I want to talk to you. Yeah, you, the person who's listening but won't stop talking about your new favorite framework to your friends. Even though they don't want to hear about it anymore. Well, I do want to hear about it because you're really important to us as a listener. So, what do you think of PodRocket? What do you like best? What do you absolutely hate? What's the one thing in the entire world that you want to hear about? Edge computing? Weird little component libraries? How to become a productive developer when you're WiFi is out? I don't know, and that's the point. If you get in contact with us, you can rant about how we haven't had your favorite dev advocate on or tell us we're doing great, whatever. And if you do we'll give you $25 gift card. That's pretty sweet, right? So, reach out to us, links are in the description. $25 gift card. Paul: So, you're saying it's pretty easy to get started even if you just have one Markdown file. If somebody is listening to us talk right now and they've never used Docusaurus, where do they go and maybe what are the first few steps? Sebastien Lorber: I think a good first step is to go to Docusaurus.new, we have a domain where you go to Docusaurus, that new, it opens a sandbox. You have the choice between CodeSandbox and Stackblitz which are online playgrounds. And then the default Docusaurus template will start for you and you will be able to play. For example, you can create a Markdown file in the docs folder and you will see how Docusaurus indulge this. And the new doc will automatically appear there in the sidebar and then you can just write the Markdown content and the content with auto-reload the new browser [inaudible]. Paul: So that's 3 steps, there you go. That's it. Sebastien Lorber: Yeah. I took care of making the tutorial very simple so normally if you tag me in Instagram and I understand the value proposition of Docusaurus. So, it's a step by step tutorial and if you open the playground with Docusaurus new you will actually have the tutorial embedded inside the playground because the playground displays the tutorial. So, you just have to follow what you see on the screen and in 5 minutes you understand how it works. Paul: I mean that's the most promising intro I've heard for a while in an open source framework. It's the duty now of everybody listening, you should go check it out and see what's happening over there. If we don't want to use Docusaurus, maybe people are interested in contributing and learning a little bit more about the direction. What's next in your mind, is the next mountain to climb for Docusaurus? Sebastien Lorber: I think there are things that we don't do so well currently. As we are a small team, it's hard to keep up with all the innovations in the JavaScript Ecosystem. For example, you see that there are funded companies that work on the next GIS Remix and Gatsby and things like that. Docusaurus is much smaller but it's quite attractive. So, there are lot of users already using Docusaurus today. But we are a small team and it's hard to catch up with these large teams on things like performance and using rust tooling to improve the build times and things like that. So, for now Docusaurus is probably the most featured created documentation website and people are satisfied but we are not so great on the build times and things like that. It's not the fastest out there and I think we should try to improve that over time. Paul: So, a lot of low-hanging fruit for people who are familiar with those areas who can maybe come in and work on it. Are there open issues right now? Sebastien Lorber: These things are not so easy so I don't think if you are a new external contributor it's what you should work on but yeah we always have some issues that can we get delegated for contributors that are looking to contribute. Some architectural design decision and things like that, it's hard to delegate because it will have an impact for the following year. So, I prefer to work on this myself. Paul: Gotcha, okay. So, in terms of the product, not the build times and things like this, do you think the product suite is finalized for what Docusaurus is offering or are you still brainstorming? Sebastien Lorber: I think we are happy with the value proposition and the induction of Docusaurus 2 right now. But we still see some limits. For example, if you have a CMS we don't provide any easy way to integrate with a CMS. So, the most dreadful way to integrate with a CMS would be to download Markdown files from your CMS, write them to the file system and then have Docusaurus read the files on the file system. This is not ideal because you have to create intermediate Markdown files and things like that. So, we are not so great with the CMS integration side for now. Unless you are using git-based CMS because the files will be on Git. So, there is one big idea that we would like to do is, as we can't compete with the other static site generators that have large teams working on the infrastructure, we would like to see if it's possible for example, to build Docusaurus with the same features but on top of an existing static site generator so that we can leverage the work of others and maybe improve the build times and things like that. It's possible that we will try to make Docusaurus static site generator agnostic so that maybe we can run Docusaurus on top of JS, maybe on top of Remix, maybe on top of Gatsby and creating some kind of portable documentation tool where we would just focus on creating the plug-ins and the sensible defaults that makes it easy to create a documentation website. But maybe, a bit less focused on the infrastructure because it takes a lot of time and we are too small to catch up with the large teams. Paul: Why re-invent the wheel if they have a whole paid team? Sebastien Lorber: Yeah. Paul: Making the wheel. Yeah, and I guess, there's more features we could get in to of Docusaurus. I mean there's things that we didn't really touch on like search, I mean that's big. Usually servers are involved in a search and the fact that it's on a static site is kind of cool. But, I think some people listening that might be saying okay I'm on Docusaurus 1 because that's what we've used forever and I want these things, how do we come to version 2? Is that a complex process and- Sebastien Lorber: Actually it really depends on how much you customized your documentation website. We have a migration team so that you can quite easily upgrade your config and a few things. But it's hard to automate the full process. But generally you don't have to update a lot of things. Unless you have customized a lot your version 1 site with a lot of CSS you will have to find a way to reproduce your old design if you want to keep it as it was before, which is maybe not something that you want. It really depends on what your goal. But no, I think the version 1 websites can migrate to version 2 quite easily. There are some challenges, for example, if the documentation was versioned with a lot of versions or if you have internationalization. For example, if you supported multiple languages, there are some challenges if you have a complex site like this. For example, I did the migration from version 1 to version 2 of two important websites at Meta, there was Jest which was version 1. It was translated so there are a lot of languages that I had to ensure that we don't lose the translations during this process. And the React Native website had a lot of versions. So, we were able to migrate these two sites from version 1 to version 2 and documented the process so that others can do the same. Paul: Okay, so it really depends case-to-case? But the config for the most part is automatic because it's just a config? Okay, okay. Sebastien Lorber: Yeah. Paul: Gotcha. Sebastien Lorber: If you don't have versions and translations then it should be quite easy. Paul: Actually that's another thing, this was going to pass my mind and I'm glad you just brought up that word, which is versions. And this is something that Docusaurus has somewhat of a helping hand with. So, people should use version in their documentation, right? That's kind of the message going forward here. How does Docusaurus help people put that forward? Sebastien Lorber: I think Docusaurus has a different approach to what people are used to because I think most people are used to having one git branch per version, for example if you have a project in version 1 and version 2, you will have one git branch for each version. Docusaurus will handle things differently. Your documentation for both versions will be on the same branch, by default. You can still decide if you want to have multiple documentation branches, if you want. But by default, you will have, for example, the main git branch will hold the documentation for version 1 and version 2 at the same time and when you work on version 3, for example, if you are ready to release it, you will publish the major version of version 3 and at the time we provide a key command that you will run which will create a snapshot of your current documentation. We call this the current documentation, which is the one you are editing continuously. And it will create a snapshot of this current documentation and archive it in a version 3 folder. In which you will be able to change things that are only relevant for version 3. For example, if you start to work on version 4 you will be able to edit the version 4 documentation. That is the [inaudible] version. And you will have the folder version 3 for the folder version 3 documentation. So, you will have two documentation sets to maintain on the same branch. I think it's interesting because for example, if you have a feature that you merge on your main branch for example, you will be able to create the documentation and to back-port the documentation on all the documentation versions with a single pull request. For example, if you want to implement something in version 3 but you want to back-port the feature in version 2 and version 1, you will be able to submit just one pull request and update the 3 version documentations at the same time. So, I think it has some advantage for back-porting things. Also, Docusaurus will take all your versions and build a single page application for all the versions. So, for example, if you look at the Docusaurus website, by default there is often a dropdown at the top to select the version you want to [inaudible] the project in. And if you switch from one version to another you are still on the same single page application. Not going to another domain or something like that and there is no full page reload. So, this allows us to make the switch from one version to another quite fast and also, to build some features like [inaudible] for example, if you're on version 2 and the latest version is version 3, you will be able to show a banner that says you are not on the latest version, you should try to browse the version 3 version or something like that because you want people to make sure that they are browsing the documentation of the latest version that you published. Paul: Right, I'm definitely familiar with the documentation version dropdown on these things. I remember seeing that. So, Sebastien, if people want to find you and learn more about what you're working on with Docusaurus, where can they follow you? Sebastien Lorber: They can follow me on Twitter I am @SebastienLorber and also I have a weekly React newsletter called "This Week in React". This is where I generally share a personal update on Docusaurus or anything significant that I want to tell the world. Paul: And where is that newsletter distributed? Sebastien Lorber: ThisWeekinReact.com. It's a curation newsletter, so I send a weekly email with the best news of the React ecosystem. Paul: That sounds pretty good. Okay, awesome. So, okay we got the Twitter, we got the newsletter and if people want to check out Docusaurus is Docusaurus.new is that the website you mentioned earlier? Sebastien Lorber: No, it's Docusaurus.io. Docusaurus.io is the playground that you can get started in 5 minutes online without installing anything. Paul: And the main website is dot I-O? Sebastien Lorber: Dot I-O yeah. Paul: Okay, awesome. Well, Sebastien thank you for your time, coming on. Hopefully some people will try out Docusaurus 2 and then maybe get interested and help support some of these upcoming features and improvements that you're talking about. But yeah, thank you for your time. Sebastien Lorber: Thank you for having me. Paul: Thanks for sharing about the newsletter too. I'm sure some people would like to subscribe to this. Sebastien Lorber: Yeah, I hope. Paul: All right, well see you around. Sebastien Lorber: Thank you, bye. Emily: Hey, this is Emily, one of the producers for PodRocket. I'm so glad you're enjoying this episode. You probably hear this from lots of other podcasts but we really do appreciate our listeners. Without you there would be no podcast. And because of that, it would really help if you could follow us on Apple Podcasts so we can continue to bring you conversations with great devs like Evan You and Rich Harris. In return, we'll send you some awesome PodRocket stickers. So, check out the show notes on this episode and follow the link to claim your stickers as a small thanks for following us on Apple Podcasts.