Docusaurus with Sebastien Lorber

Episode Description

Sebastien Lorber discusses his journey from hacking and Java development to maintaining Docusaurus 2, Facebook's open-source documentation site generator.

Episode Summary

In this episode, Sebastien Lorber, a freelance developer working with Facebook on Docusaurus, shares his path from teenage Counter-Strike scripting and early internet hacking to becoming a key maintainer of one of the most widely used documentation tools in open source. The conversation traces his programming origins through Java and Scala before arriving at React in its earliest days, where he built time-travel debugging independently before Redux existed. Sebastien explains how Docusaurus 1 was born from Facebook's habit of copy-pasting documentation sites across open source projects, and how version 2 represents a fundamental shift by hydrating React on the client to create a true single-page application. The discussion covers practical challenges like MDX compatibility issues, the swizzling-based theming system and its maintenance difficulties, versioning trade-offs for large sites, and the friction non-developers face when contributing documentation through GitHub. Sebastien also touches on upcoming plans including a long-awaited beta release, potential Tailwind theme support, CMS integration possibilities through a createPage API, and his work migrating the Jest site to test the internationalization feature. The episode offers both a rare look at early React community history and a grounded view of the trade-offs involved in building developer tooling at scale.

Chapters

00:00:00 - Introductions and Early Programming Origins

The episode opens with Sebastien Lorber introducing himself as a freelancer working with Facebook on Docusaurus, a documentation-focused static site generator. He explains that while he's not a Facebook employee, he's been contributing to the project for over a year and previously did React ecosystem consulting.

Sebastien shares how he first got into computers at age 13 through gaming, creating macros for Counter-Strike movements, and eventually getting pulled into the world of IRC file sharing and amateur server exploitation. His early experiences as a self-described "script kiddy" breaking into university servers to host files gave him a foundation in computing well before formal education. Anthony draws a parallel to phone phreaking history and the origins of Apple, connecting Sebastien's story to a broader tradition of hackers-turned-builders.

00:05:17 - From Java and Scala to Early React Adoption

Sebastien describes his formal education in engineering school focused on Java, followed by several years as a Java developer working with Spring and Hibernate in French enterprises. A growing interest in functional programming led him to Scala and a CTO role at a startup, where he reluctantly encountered JavaScript while helping his team debug a troubled Backbone.js frontend.

By 2014 he had become an early React adopter, drawn to it through his functional programming background. He recounts how the early React community—including figures like David Nolen with ClojureScript—was largely composed of functional programming enthusiasts experimenting with state management before Redux existed. Sebastien reveals he built time-travel debugging a year before Redux launched but lacked the marketing and documentation skills to gain adoption, a detail that connects ironically to his current documentation-focused work.

00:10:39 - React's Hidden History and Forgotten Pioneers

The hosts and Sebastien reflect on how React's origin story remains surprisingly obscure despite its dominance in web development. Few developers know Jordan Walke created it, and early evangelists like Pete Hunt have largely faded from community memory despite playing crucial roles in React's initial adoption.

Christopher raises the broader point that React seemed to appear fully formed one day from Facebook, with most developers never questioning its creation story. The conversation touches on the pre-React landscape of AngularJS, Backbone, Ember, Browserify, and RequireJS, setting the stage for understanding why Docusaurus emerged from the same ecosystem that produced React itself.

00:12:46 - Docusaurus 1: Origins and Architecture

Sebastien explains that Docusaurus 1 was created roughly four years prior when Facebook noticed they were repeatedly copy-pasting documentation site code across their many open source projects. The tool was built to standardize this process, even at the cost of limited customization. Notably, version 1 used React only on the server for rendering static HTML, never shipping React to the browser—making it architecturally closer to Jekyll than to modern Jamstack frameworks like Gatsby or Next.js.

This meant developers couldn't use React state in their components and had to rely on vanilla JavaScript or jQuery for any client-side interactivity. Sites like Babel and Prettier still run on version 1. The conversation highlights how this server-only approach, while simple, created a ceiling for what documentation sites could achieve in terms of user experience and interactive content.

00:15:53 - Docusaurus 2: SPA Architecture and Performance Trade-offs

The discussion shifts to what motivated Docusaurus 2, which fundamentally changed the architecture by hydrating React on the client to create a true single-page application. Sebastien explains how this enables features like link prefetching on hover, preserved scroll position, and elimination of blank screens during navigation—improvements inspired by frameworks like Gatsby.

He raises a provocative point about performance measurement: Docusaurus 2 may actually score lower on Lighthouse than version 1 despite providing a better real-world user experience, because monitoring tools primarily measure initial page load rather than overall navigation quality. The conversation then covers Sebastien's own history with the project—he joined only a year prior, replacing a team member who passed away from cancer, and works alongside just two Facebook employees and various community contributors.

00:21:08 - Alpha to Beta, MDX Support, and Versioning

Sebastien clarifies that Docusaurus 2 has been in alpha for two years because the team wanted feature parity with version 1 before declaring beta, with internationalization being the final missing piece. He notes the beta release is imminent, pending just one pull request and a blog post. The conversation then explores MDX support, which is both a strength and a pain point—developers love embedding React components in docs, but non-developer users hit confusing compilation errors when standard Markdown isn't fully compatible with the MDX parser.

The built-in versioning system is also discussed, with Sebastien explaining that it builds all documentation versions into a single application. While convenient for smaller sites with a version-switching dropdown, this approach creates scalability problems for large documentation sets, where Git branch-based deployment of individual versions may be more practical.

00:25:01 - Theming, Plugins, and the CMS Integration Question

Sebastien describes the swizzling system for theme customization, which mirrors Gatsby's shadowing approach by letting users override individual components. While powerful, this creates an implicit and fragile API surface where internal theme changes can break user customizations. He envisions using TypeScript to make the theming contract more explicit and mentions plans for three officially supported themes: classic, Bootstrap, and Tailwind.

The conversation broadens to discuss Docusaurus's potential as a more general-purpose tool. Christopher suggests a createPage API could open up CMS integration and non-developer use cases, though Sebastien clarifies that unlike Gatsby, Docusaurus won't aim to build a massive plugin ecosystem. He acknowledges the real friction non-developers face with Markdown and GitHub pull requests, and highlights promising solutions like StackBlitz's browser-based Node.js polyfill that could let users edit documentation without local development environments.

00:33:46 - API Documentation, Jest Migration, and Search

The final segment covers auto-generated API documentation, with Sebastien noting that tools like Redoc and TypeScript-based generators handle only the API reference portion of documentation. Anthony clarifies the relationship between Swagger and OpenAPI before asking about the Jest migration from Docusaurus 1 to 2, which Sebastien reveals he initiated himself as a test case for the internationalization feature. The multi-month migration involved working through numerous issues with the Crowdin translation platform.

The episode closes with a brief discussion of Algolia-powered search, which Sebastien explains is offered free to open source projects, creating mutual benefit through visibility and community support. He notes the architecture is designed to allow alternative search engine plugins, though no competitors have pursued integration. The hosts thank Sebastien for his contributions to both Docusaurus and the Redwood framework's multilingual documentation efforts.

Transcript

00:00:00 - Anthony Campolo

Could you just let us know how to pronounce your name?

00:00:04 - Sebastien Lorber

Sebastien Lorber.

00:00:06 - Anthony Campolo

Lorber. Okay. I was curious if it was going to be like sorbet, light tea. Right? Sebastien, welcome to my podcast.

00:00:24 - Sebastien Lorber

Hello, everyone. Thank you for having me.

00:00:27 - Anthony Campolo

Why don't you go ahead and let our listeners know who you are, what you do, and what kind of projects you work on?

00:00:33 - Sebastien Lorber

So I'm Sebastien. I'm currently working with Facebook on Docusaurus, which is a static site generator for documentation. I'm a freelancer, so I'm not a Facebook employee, and I've been doing this for over a year now.

Previously, I was mostly doing freelance consulting in the React ecosystem. So, mostly consulting, and sometimes long-term missions with implementation work.

00:01:01 - Anthony Campolo

You also helped out with getting the Redwood documentation to be multilingual. We talked about this with Clare on a recent episode, so we really appreciate all that help that you gave us, and that's partly what got us connected.

I'm a big fan of trying to make documentation available to as many people as possible, so I was really happy to have gotten the opportunity to work on that. And I'm really happy to have you here so we can get more into your background and how you got into what you're doing.

So I'd be curious: how did you first get into programming, like your first programming language, where you studied, or if you studied any of that kind of stuff? We like getting that kind of background from our guests.

00:01:48 - Sebastien Lorber

Yeah. I think it's the first time someone asked me, and I have a lot to say about this. It could last for hours, I think.

I got into programming when I was 13 or something like that. I was playing Counter-Strike and things like that. The first things I did were mostly to script some actions. For example, there was a special move in this game called the bunny hop. It was a sequence of keys that you had to press in the correct order with good timing. And somehow I created a macro to press just one key and do all the actions in the right order for me so that I could do the complex movement more easily.

Later I was a bit involved in, not the hacking scene, but more like downloading movies online and things like that.

[00:02:44] So there were things on IRC, like DCC servers and things like that, that permitted you to download illegal movies and files and whatever. This is something that got me interested in computers. I didn't really learn to program before I was in engineering school, which I attended maybe four or five years later. So mostly I was playing with computers and learned programming later at school.

00:03:13 - Anthony Campolo

Cool. Yeah. I was also someone who downloaded a lot of stuff as well. It sounds like you were a little bit before the LimeWire days, right?

00:03:21 - Sebastien Lorber

Yeah. Before that, there were a lot of things going on on IRC and also on online forums. We called those, I think, boards or something like that. And when people exchanged the links, I somehow got into hacking. So I was like a script kiddy trying to exploit remote servers in universities to put movies on those servers because they had a good connection. So it was easy to distribute the movies.

I got into the hacking scene by trying to get into those servers and put the movies there.

00:03:59 - Anthony Campolo

That's so cool. That's a really cool story. Have you ever heard the term phone phreaking?

00:04:05 - Sebastien Lorber

I think I've heard about it, but I don't know exactly what it is anymore.

00:04:09 - Anthony Campolo

There's a good book. It's called Exploding the Phone. I think you might enjoy it. It's like the birth of hacking. Essentially, the original hackers. Before you could hack computers, you would hack the telephone system. Literally, you would figure out the dial tones. That's how it all worked. You'd have dial tones that would basically program AT&T, like the Bell System.

People would figure out what these tones were, find ways to reproduce them, and then do that into the phone system. So you'd get free calls or you'd actually get into systems you're not supposed to be able to get into.

00:04:46 - Sebastien Lorber

I think I remember this, but I never tried to do it. I think it was before I tried to hack things. I'm not sure it was still possible at the time when I tried to hack my first server.

00:04:56 - Anthony Campolo

So yeah, this is actually the birth of Apple. This is part of their whole story: when Steve Jobs and Wozniak got together, they were building what were called blue boxes, which were basically devices that would let you hack the phone system and then sell to people, which was very illegal at the time.

How did you get into JavaScript?

00:05:17 - Sebastien Lorber

I did engineering school, where I mostly learned about Java. We saw a lot of languages, but the main one was Java, like many engineering schools at that time. So ten years ago I started as a Java developer doing things like Spring and Hibernate and things like that in big companies in France.

After maybe three years of Java, I was interested in functional programming, so I decided to learn Scala. I joined a startup as a CTO to help develop the startup. The thing is, I was not a front-end developer at all, and in the beginning I didn't even like JavaScript. For me, it was like a toy language that you use to make some text blink or things like that.

The thing is, I saw that my team at my startup struggled to make the front end work. They were using Backbone.js and we had something quite complex to build. I saw that they made some mistakes in the code, and I tried to help them by using my experience doing some back-end development. I was able to help them figure out code patterns that they could use to make the front end simpler and easier to maintain.

[00:06:23] So this is how I became a front-end developer, basically in 2014. I was an early adopter of React, like seven years ago, when nothing existed. There was no state management at all, so you had to do things on your own. There was no Redux, and even the precursors to Redux didn't exist at that time.

Progressively, the React ecosystem grew and a lot of tools were created each year. And this is how I became an almost full-time front-end developer.

00:06:54 - Anthony Campolo

It sounds like you were into React long before you were working for Facebook. Is that kind of how you got connected to Facebook because you were already connected to the React world?

00:07:05 - Sebastien Lorber

I think I've been connected to the React world for a long time because I've been using it for seven years, and I know many people who now work for Facebook and things like that. We had a lot of discussions in the early days with many people who are still in the React community today.

I'm maybe not the most famous developer of the early days today, because some of them are much more known and maybe are in the React core team now, but I think many people in the early days will have seen my name in GitHub issues and things like that. I also tried to contribute to this ecosystem. I created some tools and tried to innovate with new things that I wanted to show to the community.

For example, before Redux existed, I created a framework in my startup that basically had time-travel debugging before Redux was released. I published a YouTube video, like a year before the release of Redux, showing an experience with time-travel debugging.

[00:08:07] But the thing is, it wasn't very polished and I was not very good at marketing or documentation, which is a bit weird today. This project never took off because it was mostly something internal that we built for our startup. It was not very usable outside of the startup, so it didn't take off and we didn't push for it to be adopted by the community.

Then Abramov did a better job than me at pushing these ideas, and I think a lot of other tools now have been created by many other people in the community.

00:08:38 - Anthony Campolo

And did you implement Flux to do that, or did you use a different architecture to figure out the same thing? I was kind of curious how it worked.

00:08:46 - Sebastien Lorber

At that time, a lot of people were trying to innovate with the same approach. Many people in the early days of React were interested in React because they had some kind of experience in functional programming.

For example, I had been a Scala developer some years before, so I was able to understand functional purity. I used things like monads and things like that. So all these things helped me understand the value of React.

Also, other people in the community, for example David Nolen, showed very early in the React days that the functional programming model was very interesting for the performance of React. This is something that even the React core team didn't show at that time. So he really got a lot of people in the functional programming community interested in React.

We were all trying to do something a bit like what Redux does, but in a worse way, somehow. And then Abramov was able to figure out a way to do this.

00:09:56 - Anthony Campolo

Now, is David Nolen for the ClojureScript and React, right?

00:10:00 - Sebastien Lorber

Yeah.

00:10:01 - Anthony Campolo

We did a podcast with him a long time ago. And once I made the connection between his ClojureScript work and React, it was like, oh, a lot of things clicked together because it makes a lot of sense, as you say. You know, people who really like React tended to really like functional programming.

I'm glad that we can get you on to really talk about this history here. React is so interesting in that it's completely taken over web development, but I find very few people actually know the history. If you ask people who created it, or if you ask them who Jordan Walke is, most people have no idea.

00:10:38 - Sebastien Lorber

Yeah.

00:10:39 - Anthony Campolo

This is one of the things I enjoy, getting people on who've been there really since the beginning to get a lot of this deeper history, because I'm a big history buff. Helping put you in the canon as you deserve to be.

00:10:51 - Christopher Burns

I don't even know who Dan is, or what he's done.

00:10:55 - Christopher Burns

No. To me, React feels, even today, still mysterious about who created it. Obviously you can read about it and stuff, but when I always think of React, I think Facebook created it. But you never really think about why Facebook created it, how it was created for Facebook and all these other things. It just kind of became this massive thing one day and we all started using it.

00:11:20 - Sebastien Lorber

I think in the story, a lot of things are a bit lost. For example, in the very beginning of React, I think the most famous person, the person that represented React, was Pete Hunt. But today nobody knows him in the community anymore except the ones in the early days, somehow.

00:11:38 - Anthony Campolo

Yeah, that's a perfect example. I actually went to a Clubhouse specifically to hear Pete Hunt, because Pete Hunt and Jordan Walke and a bunch of people were doing a Clubhouse not too long ago. For me, as a developer advocate, I look at Pete Hunt's place in the history of React, and it's crucial. It's really important. And like you say, no one knows. No one has the slightest idea.

But I imagine he probably is not that bothered by it, because for someone like that, when you do something significant within the history of a field, doing the thing is more important than necessarily getting the recognition for it, although the recognition is also nice as well, I guess.

00:12:18 - Christopher Burns

Does anyone care about who created Angular? Like, actually created Angular?

00:12:22 - Anthony Campolo

He probably doesn't want to take credit for that at this point.

00:12:26 - Christopher Burns

Like, this is the thing. What was before React? Before React you had Angular. Was that before React? Angular 1 was before React.

00:12:35 - Sebastien Lorber

There was AngularJS.

00:12:37 - Anthony Campolo

And Backbone and Ember. Those are kind of the three big things at the time.

00:12:41 - Sebastien Lorber

Yeah. And Browserify and RequireJS.

00:12:46 - Anthony Campolo

So let's get into Docusaurus. Let's start with Docusaurus 1.

00:12:51 - Sebastien Lorber

So I was not at the creation of Docusaurus 1. I don't know exactly the whole story. It was created by Facebook maybe four years ago or something like that. They noticed they had a lot of open source projects. Every time it was the same thing: they created a docs site and copy-pasted the same code from one site to another.

From there they had the idea to create a tool to make it easy to create docs sites for all their projects, even if it's not very customizable. At least it would reduce a lot of the work to get the site online.

So they created the first site and the first version of the tool. It was using React, but not in the same way as most Jamstack React frameworks work today. It was only using React on the server. There was a Node process that rendered the pages on HTML files. React wasn't used in the browser, so you don't download React. It was actually quite similar to simple static site generators like Eleventy and Jekyll.

[00:13:55] For the JavaScript items in the browser, you download additional vanilla JS components to make them work. A lot of sites use the first version of Docusaurus. For example, today there is still the Babel website that uses Docusaurus. And I think Prettier is also using Docusaurus 1.

00:14:14 - Anthony Campolo

That's super interesting that Facebook was literally just copy and pasting the same docs site from one to the other. Makes sense. Like that's what I probably would have done, because with docs you want it to look nice enough. You want it to get the information across that needs to get there. You don't want to belabor it.

But at the same time, if you're just copying and pasting the same thing over and over again, you can't grow beyond whatever that initial boilerplate template is doing for you. So I would imagine they were probably hitting up against limitations of what they could even do with it.

That's also really interesting. You were saying how it was basically server-side rendered and then spitting out static files. So it sounds like it was kind of like Next.js, but in static mode a little bit.

00:15:01 - Christopher Burns

Or would that be Gatsby?

00:15:03 - Sebastien Lorber

Actually, it's different because Gatsby and Next.js are using static generation, but they hydrate React on the front end. So, for example, in the first version of Docusaurus, you couldn't use state at all in your React components. You had to use, for example, jQuery or something like that if you wanted to add a dynamic component on the front end.

So it's quite surprising not to hydrate React, but that was how it worked. It was really something quite like Jekyll. I think there is something quite interesting to discuss about this. One of the main differences between version 1 and version 2 is that Docusaurus 2 hydrates React on the front end, so it is a real single-page application, while the other one was not a single-page application. It was just static HTML pages that you navigate with regular browser navigation.

00:15:53 - Anthony Campolo

That's great. We can probably infer some of this, but just to dig into it, what were the issues with Docusaurus 1? What were some of the limitations that required you to make this change so that now it's getting rehydrated and now we have this kind of interactivity? What sort of limitations were you running into with Docusaurus 1?

00:16:14 - Sebastien Lorber

As I wasn't there at this time, I don't know exactly all the limitations. But I think we have seen with frameworks like Gatsby that creating single-page applications could lead to a good experience.

For example, there were techniques like prefetching. So when you hover a link, you download the assets, the JavaScript for the next page. And then when you click on the link, everything is already ready. It just has to render on the client without fetching anything on the server.

So it gives a good navigation experience because you don't change from one page to another. For example, you can persist the scroll position of many items on the page. You don't see a blank screen when the next page is loading if you have a slow connection and things like that.

I think it can improve the user experience. I think something very interesting is that, for example, if you compare 1 and 2, the Lighthouse score may not be better for version 2, despite the experience being better for the end user.

[00:17:16] So I think there is some kind of mismatch between the score that the monitoring tools give you and the real experience that the user has, because the monitoring tools are not really able to understand the whole picture. They mostly measure the performance of the very first load, but they don't measure the experience in general, I think.

00:17:39 - Anthony Campolo

Yeah, I've always struggled to really know how much stock to put into Lighthouse scores and things like that, because it makes sense. If you think about it, it's coming from Chrome, which is the one creating these crawlers that you're trying to optimize for. So it makes sense that you'd want to optimize for whatever they want you to optimize for.

But as you say, that may or may not be reflective of anything real in terms of speed and how you interact with the site.

And you mentioned a couple of times there, I've been saying, what was it like working on Docusaurus 1, and you didn't even work on Docusaurus 1, which I didn't know. I thought that you were the Docusaurus guy. So I'm kind of curious: you are the Docusaurus 2 guy, I think. So where do you come into this story? At what point did you enter the picture, and how much of creating Docusaurus 2 were you a part of?

00:18:31 - Sebastien Lorber

Actually, I just joined Docusaurus last year, so the project already existed for four or five years. Maybe in 2017, the first version was released. I think after maybe 2019 they decided to create the second version.

The first version still existed, but the work on version 2 had started and we were in alpha for two years, which is too much probably. We have been working on version 2 for like two years already and it's still in alpha, but the beta will be released soon, so I think it gives a good signal to the community that the project is starting to feel more ready and stable.

I joined Docusaurus 2 only last year and the work had already started more than a year earlier. The thing is, I am a freelancer. I'm not a Facebook employee. I think Facebook was looking for someone to help on the project with good experience in React and its ecosystem, and also with the open source model, to be able to collaborate with external contributors.

[00:19:44] Also, there is something that happened. They had an intern at Facebook, which I think was an employee a bit later, and he died of cancer. So I think there was someone on the team that was missing. So unfortunately I've replaced him somehow, probably to continue the project and ensure that version 2 is completed.

I don't think this is usual for Facebook to hire a freelancer to maintain an open source project, but maybe the circumstances made it that I got the job somehow. I don't know exactly.

00:20:18 - Anthony Campolo

Interesting. And how many people are on the team?

00:20:20 - Sebastien Lorber

We are mostly three people. There are two people at Facebook, mostly Joel, my manager, and Yongshun. Yongshun is not working too much on this these days because he has an internal project at Facebook. And there are also some external contributors like Alexei and others. There are many external contributors, but they don't contribute on a full-time basis.

00:20:44 - Anthony Campolo

That's really interesting that you say it's been in beta for two years.

00:20:49 - Sebastien Lorber

No, it's not in beta. Actually, it's in alpha, and we are going to release the first beta after two years.

00:20:56 - Anthony Campolo

Gotcha. That's funny. For me, I always think, is it out or is it not out? So to me, I don't even think of there being an alpha and a beta. It's like, well, is it out yet or is it not out yet? But yeah.

00:21:08 - Sebastien Lorber

This is something that is always complicated to explain to the community, but the motivation for being in alpha for so long is that the first version had some features like internationalization. We didn't want to be in beta before having exactly the same set of features as the first version.

So the alpha was the state where version 1 users couldn't migrate to version 2 because all the features were not available. So now we have the same feature parity with version 1, and we are going to release the beta very soon because it doesn't make sense to wait much longer.

I just have one PR to merge before releasing the beta, and maybe a blog post to write, so this will be soon.

00:21:53 - Christopher Burns

One of the big things about Docusaurus 2 that took so long to get out, some of the big questions are like, has the community moved on to things like MDX? Does Docusaurus 2 support MDX yet?

00:22:07 - Sebastien Lorber

Yeah.

00:22:08 - Christopher Burns

There we go.

00:22:09 - Sebastien Lorber

It is fully based on MDX, actually, and somehow it is also a problem. For example, if you are a developer, you like MDX because you like using React components in your documentation to make it interactive. But there are a lot of users that are using Docusaurus who are not front-end developers, and they don't understand why regular Markdown doesn't work in Docusaurus.

Somehow the MDX parser is not totally compatible with CommonMark. So, for example, if you use things that look like React components but are actually regular HTML tags and you don't close them, you will have compilation errors in MDX. This is something that we want to improve. We want to add a second parser to the console so that, for example, if you have an existing documentation which is on GitHub and uses another tool that is compatible with CommonMark, you can use that exact documentation in Docusaurus without refactoring all the illegal characters and things like that.

So we try to have a better compatibility with the existing ecosystem. But by default, MDX is not always compatible. So sometimes you have to do changes on your documentation to make it compatible with MDX.

00:23:25 - Christopher Burns

And one of the big things with Docusaurus is that it's versioned by default as well, isn't it?

00:23:31 - Sebastien Lorber

So what do you mean?

00:23:32 - Christopher Burns

You can do multiple versions quite easily. Say you're just going to use a regular CMS. Why would you use Docusaurus when you could just use a CMS or something? You can easily keep your Docusaurus docs cross-compatible to have multiple versions, like, this is the documentation for version 7.6.5.

00:23:52 - Sebastien Lorber

The versioning model of the site is maybe a bit different from what people are used to, because we build a single-page application for the whole site, including all the versions.

This can be nice for some sites because, for example, if you have a small documentation, it is sustainable to build all the versions in a single-page application, and then you can have a dropdown that permits you to switch from one version to another and stay on the same documentation from version 1 to version 2 when you choose the new version on the dropdown.

But if you have a very large site, it can be a problem for scalability because if you have thousands of documents, you have more pages to build every time you submit a documentation change.

So if you have like ten versions with ten thousand documents, maybe you'd better use Git branches for your site instead of using the built-in versioning features. You can maybe deploy each version branch on a separate deployment so that if you do a change to the newer documentation, you don't have to rebuild all the previous versions.

00:25:01 - Christopher Burns

One of the big things that came with version 2 that version 1 struggled with is theming.

00:25:07 - Sebastien Lorber

Yeah, about theming. We use an approach that is quite similar to what Gatsby has. I think they call this shadowing. We call this swizzling, but it's similar.

So basically, if there is a component, we have a default theme. If you want to override a component from the system, you can use the CLI to get the code of this component, put it in your source folder, and change it the way you want. As long as it is in the correct place, it overrides the default component that is in the theme, which lets you customize the components.

This works great, but I also think it's not ideal because somehow it creates a very large API surface for your code. So it's quite implicit because it's not a publicly documented API. If someone copies your code and tries to modify it, and you do some internal changes to your theme, then it might break the user code because maybe the props have changed or things like that.

[00:26:08] And some people find it hard to upgrade from one version to another because of the changes we made. Sometimes we break their CSS and things like that. So this makes it difficult to maintain backward compatibility for this.

What I'd like in the future is to maybe use TypeScript to make this contract more explicit. So, for example, if there is a type here, it means that the user has to do something, and maybe it will be more clear for the user and maybe also for us to know when we do something. It is a breaking change because sometimes we do breaking changes, but it's not clear for us that it is.

00:26:44 - Christopher Burns

One of the hopes that we have now with the theme system in Docusaurus is that anybody can create an npm package. I believe you can do it as an npm package. I think you include it into your theme and now you have a completely different theme for your Docusaurus.

What I mean by that is there's multiple different default themes. One of them is Bootstrap that I saw. You basically do yarn add docusaurus/theme-bootstrap. Then you put the theme in the config. Your Docusaurus is now all in Bootstrap.

What we might see in the future is people just putting up random themes, kind of a bit like Gatsby, where it's like, here's a completely different theme for you.

00:27:26 - Anthony Campolo

Got to get your twin.macro in there, right?

00:27:28 - Sebastien Lorber

I mean, for now we really only have the classic theme and the Bootstrap theme, but the Bootstrap theme is absolutely unusable today, so unfortunately it's not maintained very well.

When the beta is out, I will start to work on this again, because the idea is maybe to support three themes, like the classic theme, the Bootstrap theme, and maybe one for Tailwind too. All three main themes would share the same user experience. So, for example, it's interesting because we can create a package with shared React code for all three themes, which makes it easier to maintain, and we just have to handle the classes and things like that in the style components of each theme.

For now, we are not there because it requires some refactor to extract the shared code related to the user experience and separate it clearly from the classes. This is work that has to be done to make this more sustainable.

But in general, Docusaurus is a static site generator. We can really compare it to Gatsby because it is quite similar.

[00:28:38] There are similar lifecycle APIs that you can implement. If you have used Gatsby, you know that there is gatsby-node in which you can call a function called createPage. This is something that I'd like to add to the tool, so that basically you will be able to create pages with another API and provide the data that the page needs. I think it can help to integrate with CMSs and things like that.

00:29:00 - Christopher Burns

Having a createPage function would then take Docusaurus out of this territory of being developer-only documentation. It can be more integrated into even HR documentation or whatever.

Because that's one of the things that I was going to bring up with things like Gatsby and even GitBook. All these other systems are starting to say, like, wow, writing Markdown is great. It's still a very specific skill that the wider population doesn't have. So why can't you just type some Word document into any CMS and now that's documentation? That's what Gatsby does really well right now, the CMS integration. So it'd be really cool to see that in Docusaurus.

00:29:54 - Sebastien Lorber

I don't think the goal of Docusaurus is to provide a wide ecosystem of plugins for every existing CMS, like Gatsby, because this is really what Gatsby tried to do. But at least we should make it possible for people to build their own integration and maybe try to reuse as much of the existing infrastructure as possible.

Maybe some people will create community plugins for integrating with a CMS, but I don't think it's the goal of Docusaurus. But there is something that you mentioned that is important. Currently it's a bit hard for regular users to use the service because they are not used to Markdown and, more importantly, they are not used to opening pull requests on GitHub. This is really something that is complicated. So if you are not a developer, it's quite hard to contribute to the documentation because there is no user-friendly interface to edit the documentation.

This is also something that I think there is a need for at Facebook because, for example, they had a team that migrated from a wiki documentation to Docusaurus, and now, somehow, they are not too happy. I mean, some users find there is more friction to contribute to the documentation, and we are looking for solutions to solve this problem.

[00:31:03] I think there is something that is interesting. For example, you can use CodeSandbox and things like that to edit the documentation in a sandbox, and then it's possible through the user interface to submit a pull request directly from the interface. So you don't have to load the site locally and get it running with the front-end tools.

Also, we are in touch with StackBlitz. They have something very interesting. They are creating a Node.js polyfill that can work in the browser with WebAssembly and things like that. This is a bit crazy. I don't know how it works, but it works and they are able to run the tools directly in the browser.

When I say running the tools in the browser, it's not running the client-side code. They are running the build process in the browser somehow. This is quite interesting because this allows you to load Docusaurus easily in the browser.

[00:32:00] Somehow it's like CodeSandbox, but faster, I think.

00:32:04 - Christopher Burns

I wonder if it's using one of CodeSandbox's tools. I think it's called Sandpack. It's their open source, like, Webpack alternative that works in the browser. It's worth looking up. It's called, I believe, CodeSandbox/sandpack on GitHub.

One of my questions with things like Docusaurus 2 is, do you think that there will ever be a way to auto-document your code effectively? As in, you write some comments in your code. Bish bash bosh. There's now a page in Docusaurus.

00:32:43 - Sebastien Lorber

I mean, you can't create your own documentation with this technique because it's only for the API part of the documentation. I'm not really skilled at designing documentation websites, but as some people say, for example, there are four kinds of documentation. You have the tutorials, the guides, the API reference material, and maybe the explanations that give more context.

This is, for me, only one part of the documentation, which is the API reference. It's for when you want to show something very accurate and not very user-friendly, but at least a reflection of the actual code. We don't provide anything in the core, but some people have built some plugins, and the Redux website uses something to generate documentation from TypeScript types.

We also have a community plugin to document an API. So it uses Redoc, I think, but I don't know exactly what this is. I've used Swagger before, which is some kind of UI you can use to query an API, and Redoc is quite similar, I think.

[00:33:46] So it generates some documentation based on the schema of an API.

00:33:52 - Anthony Campolo

OpenAPI is what Swagger has been renamed to, because it used to be called Swagger. Then Swagger got purchased, and they took the spec part of it, which is OpenAPI, and extracted that out into a foundation.

That's something I come across a lot. I'm doing a lot of work with APIs. There's just one last thing that I was actually curious to get your thoughts on. Before we closed out here, Clare had mentioned that the Jest team had been migrating from Docusaurus 1 to Docusaurus 2, and that she was kind of like a fly on the wall for some of that process.

So I'd be curious to get your views on that, what they were looking to get out of that migration and how you were able to support them through that process.

00:34:37 - Sebastien Lorber

Oh, so actually, it's mostly me that reached out to the Jest team to migrate their site because I was working on the internationalization feature, and I was looking for a version 1 site that needed to migrate to version 2 and that used the internationalization feature of version 1.

This was mostly to be sure that we can migrate an internationalized site in version 1 to version 2, and to document the process so that other sites can migrate by reading the doc that I wrote about this.

This was quite a complicated migration because we were using a SaaS tool called Crowdin to send the translations, then translate the documents, and then redownload the translated documents.

But the thing is, there were a lot of little issues that were complicated. I had to find ways to make it work with the tooling until it was possible to migrate the first version of the Jest website. So this was maybe a process that took a few months to get online.

[00:35:47] It was not easy, but now at least I know that the internationalization support in the tool is quite good, and a lot of people have already adapted it to document their sites in multiple languages.

00:35:59 - Christopher Burns

And I guess the final thing I can say about Docusaurus is with search done by Algolia. It just works, and that is amazing when you're trying to find something.

00:36:12 - Sebastien Lorber

Yeah.

00:36:14 - Anthony Campolo

Did you evaluate other ways to do search that weren't Algolia, or was Algolia just kind of the obvious search solution to go with?

00:36:23 - Sebastien Lorber

I don't think there are a lot of search solutions available. So mostly Algolia is maybe the most popular one, and maybe there is Elastic and there are a few other ones. But Algolia makes it free for open source websites, so you just have to ask their team to make it work and they provide all the support.

So I think it's a win-win situation because they provide support for our community by helping people get their documentation searchable. And in return, they also get a lot of visibility because a lot of sites are using Algolia.

I didn't try to contact Elastic or other search providers to see what they have to offer, and they didn't reach out to me either. But I think it may be possible to integrate other search engines, and I try to make the code in such a way that it's possible to actually write a plugin to integrate with something else.

00:37:14 - Anthony Campolo

Awesome. Well, thank you so much for being here, Sebastien. Thank you for all the work you've done with Docusaurus and helping out with the Redwood stuff especially. We didn't talk about it too much, but if listeners are kind of curious about that, your name came up many times in the conversation with Clare, so she was very much appreciative of all the help you gave us.

We're really excited to have a super cool, modern multilingual docs site, and it's all possible because of Docusaurus. So thanks a lot.

00:37:44 - Sebastien Lorber

Thank you. Thank you for having me.