3 ms·
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 th
by 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 agoAmazing, thanks for your response. I'll explore Docusaurus 2.0 :) Congrats on the release.
- slorber 4y agothanks :) glad I was able to convince you to give it a try
- stoicjumbotron 4y agoThanks for providing these examples. Really would not have guessed all these docs were created using Docusaurus.
- slorber 4y agoThose 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
- jacooper 4y agoI 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.
- slorber 4y agoWhat 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 https://twitter.com/leeerob/status/1554211061284364290 You can even try it in your browser right now: https://docusaurus.new https://docusaurus.new
- jacooper 4y agoI 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.
- slorber 4y agoDocusaurus 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/classic/docusaurus.config.js https://github.com/facebook/docusaurus/blob/main/examples/cl...
- d4rkp4ttern 4y agoThanks. 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 )
- slorber 4y agoWe do support math equations, using KaTeX (apparently it is much faster than MathJax) https://docusaurus.io/docs/markdown-features/math-equations https://docusaurus.io/docs/markdown-features/math-equations