231 karma · joined January 20, 2016
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.
I think I'm quite fair with other tools.
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.
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.
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?
How are we supposed to render this Docusaurus page on a PDF exactly? https://www.courier.com/docs/reference/send/message/
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.
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
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.
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.
Here's for example a plugin that integrates with TypeDoc (TS): https://www.npmjs.com/package/docusaurus-plugin-typedoc
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.
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
The stable release is not very different from the latest betas: it's mostly our commitment to respect Semantic Versioning for the next releases.
Just sharing your blog url for the interested: https://blog.johnnyreilly.com/
We also have a lot of other personal website/blogs in our site showcase: https://docusaurus.io/showcase?tags=personal
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.
See also: https://github.com/facebook/docusaurus/issues/958#issuecomme...
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.
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
Really tried hard to highlight the fact that you can truly customize your docs site with Docusaurus ;) custom navbar, footer, layout, sidebars... everything
We have seen many examples of Docusaurus sites generating pages from code comments, GraphQL or OpenAPI schemas
For example here's a plugin that does something akin to what you want, but from TS comments: https://www.npmjs.com/package/docusaurus-plugin-typedoc
And here is an example integration of Redoc/OpenAPI in Docusaurus: https://redocusaurus.vercel.app/examples/using-single-yaml/
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.
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.
You just write markdown files. Eventually you create a custom landing page with React (optional, we also support a Markdown landing page).
If you want to customize your site, you can use more advanced tools, but really you can stick to Markdown if you want something simple.
Now Docusaurus uses advanced things under the hood, but it's an implementation detail, not something you really have to deal with.
Just try it and see: docusaurus.new
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...
We have many devs using Docusaurus as a portfolio or personal blog, we even have a dedicated showcase tag for that: https://docusaurus.io/showcase?tags=personal
For advanced needs, like multi-sdk support, we get you covered.
Site with multiple frontend SDKs (React, Angular...): https://docs.dyte.io/react-ui-kit
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/
With MDX you can embed JS and/or React in Markdown already
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pw...
We'll look into more "offline supports" in the future including producing pdf files etc (it already exists but as community plugins)
The goal is not only to get some html files online but also to great a first-class experience for the end user.
Do you truly believe that your home-made setup would be sufficient to output a top-notch doc site?
Really curious to see what kind of site your setup produce, can you share a live url so that we can compare?
Docusaurus v2 has a site showcase with many great looking sites: https://docusaurus.io/showcase
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?
docusaurus.new
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.