Comment by slorber | Hacker News Reader

Comment by slorber | Hacker News Reader

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://docs.snap.com/ - https://reactnative.dev/ - https://supabase.com/docs - https://ionic.io/docs - https://developer.stackblitz.com/ - https://tauri.app/ - https://hasura.io/docs/latest/index/ - https://docs.lacework.com/ - https://wiki.iota.org/ - 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.

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

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.

> 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?

In the comments, I prefer to read real discussions between developers – not curated corporate press releases.

Don’t mind the tone if a bit heated - especially when people are posting projects they have been working on for years.

“Please respond to the strongest plausible interpretation of what someone says. […] Assume good faith.”

- https://news.ycombinator.com/newsguidelines.html

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.

Congratulations on the release!

In 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?

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

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.

We have a default tabs component that you can use with MDX

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/

See also this frontend framework switcher in the sidebar: 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://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).

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

Tailwind or something like it sounds good.

How can we transform our DocBlock or YUIDoc comments in PHP and JS code, into beautiful hyperlinked documentation? Now THAT would be something!

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

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.

Reply on news.ycombinator.com