4 ms·

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 ou

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/ https://squidfunk.github.io/mkdocs-material/ [2]: https://github.com/mr-karan/notes https://github.com/mr-karan/notes

d4rkp4ttern 4y ago
Material MkDocs is fantastic. Combine it with MkDocStrings and you can get auto-documented code via docstrings (at least for python )
- 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 ago
    Amazing, thanks for your response. I'll explore Docusaurus 2.0 :) Congrats on the release.
    - slorber 4y ago
      thanks :) glad I was able to convince you to give it a try
  - stoicjumbotron 4y ago
    Thanks for providing these examples. Really would not have guessed all these docs were created using Docusaurus.
    - slorber 4y ago
      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
  - jacooper 4y ago
    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.
    - slorber 4y ago
      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 https://twitter.com/leeerob/status/1554211061284364290 You can even try it in your browser right now: https://docusaurus.new https://docusaurus.new
      - jacooper 4y ago
        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.
        slorber 4y ago
        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/classic/docusaurus.config.js https://github.com/facebook/docusaurus/blob/main/examples/cl...
  - d4rkp4ttern 4y ago
    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 )
    - slorber 4y ago
      We 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
nop_slide 4y ago
Do you have any info on how you deploy these and integrate with obsidian? I like the sound of this setup.
- slorber 4y ago
  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 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 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.

d4rkp4ttern 4y ago

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

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 ago
  Amazing, thanks for your response. I'll explore Docusaurus 2.0 :) Congrats on the release.
  - slorber 4y ago
    thanks :) glad I was able to convince you to give it a try
- stoicjumbotron 4y ago
  Thanks for providing these examples. Really would not have guessed all these docs were created using Docusaurus.
  - slorber 4y ago
    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
- jacooper 4y ago
  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.
  - slorber 4y ago
    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 https://twitter.com/leeerob/status/1554211061284364290 You can even try it in your browser right now: https://docusaurus.new https://docusaurus.new
    - jacooper 4y ago
      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.
      - slorber 4y ago
        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/classic/docusaurus.config.js https://github.com/facebook/docusaurus/blob/main/examples/cl...
- d4rkp4ttern 4y ago
  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 )
  - slorber 4y ago
    We 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

nop_slide 4y ago

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

slorber 4y ago
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 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 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.