Hacker News Reader

Comment by d4rkp4ttern | Hacker News Reader

Material MkDocs is fantastic. Combine it with MkDocStrings and you can get auto-documented code via docstrings (at least for python )

View on HN

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

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/ - Figma: https://www.figma.com/plugin-docs/ - Iota: https://wiki.iota.org/ - Hasura: https://hasura.io/docs/latest/index/ - Ionic: https://ionicframework.com/docs - Quickwit: 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

Thanks for providing these examples. Really would not have guessed all these docs were created using Docusaurus.

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

Amazing, thanks for your response. I'll explore Docusaurus 2.0 :)

Congrats on the release.

thanks :) glad I was able to convince you to give it a try

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.

What makes MkDocs easier to use than Docusaurus for a non-dev user exactly?

The only thing I can see is that maybe you are more familiar with Python than Node.js? Otherwise using Docusaurus or MkDocs are both equally easy IMHO

You can get a Docusaurus site online in 1 minute, and publish your first doc edit in 2 minutes. See demo video: https://twitter.com/leeerob/status/1554211061284364290

You can even try it in your browser right now: https://docusaurus.new

I didn't have to code anything. I just created a yaml config, set the theme, the title, and the themes setting, and I was done.

I didn't need any coding.

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 )

We do support math equations, using KaTeX (apparently it is much faster than MathJax)

https://docusaurus.io/docs/markdown-features/math-equations

Reply on news.ycombinator.com