Investigate Docusaurus (revisited)

[Xhale1]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Related: #100 and fastify/fastify#722.

I propose revisiting migrating the docs to Docusaurus, especially after significant improvements to their tech since previous discussions.

I would love to draft up a proof of concept for the team if there's serious interest, and help with efforts to migrate if the demo proves viable.

Motivation

My team recently spent some time investigating alternatives to Express and some elements of the Fastify docs gave us pause. The most pressing for us was the lack of order and headers in the sidebar which made getting started more cumbersome than necessary. Additionally, something about the "system defaults" approach to Fastify's docs makes the site feel less professional than, say, Create React App or React Redux.

I think Docusaurus's default styling, creature comforts, and additional features make migrating a compelling option. Recent (since #100) support for markdown will make migrating far less troublesome than it once was.

Potential benefits:

• Order pages in the sidebar
• More intuitive table-of-contents (potentially subjective)
  • Separating the table of contents and sidebar could prevent confusion on what's a page and what's a page's content (and allows for more nested docs)
• Improved code blocks
  • Copy button
  • Built in titles
  • Better styling (subjective)
• Better docs-wide styling
  • Large number of ready-to-use components (ex. tabs, admonitions)
  • Dark mode
  • "Trendier" default design
• Familiarity with developers
  • Docusaurus is widely used across the React ecosystem and, for me at least, instills a degree of confidence when I see it
  • Existing familiarity translates to comfort and ease of use
• Internationalization support
  • Adopting this feature would obviously incur many additional challenges, so it's benefits are diminished
• Off-load documentation maintenance to a well-established industry standard
  • Using a tool such as Docusaurus could save the core Fastify team some dev time

Example

No response

[Eomm]

In general, I think the fastify website tech stack is out of date and need an upgrade.

I think the "must have" features are:

• Fastify's version dropdown to see the right documentation based on the version (not the last one only)
• The fastify repository's docs/ folder is the main source of truth

Nice to have:

• runkit integration (I saw it somewhere and it is just amazing)
• site preview on PRs

---

I'm not against any new framework (Docusaurus, Gatsby, GitBook or others), I prefer the one that fits the fastify needs.

EDIT: forgot to say: we need someone that would like to push this initiative. I'm happy to give feedback, but I don't have a time slot to help implement this

[mcollina]

I recognize the problems in the documentation and current website. We truly need somebody that will champion it in the long run.

This is a significant endeavor. I'm not convinced in moving to Docusaurus is the right solution as it felt too "strict" in the past with how they wanted docs.

[Xhale1]

My company is adopting Fastify and I would love to do what I can to lead new documentation improvements (content, design, infra, etc).

I suppose my next question is what do you feel would be the best next steps? I'm confident in Docusaurus as the best tool for the job though I could draft up some comparisons if it'd be beneficial.

I can build out a proof of concept for new docs as a jumping off / talking point for further conversations on what this would entail.

Edit: made it a bit more clear that I'm interested in leading documentation improvements.

[jsumners]

With the recent addition of support for guides in the documentation I intend to do a reorganization. I just haven't had time to get started yet. Might have some time this weekend. Not sure.

As for the proposed package: I would rather stay far away from Facebook tech.

[Xhale1]

Regarding the Facebook tool: I'm generally all for anti-facebook sentiments but I think we should pursue the best tool for the job. Avoiding Facebook also means avoiding Next, Gatsby, and React.

That said I have some ideas for alternatives:

• GitBook
  • Really solid from a design & usability standpoint
  • It's proprietary and doesn't leave a lot of room for customizing (they've changed pricing models in significant ways in the past)
  • Flip side of that is they handle all the tech & deployments which means even less developer maintenance
• Next.js with additional code to handle markdown and styling
  • Still uses Facebook tech (react)
  • Allows for pretty much whatever design / functionality we want
  • I personally have a lot of experience with the framework
  • The MUI docs are an incredible example of this approach
• VuePress
  • I've heard good things and it's used frequently in the Vue community, but as I have almost no experience in Vue I wouldn't be able to assist here

It seems to me that next.js and vue could end up requiring too much developer time, which would leave GitBook and Docusaurus as popular feature-rich options. I prefer the open-source nature of Docusaurus to GitBook, and I like the Next.js solution if the engineering time ends up being low enough.

[jsumners]

Avoiding Facebook also means avoiding Next, Gatsby, and React.

This is completely acceptable to me.

I'm not convinced we need to change the tooling. I will try to put together my proposal in short order. It amounts to:

1. Split /docs into /docs/guides and /docs/reference
2. Add /docs/index.md
3. Add /docs/reference/index.md
4. Move appropriate docs into the correct locations

A subsequent PR(s) would address the actual text of the documents. All reference docs should match the style of https://www.fastify.io/docs/latest/Encapsulation/ and https://www.fastify.io/docs/latest/Hooks/ .

[lachlancollins]

Hi, I've been directed here from fastify/fastify#2877. The key focus of my comment there was improving the integration of TypeScript documentation so that it is alongside and "equal" to the JavaScript documentation, rather than in its own separate page.

One of my suggestions as part of this improvement was implementing toggles for code examples between JS and TS, citing Redux Toolkit's docs as an example, which I've since learnt actually uses Docusaurus. I know @Xhale1 has mentioned improved code blocks as one of the benefits, and I see this toggle functionality as the next-step on top of that and another pro for migration.

In terms of the React ecosystem, at this point it simply has the best tools for frontend development, and I believe migrating to Docusaurus would ensure the tech supporting Fastify's documentation is future-proofed. I've also just checked and found that Metalsmith hasn't pushed any updates since 2016.

As someone with a fair bit of time on my hands at the moment, I'd be keen to work on a Docusaurus project for Fastify - let me know if this is something you'd be interested in.

[Xhale1]

I feel strongly that avoiding react because it't facebook tech is a poor decision. The same logic could be applied to avoiding nodejs, typescript, github, npm, yarn, or a great many leading tools that make developer lives so much better.

A massive amount of the top tech sites in the world use React, and a healthy majority of top open source projects use Docusaurus. The project is fully open source and we could fork it to avoid facebook influence if necessary.

Adopting an industry standard tool makes first-time contributions far easier, and can ultimately let us focus on writing incredible documentation instead of re-inventing the technology itself. The benefits we would get out of the box seem extremely compelling to me, and they seem compelling enough to a large number of other open source projects.

I greatly appreciate the work that has gone into the existing documentation site and the Fastify ecosystem as a whole. That said, I believe docusaurus could benefit the community in a number of ways and is the best tool for the job.

Examples of incredible tools using docusaurus:

• Socket.io
• Redux & Redux Toolkit
• Jest
• Supabase

Edit: I want to readdress and refocus on the core pain points I think we're looking to address here.

Documentation features

Improving the in-house implementation will inevitably lead to a game of catch-up with tools dedicated to docs, and it will pull developer focus away from other parts of the Fastify ecosystem. Existing dedicated solutions give us new features to write amazing docs out-of-the-box, for free. We only pay the cost of migration.

Time commitment

Dedicated tools bring with them their own knowledge base and documentation on how to use them. Adopting a dedicated tool means our community benefits from the existing knowledge on how to use it. Docusaurus's own docs, for example, lower the barrier to entry to working on any docusaurus site and alleviates the struggle of learning the quirks of an home brewed system. In my opinion community members wanting to contribute to improving the docs site would have an easier time with docusaurus or similar than they would with the current system.

[mcollina]

There is a fundamental issue with docusaurus: versioning. Versioning in Docusaurus is very far from how things should be structured. Docusaurus support this as an afterthought by keeping all the data on the same repository (ref https://docusaurus.io/docs/versioning). The approach that this website currently has is great for this as it allows multiple versions to coexists (they are assembled from different releases).

IMHO we should just move this to elevently. It's more up to date than the current stack but it's still true to the same principles.

Note that the majority of the work is needed on the documentation itself.

[jsumners]

Note that the majority of the work is needed on the documentation itself.

This is correct. Unfortunately, I was just too out of it over the weekend to work on fastify/website#291 (comment) (I started a local branch and that's as far as I got). Thursday and Friday are a holiday for me, so I hope to get some work done at that time.

In terms of the React ecosystem, at this point it simply has the best tools for frontend development, and I believe migrating to Docusaurus would ensure the tech supporting Fastify's documentation is future-proofed.

This statement is a matter of opinion. If you ask the folks that like Vue, Marko, or other things, they would say the same sort of thing about those technologies.

I feel strongly that avoiding react because it't facebook tech is a poor decision. The same logic could be applied to avoiding nodejs, typescript, github, npm, yarn, or a great many leading tools that make developer lives so much better.

It is my opinion that using Facebook tech is tacit approval of that company's practices and tactics on a myriad of issues around privacy and data collection. I am but one vote amongst many, but my vote will always be against using Facebook tech.

Adopting an industry standard tool makes first-time contributions far easier, and can ultimately let us focus on writing incredible documentation instead of re-inventing the technology itself.

On this we agree. I just want to see a different technology used to fill that role. Matteo is suggesting https://www.11ty.dev. I use https://gohugo.io for my personal sites and find it fantastic.

Remember, fastify.io is more than just documentation. It is a full website that needs to support things like fastify/website#194 in addition to the documentation. The requirements set forth by fastify/website#291 (comment) are what should be focused on in any project that seeks to update the website generation. For example, when I do get my proposal PR up for the documentation, I will have no way of knowing if it works since we do not have a way to generate test sites from PRs to the main repository.

[lachlancollins]

Just a few thoughts on the versioning issue in Docusaurus - wouldn't it be possible to just use the current strategy of clone all releases, and then copy the docs of old versions into /versioned_docs, and the latest release into /docs?

Also to clarify my view, I would like to see something more than the current site's features, including those mentioned by @Xhale1 up the top of this page. Docusaurus seems to be the easiest way to get these out-of-the-box and with less manual work and also has wide adoption. However, if you guys would be more comfortable with something like 11ty or Hugo, I'm not fussed as long as they can be expanded to add this functionality.

I'm also just wondering about the benefits of having separate doc versions for each minor release - most sites I've seen just split it into major. Is there a reason why this format is used on Fastify's website? I'm updating on v3 whenever I notice a new version, and haven't had any breaking changes (yet).

Thanks in advance - this is the first time I've been invested enough in an open source project to contribute to discussion, and I'm really looking forward to seeing how Fastify grows :)

[jsumners]

Please see fastify/fastify#3474 for my proposal as a starting point.

[jsumners]

I'm also just wondering about the benefits of having separate doc versions for each minor release - most sites I've seen just split it into major. Is there a reason why this format is used on Fastify's website? I'm updating on v3 whenever I notice a new version, and haven't had any breaking changes (yet).

Personally, I would be willing to cull all of the old documentation and stick with the current supported LTS releases. Either at the semver major level or only the most recent release in the LTS line. It would greatly simplify a lot of site generation logic.

[Xhale1]

I fully agree with @lachlancollins on not being attached to docusaurus, whatever tool gets us the best docs would be great. Apologies if I seem like I'm just pushing a single tool.

Regarding versioning: I also agree that we should drop the patch (and I think minor) versions of the docs. I propose having 1.x, 2.x, 3.x, and next (or similar). This is also the way docusaurus is built to handle versioning, with a next branch and then a set of docs for each major version. I actually really like how they handle it, but to each their own.

I also want to throw Vue Press into the mix for consideration as an alternative tool. I don't have very much experience with it but it's used extensively in the vue ecosystem.