I'm so happy with Material Mkdocs[1]. I use Obsidian to write a bunch of notes and then combine that with a bunch of mkdocs plugins to generate a static site out of it [2].
What does Docusaurus offer more, if anyone who's used both can compare?
As the Docusaurus site maintainer, I believe MkDocs is great (and probably simpler) but our plugin system is more powerful, MDX/React makes it easier to make the docs interactive, and we have more flexibility for theming.
All those sites are customized, they do not look like a stock template. You don't need to be Stripe anymore (with a full engineering team) to get a beautiful and interactive docs website
I personally wanted to use docuensarus, but since I'm more in infrastructure and not in development, I found mkdocs with mkdocs-material to just be easier to use.
Docusaurus is similar: you don't need to code anything, and can start with a config file + a folder of Markdown files.
The only difference is that our config file is a .js file instead of .yaml, which I'd say is more powerful since you can do fancy things like reading env variables to make your config "dynamic".
But by default a Docusaurus config file is not too complex. Probably a bit more than MkDocs (as we keep some boilerplate on purpose so that you can just tweak it) but still not really requiring to be a JS developer to edit. See: https://github.com/facebook/docusaurus/blob/main/examples/cl...
Thanks. Will definitely check it out next time I want to switch doc systems :)
Also I always ask — does docusaurus support MathJax and such in the doc strings? (Material MkDocs(strings) does )
Those are all in the carousel of our blog post, which include many more.
Really tried hard to highlight the fact that you can truly customize your docs site with Docusaurus ;) custom navbar, footer, layout, sidebars... everything
We provide a "docusaurus deploy" tool to deploy on GitHub pages but it is more work to setup the GH Action CI than using a good static hosting solution
---
Regarding Obsidian, we don't provide an official integration with it, and IMHO Obsidian is only the "markdown authoring experience". Similarly you can use another tool like VSCode, Sublime or Intellij.
What I would do:
- Author md in Obsidian
- Sync Obsidian vault md to GitHub using https://github.com/denolehov/obsidian-git
- Setup Vercel/Netlify to deploy my doc site from the GitHub repo
Note: we don't support Obsidian bi-directional linking such as [[xyz]], as this is not part of the CommonMark spec. But I definitively want to support something like that as well in the future, as I'm interested to create my own second brain / digital garden using Obsidian and put it online with Docusaurus. This way Docusaurus could become a free competitor to Obsidian Publish.
I introduced Docusaurus as the way to finally unite all documentation for our project and it has been a huge success.
Our project consists of many components and we used to have a bunch of md files scattered around. Due to the MD-native nature of Docusaurus migrating from that to a Docusaurus site was really easy.
Even though a lot of customization is possible, the default theme is a great start and made our docs looks much more polished.
The thing I liked the most is that it's now a lot easier to contribute to it, and a lot of internal and external developers are adding content to it, which at the end of the day, is the important part.
Last, y discovered unDraw (https://undraw.co) through Docusaurus and it has been an invaluable resource!
Plenty of comments wondering if you need all of these features to build good docs. You don’t. What you might find is that once you’ve built a good docs site, you need a small customisation. Maybe an in-line code sample runner. Maybe you’d like to make it more SEO friendly. Or search.
Again, any of these features can be built. If you enjoy building just what you need, go ahead.
What Docusaurus offers is all of these features pre-built. You’ll have access to the solution as soon as you encounter the problem.
What I found out is that because Docusaurus is so popular, you get a form of standardization across docs. I can go from React Native docs to Redux docs to TailwindCSS docs and I've already got a solid idea of where everything will be because its a docusarus site.
One thing in particular is that Docusarus has the CMD + K command to do a search, it's so nice being able to go to all the different sites for docs and have the UI work in exactly the same way.
if i have 1 piece of feedback about docusaurus docsearch, it is that doing faceted search (eg to filter for languages, or library versions) is not at all documented. i've tried multiple times and failed. if someone from Algolia is reading this, we could really use your help there, it would greatly increase the experience of all docs via docusaurus and improve Algolia integration.
Yes that's the value prop of Docusaurus: you can get started in 5 minutes, but the tool scales well with your usage if you need something more advanced
Been using Docusaurus for quite a while to spin up little documentation sites to share with people. Had somewhat given up hope on version 2 as so many features had piled up and it looked like it had become unmanageable. Good effort for getting through it all.
I would say though that part of what appealed to me does seem to be getting lost - the simplicity. I know you don't have to use all the features and v1 is still around, but it is becoming a bit of a buzzword beast.
Yes Docusaurus v2 is more featured and powerful than v1. I understand simplicity is an advantage and sometimes less feature is actually better.
We aim for site owners that want to start simple, and yet scale their site to more advanced needs. If you plan to start simple and stay simple, other tools are probably good enough for sure.
That's not really fair: that's because I included a lot of images in the blog post in carousel. I admit it's not great and I didn't have time to optimize deeply these custom image carousels for the launch to load hidden slides more lazily.
It's not the case for all other docs pages though, and we bet on progressive enhancement, so most of those things should also work if you disable JS and load less things.
Also we have link prefetching so that navigating to links appearing viewport will be immediate, but it will also load some data when links enter viewport. In our experience, these techniques to load resources a bit more eagerly produces a better UX. Would you reject a PWA, just because it loads more data upfront? No because after that you can eventually use the app offline.
Go to a regular doc page (not overcrowded with images) and disable JS: you'll see much less traffic, and the site remains usable. For example go to: https://docusaurus.io/docs/cli
If you are looking for a similar markdown-to-docs-site tool but don't want to run javascript outside of a browser, MkDocs is great: https://www.mkdocs.org/
Why wouldn't you want to run JS outside of a browser?
That looks like rejecting Node.js for Python.
I also think MkDocs is great (and I'm the Docusaurus maintainer), and probably even simpler, but IMHO Docusaurus is more flexible and customizable that MkDocs.
We have seen greatly customized Docusaurus docs site, looking very different one from another. The MkDocs sites I see in the wild usually looks quite the same (often using Material for MkDocs).
Not OP, but I was looking for documentation-oriented static site generator some time ago. In my experience:
* There's usually mess in documentation for JS-based ones. For eg. "quick start" section of the docs uses npx. Then full installation manual uses entirely different commands. JS is not my main technology so it's very confusing.
* Builds tend to be significantly slower when npm is involved.
* Plugins and themes very often have compatibility issues.
* They tend to use mdx, which is not necessarily very well supported outside of JS world and some solutions break when you try to bring your existing markdown.
I'm aware that:
* None of this is inherently JS property.
* Docusaurus is actually not guilty of most of these issues and I would recommend it.
* Probably it all makes sense/is avoidable, when you work with this ecosystem often.
However I'm just trying to setup documentation page, not start new carrer patch and non-JS based solutions are usually better on understanding that.
> Why wouldn't you want to run JS outside of a browser?
Not OP, but as someone working on backend, infra, and some part time game dev, JS isn't in my skillset in any meaningful way so I don't use tools within that ecosystem if I can avoid it.
> IMHO Docusaurus is more flexible and customizable that MkDocs.
Presumably only if you're comfortable working in JS?
Hey there!
I am the current Docusaurus lead maintainer, if you have any question let me know.
You don't need to be Stripe and have a full engineering team working on your doc to make it awesome.
Docusaurus is a content-centric static site generator based on Node.js and React. You can build a documentation site but also a blog, landing pages...
The idea is that you just write Markdown files, and we generate a great docs site for you. You can get started in 5 minutes, focusing on content, and later do more advanced customizations so that your docs are top-notch.
I like to compare Docusaurus to the Pareto principle: you only need 20% of the effort to get 80% of the result. Docusaurus is flexible so you can also decide to invest more and get a better result.
It is based on MDX (Markdown + React), which can help make your docs interactive.
Some comparable tools: VuePress, MkDocs...
I believe we do a better job than others: more features but also great flexibility. In particular you can deeply customize the UI so that your documentation site really respects respects your branding.
We have also see adoption for internal documentation at Microsoft, LinkedIn, Shopify...
We have a site showcase with almost 300 sites in case you are looking for inspirations.
> With Docusaurus we are looking to compete with top notch documentations, not simple ones.
> Do you truly believe that your home-made setup would be sufficient to output a top-notch doc site?
> I doubt these companies would be satisfied with a home-made setup like yours.
> I'm not sure why you went through all this pain, but if you don't report it, how can we fix it? Others do not have the same experience afaik.
Your combative attitude throughout your comments here has really put me off trying Docusaurus. You don’t have to lash out at people who prefer an alternative approach.
I shouldn't have used the word "toy" but I mean it. I really dislike tools such as Docsify or MDWiki and can clearly back this up: those tools rely way too much on JS, are not "progressively enhanced", are bad for SEO, accessibility... they have their little use-cases but you should IMHO avoid them in most cases if you are looking for building anything serious.
Other tools such as VitePress, VuePress, MkDocs, Nextra... are all great sane competitors of Docusaurus.
I just believe that Docusaurus is more featured and flexible, that's all.
These other tools have other advantages that Docusaurus do not always have, but I claim the right to defend Docusaurus where it really shines.
Sometimes being less featured is an actual advantage (simplicity). Sometimes being built on another platform (Nextra using Next.js, Dokz using Gatsby), frontend framework (VuePress, VitePress using Vue.js...) or language (MkDocs using Python) is another advantage.
I understand that my words might look offensive, and sorry for that. Please also take into consideration my feelings when you compare a 1 day home-made setup with a project being worked on since 2018.
> I just believe that Docusaurus is more featured and flexible, that's all.
That’s not the problem. This is the problem:
> they have their little use-cases
If you look at what other people in this thread are doing when they are comparing other tools to yours favourably, they are talking about what Docusaurus does better.
When you reply to somebody comparing other tools to yours unfavourably, you jump to belittling the other tool.
It gives a really bad impression of Docusaurus that, when you think about it in relation to other tools, you aren’t thinking of what Docusaurus does well, but immediately try to belittle the alternative in some way. Docusaurus can’t be all that great if the best things you can think of are insults about some other tool.
The most convincing comments in favour of Docusaurus are coming from everybody but you. I don’t think that’s what you are trying to achieve with your comments here is it?
I'm not belittling all other tools, just MdWiki (and Docsify that I consider in the same category of client-side JS, hash-based docs tool).
All the other docs tools are great too, and I'm not saying Docusaurus is better. I believe Docusaurus can scale from small sites to very advanced doc sites with minimal effort.
If I were a Python dev looking for something simple but that remains quite flexible, I'd definitively try MkDocs.
If I were a Vue dev I'd try first VitePress/VuePress before Docusaurus. It has less features but a great UI design, some convenient Md features, and it's convenient for a Vue dev/team to reuse their existing VueJS knowledge.
If I had a Next.js site and wanted to integrate docs feature in the same site, I would try Nextra.
Really, apart my comment on MdWiki (which I still stand by: most of you shouldn't use it), I think I'm fair with all the other tools?
My comments are all authentic and nobody at Meta proofread anything. I'm not even a Meta employee myself, just an external contractor working on Docusaurus.
> You can display real production source code in code blocks in any language without having to copy-paste and it can stay in sync.
I've never tracked down the docs for doing that (e.g. including lines 31-34 from ../../src/path/to/library.py in the documentation and keeping it in sync as that expands to lines 31-36) - can you point me to them?
Since you are welcoming questions, you can save me the documentation search:
My use case involves documentation for, e.g., a software library that can be used in different languages/frameworks. The documentation is the same, but then we provide examples is different languages and we're looking for a way of elegantly presenting this.
Do you support any way of marking the original markdown so that a "switch" from the UI can present one of alternative parts?
I apologize if that is not clear -- and asking about a custom use case.
But really, MDX gives you the freedom to implement your own tabs system. See for example how Courier is documenting usage of an API with multiple languages: https://www.courier.com/docs/reference/send/message/
You can even have SDKs that have different lifecycles (for example MyProduct-Android-1.4 vs MyProduct-iOS-2.6)
And finally you can build an abstraction on top of Docusaurus so that you have one separate doc per product and yet all your product docs look the same:
- https://xsoar.pan.dev
- https://prisma.pan.dev/
I'm actually using it for both docs and marketing pages. It's so nice to be able to easily link between pages as it's all the one site. And I'm not even a JavaScript developer. Thanks for your hard work!
Also, I'd love to see a theme marketplace. I'm also not a designer and would pay for pro designs (especially landing pages). Check out mui, that's what they do (open source but with marketplace).
We are definitively interested to provide more themes in the future, starting with a TailwindCSS one.
I also believe the Tailwind ecosystem provides a lot of useful copy/pastable code snippets (including full landing pages) so having a Tailwind theme might help reuse the output produced for Tailwind.
Curious to know more about what you are looking for
I doubt we'll ever officially provide an official integration for YUI but rather we'll let the community provide one: it's difficult for a small team to be exhaustive and provide first-class integrations for all languages/tools.
Our plugin ecosystem should be good enough to enable you to build it in userland. If that's not the case, please let us know.
I was hoping for something I could use to generate my docs, but this is so incredibly over-engineered it's comical to me. React components, MDX, TypeScript config files, CSS-in-JS? Do you really need all that to write docs?
I have my own little markdown-to-html static site generator that does nearly everything I would ever need, and it only uses a small library for conversion MD to html plus a custom, very simple templating language to do things like include other files or get a list of files in another dir so you can create a list of links... and that's it. You can probably write one yourself on a weekend. I will be sticking with my own, thanks.
You don’t need it to write docs. But, as someone who’s worked in a relatively large documentation org… it’s nice to have a stable, extensible base that you can extend consistently across multiple docs sites. It’s ideal to have a similar look and feel, but the flexibility to tweak that for each product.
Basic docs sites can literally just be HTML. But the more you maintain them, the more you want to experiment with novel methods of documentation (think: interactive consoles, new methods of styling guides and tutorials like Apple’s SwiftUI docs, or even new methods of segmenting content within a single docs site (SDK and versioning selectors, anyone?))… eventually, simple tools will hold you back. Or you’ll end up building an unmaintainable nightmare on top of a simple tool. In those cases, it’s nice to use a “batteries included” product so you don’t have to write all of that infrastructure yourself.
For personal blogs and small docs sites, it’s overkill of course. But in docs land just as in developer land, ICs want to build new skills for their resumes or personal interest.
And, of course… it has a built in dark mode! Harder to find than you’d think.
Agree Docusaurus might be overkill for simple docs, however we also made sure the experience for simple usage is great.
It comes with file-system routing convention, versioning, accessibility, internationalization, good SEO by default and many useful features that would take time to build in userland...
Palo Alto Networks has a dev portal with multiple products using Docusaurus, all sharing similarities but with tweaks per product:
- https://xsoar.pan.dev/
- https://prisma.pan.dev/
I thought so, too. I've switched to mdbook[1], which is more lightweight, and (at least at the time) was one of the few solutions that compiled down to a directory that can be used without limitations while offline.
I'm sure that Docusaurus can do a lot, and more in the future. I think the resulting pages feel a little heavy to use (how they load and react in a browser), but that's just my personal opinion.
I had tried to find a tool that would be simple, quick to use, and as close to a static HTML page as possible while still retaining a "book" character. Even a Vimwiki HTML export would have been an option, were Vimwiki's Markdown support better. Mdbooks fit the bill, and does not seem to stray too much from that initial direction, as far as I can tell.
Just curious whether rust is an advantage for this sort of a tool? I don't know much about rust but my impression is that it's a systems language like C/C++. Is security a major problem for this sort of a build tool? It just seems like of I were writing something that processes text using a C/C++ class language isn't going to maintain well or be easy to adapt, extend or customize.
IMHO Rust is useful for its speed. Many frontend tools use Rust today (like swc, napi-rs...).
We are willing to include Rust in Docusaurus in the future (alongside Node.js), as it can help to build the static doc site faster. BTW our docusaurus prod site (docusaurus.io) is built using swc already (https://swc.rs/)
Now using a 100% Rust tool to build a doc site would be great too, but at the end of the day if you want a great experience you'll also need some JS and not just plain static HTML files. And Rust devs are more likely less "frontend-y" (I've been a backend Scala dev 10 years ago, I know how good looking UIs are produced by backend devs ^^). So I guess a combination of Node.js + Rust is great, and the frontend community that care about UI/UX is more likely to contribute to the JS side to polish things.
I guess I'm just thinking in terms of these tools as being text in, text out transformers. And it seems like an embarassingly parallel workload. So speed seems like the wrong thing to optimize to me.
Time required for customization, feature implementation and maintenance should be minimized. Documentation generation often needs to be extended and customized. So the question is how much developer time gets sunk into adapting the tooling vs buying CPU time.
We optimize for features, easy of customization and easy of upgrades in priority
Now we have large docs sites with thousands of pages, and it's painful if their static site takes forever to build, so we should also optimize for speed. Build-time speed reduces the feedback loop and it also saves developer time. It's like having a better computer somehow.
I'm confused. Is docusaurus implemented in a system's programming language such as rust or C/C++? Wouldn't the easiest way to improve build time be to get a parallel build system (assuming it doesn't have one) and then throw more CPUs at it?
We build a single page application and use Webpack (nodejs build tool to create SPAs). In 2018 there weren't many alternatives to Webpack so we pick that, but may reconsider in the future. We don't have the bandwidth to create our own frontend build tool, we focus on the features.
Docusaurus is also IO intensive as we read a lot of markdown files on the disk and also emit intermediate files.
Webpack already builds things in parallel, but it remains nodejs, and IO/CPU are both bottlenecks at different steps of our build.
No idea, actually (not a Rust developer myself). What I have noticed is that Rust seems to provide good tooling for building monolithic executables that contain a complete application, including assets. That's quite nice for trying stuff out or managing a few of those without a package manager, but has nothing to do with documentation generation per se.
Oh, that's nice and I do agree about that! I've noticed go does that sort of thing, too (hugo, etc).Some of these systems out there include so many moving parts that it's really difficult to just even try them out (i.e. supabase vs pocketbase).
Many companies using it: Supabase, Redis, Figma, Ionic, Snapchat, LinkedIn, Microsoft, Shopify, Tauri... I doubt these companies would be satisfied with a home-made setup like yours.
If you don't have advanced needs, you could as well just publish md files on GitHub?
I wouldn’t worry too much about that comment. The top comment is very much in keeping with the HN tradition of trashing others’ work without fully understanding the use case.
My favourite HN comment went like “For a Linux user, you can already build such a system yourself quite trivially by getting an FTP account, mounting it locally with curlftpfs, and then using SVN or CVS on the mounted filesystem.” (https://news.ycombinator.com/item?id=8863)
Fortunately the person this was addressed to continued building Dropbox.
Well, there's a tool for every task and yours in this case might be too overblown for the simple task that the user is trying to solve. No need to compare it to the use at bigger companies and organizations. No need to either get arrogant or stroppy. Just because a user doesn't use your tool, she is not a hater, neither.
Sound a bit like "But mine is better/bigger/shinier than yours!" to me. Keep cool.
Well, the op was quite offensive in the first place
> this is so incredibly over-engineered it's comical to me.
Isn't it fair that I defend the tool I work on after reading such comment?
The op can stick with its original tool and that's perfectly fine to me. Indeed Docusaurus might be overkill for many simple use-cases.
Does it mean it's over-engineered? Well, that's worth discussing. Some companies really need the features we provide.
Can you build something as advanced as some of the existing Docusaurus sites we showcase, using a simpler stack? That's an interesting discussion to have, but share some links.
Well, I don't see the offensive part here. As you say it yourself: "It might be overkill for many simple use-cases." Period. No need to jump into every thread where a user says that it is just too much for her use case, and you asking for links to compare the output (as you did with me as well?).
Just be happy with what you created and the showcases prove the demand for it. So?
Well, we don't have at all the same definition of what "offensive" means then.
> where a user says that it is just too much for her use case
That's not at all what the op said, just a 2nd reminder:
> > this is so incredibly over-engineered it's comical to me.
The op said it's over-engineered, in general, not for her use-case
---
I am happy with the result and I won't be affected too much by comments from people that criticize what we've built without giving it a try. Now I keep the right to defend the tool when it's criticized this way.
Don't get me wrong... I just like simple things, and this is definitely not simple, so not to my taste... I am sure the majority of people out there will love support for React, TailCSS or whatever else this supports...
But I do believe I am able to write top notch documentation by simply being good at HTML/CSS... because that's what it really goes down to in the end?! How does Docusaurus make things pretty? By using themes? Well, I can copy your theme into my hand-written HTML which then wrapps the markdown content I wrote... I don't think end users would notice any difference whatsoever?
One thing I have difficulty generating is a search toolbox... but that's only because I haven't added the "feature" yet... and as I said: I like to keep things simple.
1 minute: it's what it takes to init a new Docusaurus site and publish it to a prod url with https.
2 minutes: you are already submitting your first doc PR, review it and merge it to deploy to production.
For me, this is simple. I understand this might look complex to you if you come from a different background, but nowadays, frontend devs are used to such workflows.
brabel that's fair, I also like simple things btw.
Can you please share your doc site, so that I can at least know what kind of docs experience you are building?
Tailwind is not something we support atm, and when we'll do it will be optional.
The only choices you cannot opt-out are: Node.js, React, CSS, JavaScript, Markdown/MDX.
The rest is all optional and provided as plugins. You don't need to use TS nor Tailwind, but isn't it nice to be able to use those if you want to?
For sure you can hand write a top-notch doc site using html, css and vanilla JS. You can also write all your programs in assemble/bytecode/machine code if you want, and similarly they could potentially make these programs faster than their C++, Rust, Java equivalent. I doubt this is a great idea, but in the end you are responsible for your choices.
Docusaurus is a tool that will help you achieve the desired result for a lower effort, it's like the Pareto principle.
> Well, I can copy your theme into my hand-written HTML which then wrapps the markdown content I wrote...
Well, it doubt it's as easy as you think it is. We took great care of accessibility, interactivity and many other things that you'd have a hard time copy/pasting.
To me, even if technically it is possible to reproduce such site in Vanilla JS, it would take me a lot of time to do so. Docusaurus only helps you save time to achieve that experience.
> One thing I have difficulty generating is a search toolbox... but that's only because I haven't added the "feature" yet... and as I said: I like to keep things simple.
So you want search or not, it's not clear to me? Because if you don't, then users can't search and that may be a UX/DX problem, and if you do, then your stack becomes more and more complex and you invest a lot of time building it as you pile features one after the other. You could as well bet on Docusaurus in the first place, and use our search plugins to get search for free.
TLDR: if you value your time and plan to scale a bit your doc, Docusaurus is a great choice to me, even if it looks overly engineering for your initial need. Now you can definitively get a similar experience with vanilla JS, if you are willing to invest a lot of hours to make everything work. And there are things that Docusaurus do that you may not even notice by simply looking at the UI, such as make your doc very accessible or providing good SEO by default.
This account is my "anonymous" account, so I can't give you an example of what docs I can create myself... but docs systems I like include asciidoctor[1] and mdbook [2]. Though I find that even those are overkill for my hobby projects at least ... professionally, I prefer to use them anyway because of support/updates and to leave something others can manage themselves later.
> Now you can definitively get a similar experience with vanilla JS
This comment seems to show we come from very different worlds. Why do you believe you need JS to create documentation?? Have you tried writing HTML/CSS without any generator/JS/tools? It's actually pretty easy... Documentation is mostly static, which HTML/CSS was designed to create... and if you want to add a little interactivity here and there (e.g. run this code live) you can just embed something like Codepen.io or even, yes, vanilla JS if really necessary.
I do agree your tool is quite amazing... the fact it takes care of verifying crosslinking, for example, is great... but I hope you do understand that you're using a heavy-weight tool to do something that's usually pretty basic (or maybe you think of docs as something much, much more advanced than what I think of - like the Rust Docs to me are a good example of great docs and I can't even think of why anyone would need anything more advanced - I think you would find that far from advanced? Othewise, you'd agree you can easily write that by hand with HTML/CSS and a little scripting around perhaps to do crosslinking, md-to-html conversion and simple stuff like that).
> I like include asciidoctor[1] and mdbook [2]. Though I find that even those are overkill for my hobby projects at least ...
That's one thing: Docusaurus is not necessary just for hobby projects where the doc only exists for yourself and a few users. It can be used for hobby project but it can also scale for much larger projects where the doc is a critical part of the success of the project, and where the company behind is willing to invest thousands of dollars to have a really great doc. For example, the doc of React-Native is critical for React-Native success: https://reactnative.dev
> I prefer to use them anyway because of support/updates and to leave something others can manage themselves later.
If you have a small project, you can also use Docusaurus in a very simple way, and stick to our stock template (which looks like this: https://tutorial.docusaurus.io/)
The only thing you'll need is to leave a folder of Markdown files to your colleagues, that's all.
I have planned to add a very simple CLI on top of Docusaurus to make it even easier: just run "npx yolodoc ./my-md-docs-folder" and it will build your simple Docusaurus site => No need to install anything, know that it's using React/MDX/TS or whatever: the only thing you'd need is to have Node.js installed (which is not more complicated to install than Python or Ruby btw)
> This comment seems to show we come from very different worlds. Why do you believe you need JS to create documentation??
I don't believe that. I believe you can do everything by hand but at some point when you have thousands of docs pages, you also need to be productive and fall into the pit of success by adopting tools that streamline the docs authoring experience for your doc team. Do you prefer throwing 1000h of your time on your home made solution, or just use Docusaurus and save time, and get a better result for something like 200h? => That's the value proposition of Docusaurus.
Also note that for some accessibility details, you do need to have some JS because using just HTML has its limit. Docusaurus takes great care of accessibility concerns by default for you: progressive enhancement, skip-to-content, aria labels, keyboard navigation, focus rings, semantic html...
> and if you want to add a little interactivity here and there (e.g. run this code live) you can just embed something like Codepen.io or even, yes, vanilla JS if really necessary.
There are many places where you probably want JS in your doc site: collapsible categories, search, tabs to switch SDK languages, mobile drawer menu etc... Using just HTML has its limit.
Now Docusaurus doesn't just bring interactivity to the "layout" but also inside the docs. This makes it possible to build interactive documentation where the experience is natively more "playful"
Using Codepen.io or CodeSandbox inside your doc leads to a subpar experience to what we want to provide with Docusaurus. Those embeds are not native to the website and require a heavy iframe to load.
Also the demo code you maintain would be saved in a separate system which makes long term maintainance more complicated than to colocate example code with actual docs rendering those.
Using an iframe can also reach some sandboxing limits due to browser securities for certain use-cases.
If you are going to build an API client for your REST API (ie have a Stripe-like API docs experience), I doubt you'd be able to get a great DX with iframe embeds. Instead you want the API client to be native, load fast, and integrate nicely with the rest of your docs site layout.
See for example this Courier API client using Docusaurus: the code sample has a sticky positioning and always remains visible: https://www.courier.com/docs/reference/send/message/
It would simply be impossible to get this better UX with an iframe embed.
---
> I do agree your tool is quite amazing... the fact it takes care of verifying crosslinking, for example, is great...
Thanks ;)
> but I hope you do understand that you're using a heavy-weight tool to do something that's usually pretty basic (or maybe you think of docs as something much, much more advanced than what I think of - like the Rust Docs to me are a good example of great docs and I can't even think of why anyone would need anything more advanced - I think you would find that far from advanced?
I think I didn't explain very well, but most of the "complex stack" of Docusaurus is not directly exposed to you. Similarly, do you really care about which libs MdBook is using under the hood? Would you say "MdBook is overly complicated because it's using XYZ as a dependency!"? Docusaurus used React, MDX, Node.js, Remark, Webpack, TypeScript, Infima... All those buzzwords are internal implementation details, and you do not really need to care about them: just write markdown files!
Is one of those 2 commands really more complicated than the other?
"mdbook serve --open" vs "docusaurus start"
Because in both cases, it's what it takes to use the tool: just start it, and focus on writing good content in Markdown files.
Docusaurus can do much more than that, but you can stick to the simpler workflow if you have basic needs. Just watch this 60sec video demo and see how simple it is: https://twitter.com/leeerob/status/1554211061284364290
> Othewise, you'd agree you can easily write that by hand with HTML/CSS and a little scripting around perhaps to do crosslinking, md-to-html conversion and simple stuff like that).
I totally agree with that. I just feel it would be more time consuming than using a dedicated doc tool that already solved this problem for you. It can by MdBook, Docusaurus or whatever else you like. But at the end of the day, you are free to use whatever tool is good for your use case.
I do believe that the default Docusaurus output provide a better UX than the MdBook output, but it is a matter of personal taste I guess. And it's not more complicated: you just give it Markdown files and run a CLI command to build the site. The only major difference for you, as a docs user with relatively simple needs, is that you have to install Node.js instead of Cargo.
My team uses Docusaurus for internal docs. I just had to make my first contribution to that repo the other day, and it was a mess. Docusaurus didn't work from within WSL (well, it mostly worked but every page load crashed when viewing), so switching to native Windows NPM and the several dependencies and installation steps to get it working took about a half hour with the help of a colleague who knew how it worked. And ultimately, it was just so I could write markdown.
The generated docs are nice, to be sure, but I certainly would not go through that pain if I had to go documentation from scratch.
You don't need any of it. It's included in the framework if you want to make your docs more interactive but you can stick to plain text in markdown (like most of these frameworks).
That's why I made https://reactivedoc.com/. You can use it to write interactive documentation in markdown and save it as a simple, self-contained, html+js file.
Now I'm working on v2, with cleaner syntax & more widgets (I want to add an embedded web base terminal to run shell commands), you can see an example here: https://reactivedoc.com/editor/
I think it depends on your end users. If you're building a product for devs, personally, I think it's worth investing in a great docs experience and more 'advanced' features. Docs are going to be one of your most used interfaces. But you should make sure that making docs 'pretty' isn't detracting from usability. If you're making internal docs, then ya, I agree with you, keep it dead simple.
Actually I don't consider Docusaurus as a real investment. altough as a non-Node.js/React dev all this might sound complex, but this is actually the basic stack for many frontend devs today, not something very fancy.
Investing in your docs mean assembling a tech team for a long effort to build a first class experience. I believe you can achieve something almost as good as a full team by having just 1 engineer working on your Docusaurus doc a few hours per week.
> If you're making internal docs, then ya, I agree with you, keep it dead simple.
Internal docs also deserve a great DX. You can use Docusaurus for internal docs, and use our stock template to get started in a few minutes: just write markdown files. We have been reported heavy usage of Docusaurus at Microsoft and LinkedIn for internal documentations for example.
You don't have to do anything to have this DX: just write md files. Maybe you can already feed Docuaurus with your existing md files, and it will just work without any change.
This is not really comparable to Docusaurus: your thing is a little toy to publish documentation online but not really useful to create a great advanced and looking doc site.
Just consider this: your tool requires client-side JS to work. This is very inaccessible and does not respect the progressive enhancement philosophy of the web. A Docusaurus site takes great care of accessibility, and the experience with JS disabled remains good.
Also using JS this way with anchor link routing will likely lead to bad SEO, and a flash of unstyled content which gives a really bad UX.
As the rep for a product: I wouldn't recommend bashing someone's project by calling it a "little toy". It works for them regardless if it looks as "fancy" as yours. Not a positive look for you or your project if this is how you're going to treat others.
Now if you clearly understand the tradeoffs of such tools and still decide to use it, that's fine. What I see in practice is that many decide to use such tool and are not really aware of the tradeoffs they make.
I personally believe being accessible is a mandatory feature for any documentation website framework. But maybe you'll publish the docs just for yourself or a very limited set of persons, in which case you might care less.
At least as a user i find tommica's "toy" much faster and easier on the eyes than the showcase sites in Docusaurus. The only negative is that small visible "reflow" whenever a page loads.
EDIT: the courier and ionic examples linked elsewhere were faster though.
So happy to see Docusaurus hit the big 2.0! I use it to power my blog and it's a tremendous tool. The DX is fantastic and it's open source! I've been able to contribute to it myself. Amazing times!
We use Docusarus at several sites. Can't wait to see what's new in 2.0 release. I've been using beta version for some time now, without any issues. I think that stable version could be only better.
I've been using Docusaurus for a few years now and it's my top choice for making small-mid sized websites. Dark mode out of the boss is a killer feature!
I searched the documentation for "pdf" and did not find anything relevant - is it really true that this is not able to generate a PDF from the written text?
Generating a proper PDF document still seems a very basic requirement for anything that produces documentation.
We do not have a first-class plugin to generate a linear PDF documentation, but are willing to have one. Our plugin lifecycles could enable you to build one, and we might create an official one in the future.
Keep in mind Docusaurus is a good tool to produce interactive docs. A PDF is not very interactive so if you want any interactivity, you'd have to limit yourself to a subset of Docusaurus features.
> Generating only a website for documentation seems like a cultural step back.
No it's actually the trend to have more interactivity. A linear PDF is more like old-school. Don't you like that on the Stripe docs there's a built-in API client?
Supporting PDFs remains useful but it's more an edge case than the main feature of Docusaurus. We have some users willing to edit books using Docusaurus, but most users do want interactivity, and it's definitively a step forward.
Print it, read it in an (e-ink) ebook reader or whatever. Many people do not feel comfortable reading from a monitor screen. Also book-like PDFs tend to focus on the content instead of the surrounding chrome like navigator menus or whatever, so they can be used like that too (though an epub would probably be better for that - and the ebook reader too).
Docusaurus wants to make the docs interactive to produce a great reading experience. How can we provide that and yet print on PDF?
Remember Docusaurus input remains markdown files so you can still look for another tool that is able to generate a PDF from the same folder of existing markdown files.
We'll likely support producing a PDF but it's not the main value proposition of Docusaurus, just a nice to have for those that really want a linear static PDF instead of a beautiful and interactive doc site.
I don't know GitBook well but GitBook is probably less flexible, but their main advantage is likely that they are less developer centric than Docusaurus. They offer a managed service and content updates can be sent without commiting markdown files to a Git repository.
Docusaurus does not come up with anything to author Markdown files: you'd have to figure your authoring experience yourself, using a CMS (git-based or not), VSCode, GitHub UI, Obsidian, it's up to you...
The thing I want most as a user of docs is the option to download a PDF.
When I’m learning something new, I’ll print out some basic stuff and it makes it so much easier to learn. I go sit in a chair, read through it, and mark it up.
Sorry to disappoint but Docusaurus does not provide that out of the box, however some devs built that as community plugins, but can't tell how qualitative it is.
We believe a documentation can be much better when it's made interactive, so Docusaurus favor interactive experiences over generating a static PDF export. But we'd like to support PDF exorts in the future to please people like you that might have a different opinion
Congrats on the launch! It’s been a long time coming (4 years, wow). It’s extremely common to see docs sites built with Docusaurus today – quite an impact y’all have had!
Docusaurus is very similar to VitePress, VuePress, MkDocs, Nextra, Dokz, Docus... all those tools allow you to focus on content.
I believe we have much more features and more flexibility to customize your site in Docusaurus, but other tools are great too if you look for something simpler. Our showcase (and launch blog post) references great looking Docusaurus websites that would be hard (if not impossible) to build with the other tools.
Afaik Astro has a docs starter template but it's more a boilerplate that you have to maintain after initialization, so not really comparable with the tools above.
Note that we also want to explore if Docusaurus could run on top of Next.js, Gatsby, Remix, and eventually become framework-agnostic.
The Docusaurus team is relatively small, and can't really compete with Vercel/Next.js on the static site generator infra, build performance etc... Until now we mostly focused on implementing a good set of flexible docs feature.
The downsides of a SPA is that using React client-side is more heavy than plan static html files with vanilla JS. It has a cost on the amount of JS to initially download, and executing that JS.
We believe React enables a better UX, and this weight is worth it for multiple reasons (SPA navigation, prefetching, and upcoming things).
You can compare for yourself and see what's best: docusaurus.io (SPA/React) vs v1.docusaurus.io (MPA/vanillaJS)
Note we didn't upgrade to React 18 yet, which will reduce the cost of using React client side, and provide new interesting concurrent features like progressive hydratation. We also want to leverage React Server Components later. We could also explore using Preact.
The web APIs are also constantly evolving, with new page transition APIs and things like that. It's not impossible we move back to a MPA in the (long term) future if it makes sense.
You can restrict docs access by using Http basic auth at the host level (CDNs like Vercel/Netlify/Cloudflare usually provide this feature).
If you want in-app authentication, remember we are a static site generator so at the end of the day we have to produce static html files, and at build time we can't know which user it is. You can use a client-side authentication where your HTML first render a profile placeholder and then the profile data gets loaded with an auth request. You can also render a full-screen spinner on the static page, and then use React client-side to auth the user.
has been a very very long journey, but Docusaurus has rightfully earned its place as the default docs engine for most dev focused companies and startups and OSS libraries. huge congrats to you for shepherding this through AND consistently updating users through the process so that we did not lose confidence. Congrats!
Docusaurus has been quite inspired by Gatsby and Next.js.
We simple removed the GraphQL data later from Docusaurus, and are more opinionated toward the docs use-case while Gatsby is a more generic tool focusing a lot on CMS integration. We are more developer-centric and based on Git by default.
Even if you don't like Meta, is that a good reason to reject Docusaurus? It's not really related to the Facebook product in anyway, it's MIT, free, open-source, and does not have any tracking visitor/dev tracking.
What does Docusaurus offer more, if anyone who's used both can compare?
[1]: https://squidfunk.github.io/mkdocs-material/
[2]: https://github.com/mr-karan/notes