Hacker News Reader

Comment by mr-karan | Hacker News Reader

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/

[2]: https://github.com/mr-karan/notes

View on HN

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

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

Do you have any info on how you deploy these and integrate with obsidian? I like the sound of this setup.

That is extremely easy to deploy Docusaurus on Vercel/Netlify.

Here's a 70sec demo video deploying Docusaurus on Vercel: https://twitter.com/leeerob/status/1554211061284364290

We provide a "docusaurus deploy" tool to deploy on GitHub pages but it is more work to setup the GH Action CI than using a good static hosting solution

---

Regarding Obsidian, we don't provide an official integration with it, and IMHO Obsidian is only the "markdown authoring experience". Similarly you can use another tool like VSCode, Sublime or Intellij.

What I would do: - Author md in Obsidian - Sync Obsidian vault md to GitHub using https://github.com/denolehov/obsidian-git - Setup Vercel/Netlify to deploy my doc site from the GitHub repo

Note: we don't support Obsidian bi-directional linking such as [[xyz]], as this is not part of the CommonMark spec. But I definitively want to support something like that as well in the future, as I'm interested to create my own second brain / digital garden using Obsidian and put it online with Docusaurus. This way Docusaurus could become a free competitor to Obsidian Publish.

Reply on news.ycombinator.com