Docusaurus – Build optimized websites quickly, focus on your content | Hacker News Reader

Docusaurus – Build optimized websites quickly, focus on your content

docusaurus.io

175 pointsyamrzou47 comments

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

Oh, Reilly? He should write a book. :)

I like it too but it doesn’t have auto-docs based on docstrings, which Material for MkDocs has:

https://github.com/mkdocstrings/mkdocstrings

This post in particular helped me fix seo as well for https://appraisalinbox.com (the design still needs a lot of love).

These days I'd probably start off using astro for a static site. They've got a docs starter, too.

Aww man I hate clicking on a result on google, taking me to a pagination page where the content I'm looking for is no longer on that page.

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 actually wrote a kotlin library (https://github.com/jillesvangurp/kotlin4example) a while ago to help me write documentation that is generated from code that actually compiles and runs.

Instead of embedding code in markdown, I actually generate the markdown from code. Which with Kotlin is easy because you can write your own DSLs. And I get to refactor my code and documentation at the same time. It has some other nifty features like capturing output that you can show in the Markdown and a few other things.

If you want to see it in action, check out the documentation for my kt-search project. There are probably a lot of other libraries out there that do similar things. But it's a thing that most projects don't seem to rely on for their documentation. And breaking code samples are a major hurdle for writing documentation to begin with.

I find that addressing that gets you in a mode where you are documenting things by default. And good documentation also reveals design flaws because you are kind of forced to eat your own dog food by writing working code that shows how you would use a particular feature. I'm basically constantly trying to make life easier for both myself and my users.

Reminds me of Knuth's literate programming: https://www-cs-faculty.stanford.edu/~knuth/lp.html

That was a direct inspiration.

I wrote a ton of custom code to do this for iommi (example: https://docs.iommi.rocks/en/latest/tutorial.html). I went further than any other library I've seen and made it so that the views in the examples produce static html files that are embedded in the resulting output via iframes.

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

Mkdocs-material has been my go to for this use case. However, I once made a document website using MDbook(the thing that Rust uses for their own documentation and book), and have a lot of happy consumers.

Are there any good open source documentation chatbots that you can integrate into the search function of docusaurus? If you see commercial offerings like mintlify, they all come with a Q and A chatbot built-in. It’s not very hard to build, you just need to generate the RAG chunks at build-time but this is best implemented as part of the documentation software, rather than as a third party plugin since it heavily ties into the search feature.

+1! I'd love to know, too!

mkdocs-material is fine if you prefer Python to JS, but I personally very much dislike how it looks, and as everything else it uses a weird custom Markdown flavor where indentation is handled weirdly which can create edge-cases where for example a valid GFM list is not rendered properly by MkDocs.

+1 on Starlight, though, it is my go-to and I absolutely love it.

What makes starlight heavier? If anything its the opposite, it's not client side rendering pages like Docusaurus... https://starlight.astro.build/environmental-impact/

Likewise, I've been happy with Starlight and trust Astro products to be lightweight and efficient. I'm interested in knowing what makes it heavier

The comparisons-page clearly highlights that Docusaurus is way heavier. https://starlight.astro.build/environmental-impact/#comparis...

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!

Hey John, thanks for your contributions! Also gotta give a big shoutout to Sébastien and the crew for creating and constantly updating Docusaurus - it's one of my favorite docs software.

Are there any wishlist features? Looking for a solution for a wiki and this looks super promising.

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.

Glad to hear it's work without a front-end development background.

Yeah, it's great for non-front-end folks! The default themes look pretty good, and you can use a bunch of pre-made components right in your markdown.

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.

Why are you tempted? Personally, I like Starlight's use of web components. It is much more lightweight and since it is based on Astro, you can use whatever framework you want / need.

thanks for the assurance ;) I will stick to it then, since I’ve already spent time to look into its internal APIs too

I guess I’m just tempted because Docusaurus looks really nice

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?

Because it's trivial to mix-and-match specialized products in a single project. It's trivial to install docusaurus, and a ssg like eleventy in the same project, and configure it so that they have some shared components by setting configuration details to point to the right directory, all within one repo, same package manager, etc.

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?

They're relatively easy to make.

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

Reply on news.ycombinator.com