5 ms·

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 work

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.
zvr 4y ago
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.
- slorber 4y ago
  We have a default tabs component that you can use with MDX https://docusaurus.io/docs/markdown-features/tabs https://docusaurus.io/docs/markdown-features/tabs 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/ https://www.courier.com/docs/reference/send/message/ See also this frontend framework switcher in the sidebar: https://docs.dyte.io/react-ui-kit/ https://docs.dyte.io/react-ui-kit/ 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://xsoar.pan.dev - https://prisma.pan.dev/ https://prisma.pan.dev/
JimDabell 4y ago
> your thing is a little toy > 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.
- slorber 4y ago
  JimDabell I'm sorry if it feels so. 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.
  - JimDabell 4y ago
    > 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?
pbowyer 4y ago
Congratulations on the release! In https://news.ycombinator.com/item?id=27134785 https://news.ycombinator.com/item?id=27134785 in reply to me you said: > 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?
- slorber 4y ago
  Thanks! It's a bit hacky and will likely change in the future, but you can do so this way: https://docusaurus.io/docs/markdown-features/react#importing-code-snippets https://docusaurus.io/docs/markdown-features/react#importing...

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.

zvr 4y ago

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.

slorber 4y ago
We have a default tabs component that you can use with MDX https://docusaurus.io/docs/markdown-features/tabs https://docusaurus.io/docs/markdown-features/tabs 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/ https://www.courier.com/docs/reference/send/message/ See also this frontend framework switcher in the sidebar: https://docs.dyte.io/react-ui-kit/ https://docs.dyte.io/react-ui-kit/ 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://xsoar.pan.dev - https://prisma.pan.dev/ https://prisma.pan.dev/

JimDabell 4y ago

> your thing is a little toy > 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.

slorber 4y ago
JimDabell I'm sorry if it feels so. 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.
- JimDabell 4y ago
  > 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?

pbowyer 4y ago

Congratulations on the release! In https://news.ycombinator.com/item?id=27134785 https://news.ycombinator.com/item?id=27134785 in reply to me you said: > 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?

slorber 4y ago
Thanks! It's a bit hacky and will likely change in the future, but you can do so this way: https://docusaurus.io/docs/markdown-features/react#importing-code-snippets https://docusaurus.io/docs/markdown-features/react#importing...