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
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.
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
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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
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.
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