12 ms·

Docusaurus 2.0

202 points by slorber 4y ago

johnny_reilly 4y ago
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!
- slorber 4y ago
  Thanks a lot Johnny Just sharing your blog url for the interested: https://blog.johnnyreilly.com/ https://blog.johnnyreilly.com/ We also have a lot of other personal website/blogs in our site showcase: https://docusaurus.io/showcase?tags=personal https://docusaurus.io/showcase?tags=personal
slorber 4y ago
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. Full-featured: docs, blog, pages, plugins, themes, versioning, i18n, a11y, SEO... 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. Docusaurus 2.0 has already been widely adopted by the community during the beta phase. Some examples - https://www.figma.com/plugin-docs/ https://www.figma.com/plugin-docs/ - https://docs.snap.com/ https://docs.snap.com/ - https://reactnative.dev/ https://reactnative.dev/ - https://supabase.com/docs https://supabase.com/docs - https://ionic.io/docs https://ionic.io/docs - https://developer.stackblitz.com/ https://developer.stackblitz.com/ - https://tauri.app/ https://tauri.app/ - https://hasura.io/docs/latest/index/ https://hasura.io/docs/latest/index/ - https://docs.lacework.com/ https://docs.lacework.com/ - https://wiki.iota.org/ https://wiki.iota.org/ - https://docs.solana.com/ https://docs.solana.com/ 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.
- cpursley 4y ago
  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).
  - slorber 4y ago
    Hey, thanks for your feedback 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
    - cpursley 4y ago
      Tailwind or something like it sounds good.
- EGreg 4y ago
  How can we transform our DocBlock or YUIDoc comments in PHP and JS code, into beautiful hyperlinked documentation? Now THAT would be something!
  - slorber 4y ago
    We don't integrate Docusaurus with such tools atm but you can build a Docusaurus plugin that would allow to integrate with such tools. Here's for example a plugin that integrates with TypeDoc (TS): https://www.npmjs.com/package/docusaurus-plugin-typedoc 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.
yangshun 4y ago
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!
taubek 4y ago
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.
- slorber 4y ago
  Thanks for the feedback ;) The stable release is not very different from the latest betas: it's mostly our commitment to respect Semantic Versioning for the next releases.
stuaxo 4y ago
Think I'll leave it for a while, Meta is so poisonous.
- slorber 4y ago
  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.
  - inferiorhuman 4y ago
    Even if you don't like Meta, is that a good reason to reject Docusaurus? Yes
brycewray 4y ago
Scroll up and down that page and you see about 30 MB of resources downloaded. Yikes.
- slorber 4y ago
  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 https://docusaurus.io/docs/cli
  - michaelmcdonald 4y ago
    For the lazy: the above referenced page by @slorber only had 1.3MB of resources to load (with JS enabled).
    - slorber 4y ago
      Thanks :) that's more fair, but I admit it's still too much, and we are definitively looking forward to improve the amount of JS needed in the future! Some new features in React 18 (and upcoming releases) like Server Components are going to have a great impact on Docusaurus
brabel 4y ago
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.
- rat9988 4y ago
  React components, MDX, TypeScript config files, CSS-in-JS? Do you really need all that to write docs? No you don't, you only need to write the markdown.
  - slorber 4y ago
    Yes, and that's exactly the value proposition of Docusaurus. 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
- manigandham 4y ago
  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).
- tommica 4y ago
  I use this to run my project docs, no compiling, just one index.html and the rest are markdown files: http://dynalon.github.io/mdwiki/#!index.md http://dynalon.github.io/mdwiki/#!index.md
Danborg 4y ago
Reminds me of Gatsby.
- mhoad 4y ago
  Not a compliment I assume?
- slorber 4y ago
  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.
POPOSYS 4y ago
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. I am sure I am missing something?
- deleted 4y ago
  [deleted]
- mooreds 4y ago
  https://www.npmjs.com/package/docusaurus-pdf https://www.npmjs.com/package/docusaurus-pdf looks useful. Unclear which version this supports, however. (Not a user of docusaurous, YMMV).
  - POPOSYS 4y ago
    Sorry, but did you look at the example document? Could you really provide such a result to some serious documentation project? I guess not.
    - mooreds 4y ago
      I did not do more than google a bit and share the link.
- TobbenTM 4y ago
  If you hit the print button, the print layout is pretty good, pretty much ready to print to PDF if you ask me!
  - POPOSYS 4y ago
    I do not see any print button - dou you mean web browser print "button"? I did that - the resulting pdf can not be presented as documentation. It is not satisfying even the most moderate requirements for a documentation pdf. Generating only a website for documentation seems like a cultural step back.
tweetle_beetle 4y ago
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.
- slorber 4y ago
  Thanks for the feedback 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.
sixhobbits 4y ago
This post is pretty well written but having so many words and phrases in bold text made it annoying for me to read.
- slorber 4y ago
  Sorry about that you are not the first to tell me I use too much bold. Will remember for next time
mr-karan 4y ago
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? [1]: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/ [2]: https://github.com/mr-karan/notes https://github.com/mr-karan/notes
- d4rkp4ttern 4y ago
  Material MkDocs is fantastic. Combine it with MkDocStrings and you can get auto-documented code via docstrings (at least for python )
  - slorber 4y ago
    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. See the carousel of site screenshots here: https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0#theming https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-... I'm curious to see highly customized MkDocs sites that truly respect your branding. What I mean by respecting your branding: - Courier: https://www.courier.com/docs/ https://www.courier.com/docs/ - Figma: https://www.figma.com/plugin-docs/ https://www.figma.com/plugin-docs/ - Iota: https://wiki.iota.org/ https://wiki.iota.org/ - Hasura: https://hasura.io/docs/latest/index/ https://hasura.io/docs/latest/index/ - Ionic: https://ionicframework.com/docs https://ionicframework.com/docs - Quickwit: https://quickwit.io/docs/ https://quickwit.io/docs/ 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
    - mr-karan 4y ago
      Amazing, thanks for your response. I'll explore Docusaurus 2.0 :) Congrats on the release.
ruuda 4y ago
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/ https://www.mkdocs.org/
- slorber 4y ago
  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). See some greatly customized Docusaurus sites here: https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0#theming https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-... I'd be curious if you could show me some MkDocs sites with that level of customization
  - stonith 4y ago
    > 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?
    - slorber 4y ago
      100% agree, if you are familiar with Python, just try MkDocs first and see if it works for you.
  - dzikimarian 4y ago
    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.
jerrygoyal 4y ago
can I add authentication on top of it to restrict docs access to logged-in users?
- slorber 4y ago
  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. See also: https://github.com/facebook/docusaurus/issues/958#issuecomment-1057075925 https://github.com/facebook/docusaurus/issues/958#issuecomme...
  - leerob 4y ago
    If you’re using Vercel, here’s an example: https://github.com/vercel/examples/tree/main/edge-functions/basic-auth-password https://github.com/vercel/examples/tree/main/edge-functions/...
nindalf 4y ago
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.
- slorber 4y ago
  Thanks nindalf! 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
- _fat_santa 4y ago
  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.
  - slorber 4y ago
    Thanks for the feedback To be fair what you describe is more a side-result of our community rather than our own features. CMD+K is a popular shortcut. It's not built-in Algolia DocSearch modal. Also other frameworks like VitePress have a similar experience: https://vitepress.vuejs.org/ https://vitepress.vuejs.org/
    - swyx 4y ago
      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.
rk06 4y ago
How does it compare to other alternatives like vitepress, astro? Also, aren't react docs on nextJs?
- leerob 4y ago
  Yes, the React beta docs use Next.js.
  - slorber 4y ago
    Can confirm that the React beta docs do not use Docusaurus, and it 100% makes sense to me. I've explained why here: https://twitter.com/sebastienlorber/status/1452722568390221825 https://twitter.com/sebastienlorber/status/14527225683902218... 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.
- slorber 4y ago
  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.
leerob 4y ago
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!
- slorber 4y ago
  Thanks Lee ;)
saghul 4y ago
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 https://undraw.co) through Docusaurus and it has been an invaluable resource! Thanks Docusaurus team! <3
- slorber 4y ago
  Thanks saghul ;) glad you liked it. Yes our community is an important part in the success of Docusaurus
I_am_tiberius 4y ago
How does Docusaurus compare to Gitbooks and alternatives?
- slorber 4y ago
  We see many GitBook users migrating to Docusaurus and being satisfied with Docusaurus features, flexibility, UX/UI and performance https://twitter.com/__morse/status/1532430153338474534 https://twitter.com/__morse/status/1532430153338474534 https://twitter.com/Whelton/status/1540306373497724928 https://twitter.com/Whelton/status/1540306373497724928 https://twitter.com/mweststrate/status/1181276252293853186 https://twitter.com/mweststrate/status/1181276252293853186 https://twitter.com/jstrry/status/1461342355068309512 https://twitter.com/jstrry/status/1461342355068309512 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...
edtechdev 4y ago
I was curious if there are plugins for [[wiki links]] and backlinks. Best I can tell, you'd need to use this wiki link plugin for the remark markdown processor: https://github.com/landakram/remark-wiki-link https://github.com/landakram/remark-wiki-link And then this github action to add backlinks to the markdown files: https://github.com/marketplace/actions/maintain-backlinks-in-wiki https://github.com/marketplace/actions/maintain-backlinks-in...
swyx 4y ago
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!
- slorber 4y ago
  Thanks a lot swyx ;)
justin_oaks 4y ago
I see from the docs that if you don't want an SPA then you should use Docusaurus 1 instead of Docusaurus 2. What are the downsides of using an SPA? I guess you couldn't have a JavaScript-free site, but I'm not sure of other downsides.
- slorber 4y ago
  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.
pottertheotter 4y ago
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.
- slorber 4y ago
  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

202 points by slorber 4y ago

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!

slorber 4y ago
Thanks a lot Johnny Just sharing your blog url for the interested: https://blog.johnnyreilly.com/ https://blog.johnnyreilly.com/ We also have a lot of other personal website/blogs in our site showcase: https://docusaurus.io/showcase?tags=personal https://docusaurus.io/showcase?tags=personal

slorber 4y ago

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. Full-featured: docs, blog, pages, plugins, themes, versioning, i18n, a11y, SEO... 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. Docusaurus 2.0 has already been widely adopted by the community during the beta phase. Some examples - https://www.figma.com/plugin-docs/ https://www.figma.com/plugin-docs/ - https://docs.snap.com/ https://docs.snap.com/ - https://reactnative.dev/ https://reactnative.dev/ - https://supabase.com/docs https://supabase.com/docs - https://ionic.io/docs https://ionic.io/docs - https://developer.stackblitz.com/ https://developer.stackblitz.com/ - https://tauri.app/ https://tauri.app/ - https://hasura.io/docs/latest/index/ https://hasura.io/docs/latest/index/ - https://docs.lacework.com/ https://docs.lacework.com/ - https://wiki.iota.org/ https://wiki.iota.org/ - https://docs.solana.com/ https://docs.solana.com/ 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.

cpursley 4y ago
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).
- slorber 4y ago
  Hey, thanks for your feedback 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
  - cpursley 4y ago
    Tailwind or something like it sounds good.
EGreg 4y ago
How can we transform our DocBlock or YUIDoc comments in PHP and JS code, into beautiful hyperlinked documentation? Now THAT would be something!
- slorber 4y ago
  We don't integrate Docusaurus with such tools atm but you can build a Docusaurus plugin that would allow to integrate with such tools. Here's for example a plugin that integrates with TypeDoc (TS): https://www.npmjs.com/package/docusaurus-plugin-typedoc 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.

yangshun 4y ago

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!

taubek 4y ago

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.

slorber 4y ago
Thanks for the feedback ;) The stable release is not very different from the latest betas: it's mostly our commitment to respect Semantic Versioning for the next releases.

stuaxo 4y ago

Think I'll leave it for a while, Meta is so poisonous.

slorber 4y ago
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.
- inferiorhuman 4y ago
  Even if you don't like Meta, is that a good reason to reject Docusaurus? Yes

brycewray 4y ago

Scroll up and down that page and you see about 30 MB of resources downloaded. Yikes.

slorber 4y ago
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 https://docusaurus.io/docs/cli
- michaelmcdonald 4y ago
  For the lazy: the above referenced page by @slorber only had 1.3MB of resources to load (with JS enabled).
  - slorber 4y ago
    Thanks :) that's more fair, but I admit it's still too much, and we are definitively looking forward to improve the amount of JS needed in the future! Some new features in React 18 (and upcoming releases) like Server Components are going to have a great impact on Docusaurus

brabel 4y ago

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.

rat9988 4y ago
React components, MDX, TypeScript config files, CSS-in-JS? Do you really need all that to write docs? No you don't, you only need to write the markdown.
- slorber 4y ago
  Yes, and that's exactly the value proposition of Docusaurus. 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
manigandham 4y ago
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).
tommica 4y ago
I use this to run my project docs, no compiling, just one index.html and the rest are markdown files: http://dynalon.github.io/mdwiki/#!index.md http://dynalon.github.io/mdwiki/#!index.md

Danborg 4y ago

Reminds me of Gatsby.

mhoad 4y ago
Not a compliment I assume?
slorber 4y ago
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.

POPOSYS 4y ago

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. I am sure I am missing something?

deleted 4y ago
[deleted]
mooreds 4y ago
https://www.npmjs.com/package/docusaurus-pdf https://www.npmjs.com/package/docusaurus-pdf looks useful. Unclear which version this supports, however. (Not a user of docusaurous, YMMV).
- POPOSYS 4y ago
  Sorry, but did you look at the example document? Could you really provide such a result to some serious documentation project? I guess not.
  - mooreds 4y ago
    I did not do more than google a bit and share the link.
TobbenTM 4y ago
If you hit the print button, the print layout is pretty good, pretty much ready to print to PDF if you ask me!
- POPOSYS 4y ago
  I do not see any print button - dou you mean web browser print "button"? I did that - the resulting pdf can not be presented as documentation. It is not satisfying even the most moderate requirements for a documentation pdf. Generating only a website for documentation seems like a cultural step back.

tweetle_beetle 4y ago

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.

slorber 4y ago
Thanks for the feedback 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.

sixhobbits 4y ago

This post is pretty well written but having so many words and phrases in bold text made it annoying for me to read.

slorber 4y ago
Sorry about that you are not the first to tell me I use too much bold. Will remember for next time

mr-karan 4y ago

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? [1]: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/ [2]: https://github.com/mr-karan/notes https://github.com/mr-karan/notes

d4rkp4ttern 4y ago
Material MkDocs is fantastic. Combine it with MkDocStrings and you can get auto-documented code via docstrings (at least for python )
- slorber 4y ago
  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. See the carousel of site screenshots here: https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0#theming https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-... I'm curious to see highly customized MkDocs sites that truly respect your branding. What I mean by respecting your branding: - Courier: https://www.courier.com/docs/ https://www.courier.com/docs/ - Figma: https://www.figma.com/plugin-docs/ https://www.figma.com/plugin-docs/ - Iota: https://wiki.iota.org/ https://wiki.iota.org/ - Hasura: https://hasura.io/docs/latest/index/ https://hasura.io/docs/latest/index/ - Ionic: https://ionicframework.com/docs https://ionicframework.com/docs - Quickwit: https://quickwit.io/docs/ https://quickwit.io/docs/ 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
  - mr-karan 4y ago
    Amazing, thanks for your response. I'll explore Docusaurus 2.0 :) Congrats on the release.

ruuda 4y ago

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/ https://www.mkdocs.org/

slorber 4y ago
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). See some greatly customized Docusaurus sites here: https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0#theming https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-... I'd be curious if you could show me some MkDocs sites with that level of customization
- stonith 4y ago
  > 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?
  - slorber 4y ago
    100% agree, if you are familiar with Python, just try MkDocs first and see if it works for you.
- dzikimarian 4y ago
  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.

jerrygoyal 4y ago

can I add authentication on top of it to restrict docs access to logged-in users?

slorber 4y ago
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. See also: https://github.com/facebook/docusaurus/issues/958#issuecomment-1057075925 https://github.com/facebook/docusaurus/issues/958#issuecomme...
- leerob 4y ago
  If you’re using Vercel, here’s an example: https://github.com/vercel/examples/tree/main/edge-functions/basic-auth-password https://github.com/vercel/examples/tree/main/edge-functions/...

nindalf 4y ago

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.

slorber 4y ago
Thanks nindalf! 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
_fat_santa 4y ago
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.
- slorber 4y ago
  Thanks for the feedback To be fair what you describe is more a side-result of our community rather than our own features. CMD+K is a popular shortcut. It's not built-in Algolia DocSearch modal. Also other frameworks like VitePress have a similar experience: https://vitepress.vuejs.org/ https://vitepress.vuejs.org/
  - swyx 4y ago
    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.

rk06 4y ago

How does it compare to other alternatives like vitepress, astro? Also, aren't react docs on nextJs?

leerob 4y ago
Yes, the React beta docs use Next.js.
- slorber 4y ago
  Can confirm that the React beta docs do not use Docusaurus, and it 100% makes sense to me. I've explained why here: https://twitter.com/sebastienlorber/status/1452722568390221825 https://twitter.com/sebastienlorber/status/14527225683902218... 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.
slorber 4y ago
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.

leerob 4y ago

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!

slorber 4y ago
Thanks Lee ;)

saghul 4y ago

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 https://undraw.co) through Docusaurus and it has been an invaluable resource! Thanks Docusaurus team! <3

slorber 4y ago
Thanks saghul ;) glad you liked it. Yes our community is an important part in the success of Docusaurus

I_am_tiberius 4y ago

How does Docusaurus compare to Gitbooks and alternatives?

slorber 4y ago
We see many GitBook users migrating to Docusaurus and being satisfied with Docusaurus features, flexibility, UX/UI and performance https://twitter.com/__morse/status/1532430153338474534 https://twitter.com/__morse/status/1532430153338474534 https://twitter.com/Whelton/status/1540306373497724928 https://twitter.com/Whelton/status/1540306373497724928 https://twitter.com/mweststrate/status/1181276252293853186 https://twitter.com/mweststrate/status/1181276252293853186 https://twitter.com/jstrry/status/1461342355068309512 https://twitter.com/jstrry/status/1461342355068309512 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...

edtechdev 4y ago

I was curious if there are plugins for [[wiki links]] and backlinks. Best I can tell, you'd need to use this wiki link plugin for the remark markdown processor: https://github.com/landakram/remark-wiki-link https://github.com/landakram/remark-wiki-link And then this github action to add backlinks to the markdown files: https://github.com/marketplace/actions/maintain-backlinks-in-wiki https://github.com/marketplace/actions/maintain-backlinks-in...

swyx 4y ago

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!

slorber 4y ago
Thanks a lot swyx ;)

justin_oaks 4y ago

I see from the docs that if you don't want an SPA then you should use Docusaurus 1 instead of Docusaurus 2. What are the downsides of using an SPA? I guess you couldn't have a JavaScript-free site, but I'm not sure of other downsides.

slorber 4y ago
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.

pottertheotter 4y ago

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.

slorber 4y ago
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