Docusaurus – Build optimized websites quickly, focus on your content

The first time I heard about Docusaurus was when someone mentioned on Hacker News that they had ruined their SEO:

https://news.ycombinator.com/item?id=34389421

I helped him in recovering from a Google SEO penalty, and he documented his journey on his blog:

https://johnnyreilly.com/how-we-fixed-my-seo

This might be helpful for those using Docusaurus, as some default settings, like pagination and tag pages, can generate thousands of non-helpful pages. These issues can be easily fixed with noindex tags and a sitemap/structure cleanup.

Overall, I think Docusaurus is great. It's clean, flexible, and the community is very responsive, so it's constantly improving at a fast pace

I wish all API doc generators test the doc code examples like this https://rust-lang.github.io/mdBook/cli/test.html

Even if the code example works today, it might not in the future and tests prevent people getting stuck on outdated docs like we often see.

I've tried most of these and this is definitely one of the best, especially since the latest version. It's not too heavy but includes all the features you don't know you need at the start, and a good ecosystem of plugins and extensions.

Other notable mentions are

- mkdocs-material, if you prefer python to js

- astro starlight, not quite as mature and a bit heavier but looks nicer out the box and includes built-in search

Long time user of (and contributor to) Docusaurus. I use it to build my markdown powered tech blog. https://johnnyreilly.com/ It is very much a Goldilocks product for me ("just right") in that it has React support, Markdown support, TypeScript support and a good amount of customisation is possible (good underlying APIs). It also has a great community. Props to Sébastien Lorber for leading the project so well!

My company migrated away from docusaurus because at 1500+ markdown documents to index, the VM running it crashed out-of-memory. The VM has 32GB RAM allocated.

Somehow, someway, it was very resource-intensive for what it was.

We now run a homemade alternative that basically does the same job, but keeps scaling to five digit document counts (so far).

I tried migrating our markdown docs-as-code to use Docusaurus, we have somewhere around several hundred pages, and the build times seemed very long (5-10 minutes) compared to a simple bespoke python-based static site generator. Is that common in people's experience with docusaurus or perhaps there was an opportunity for optimizing or making it more efficient?

Docusaurus shines in docs-as-code scenarios. I used it for Amplication, Februar, and other technical docs projects.

The SEO features, integrated Algolia search, and built-in components save a lot of time and help you focus on writing markdown.

The plugin system and React-based customization is powerful, but for most projects you should be fine with the provided components and editing the custom css file.

For a look at how a dev tool company uses Docusaurus to implement its docs, check out this article on Amplication's approach:

https://medium.com/abundant-dev/amplication-documentation-ca...

This might help those wanting to use Docusaurus with a docs-as-code workflow, especially when using GitHub or other git platforms for reviews.

One of my favorite features of Docusaurus is integration with TypeDoc to generate API docs for TypeScript definitions. It makes for a useful overview of all available classes, functions, etc. It's not sufficient by itself as documentation, but it covers an important aspect as reference.

I've had some contact with Docusaurus and from my experience the Sphinx and reStructuredText combo is a much better solution to creating a robust, maintainable, cross-linked-to-nth-degree documentation where you actually can "focus on your content".

Bonus points if you prefer to not deal with the JS ecosystem and prefer Python.

The main downside is that while reST is well-suited for extending the syntax actually writing Sphinx extensions is, subjectively, significantly more arcane than writing React components/MDX plugins.

A recent discussion on this topic, part of the "I prefer rST to Markdown" submission: https://news.ycombinator.com/item?id=41120772

I have been using docusaurus for my tech blog (www.defconq.tech) and it's easy enough to use for a non front end dev.

I chose Docusaurus for the Singapore hackerspace's docs site (https://docs.hackerspace.sg).

My personal opinion when we chose Docusaurus was that it struck the right balance in having just enough batteries included.

It was quick and easy to launch something without having to fiddle with too much config, while allowing some scripting, customisability, and templating through MDX.

It's probably also a good thing that Facebook dogfoods Docusaurus in some places, while keeping it MIT licensed so the community can fork it if Facebook ever decides to stop maintaining it.

It says "optimized", but those pages seems to be very slow. First try on the showcase(!) gives only 55% on performance:

https://pagespeed.web.dev/analysis/https-eightshift-com/c5vu...

There are a lot of these documentation-geared SSGs. I've tried a few and Starlight is what rang least annoying of the bunch. No library lock-in, a sane theme, client-side search, a much smaller dependency tree than many, and quite fast to build.

https://starlight.astro.build/

So how does astro's Starlight compare to it as of Sep 2024? I've invested a bit time to configure Starlight for a new proj but now I'm a bit tempted to switch over

Would love feedbacks from anyone who have been with both Starlight and Docusaurus; thanks!

e.g. are there anything great about Starlight that I should stick to it? SEO-wise, etc.

I wish all those static site generators, and docusaurus alike doc sites, can add a login feature if they do not have one still.

what I want is a simple CMS basically, not as complex as drupal etc, but at least support login to view when I need it.

for some reason most of the docs site themes have anemic support for blogs and if you are developing something you almost always want landing+blog+docs, yet its either fixated on docs or blogs but rarely both. I wonder why?

If you don't like to run javascript outside of a browser, MkDocs is a great Python-based alternative: https://www.mkdocs.org/

I love Docusaurus. I use it for personal web projects as a static site. There's a surprising number of sites I see nowadays that you can tell are also built on Docusaurus.

we use Docusarus at work for our internal documentation sites and its okay. It gets the job done and it beats manually making a nice website for docs by hand

Maybe not fitting to mention that here, but Typora still doesn't support .mdx files out of the box. This makes maintaining docusaurus sites a hassle.

Sounds really interesting to build it with Markdown that's cool, especially to make web pages thanks to AI ^^. Thanks for sharing this.

Why are there so many site publishing solutions? Is it that good of a business? Is it advantageous to smaller players?

When I see React in 2024 I get uncomfortable.

I use Docusaurus for my software development wiki (knowledge base): https://albert.wiki

It works very well for this purpose. I didn't bother to change the default UI though. And I haven't added any search mechanism (I keep the content organized, thus I don't need it much). It has a blog feature, but I don't use it.

It's hosted in Netlify, deploying automatically on each push.

Here's the source code if you are curious: https://github.com/AlbertVilaCalvo/Wiki