4 ms·

Why wouldn't you want to run JS outside of a browser? That looks like rejecting Node.js for Python. I also think MkDocs is great (and I'm the Docusaurus maint

Why wouldn't you want to run JS outside of a browser? That looks like rejecting Node.js for Python. I also think MkDocs is great (and I'm the Docusaurus maintainer), and probably even simpler, but IMHO Docusaurus is more flexible and customizable that MkDocs. We have seen greatly customized Docusaurus docs site, looking very different one from another. The MkDocs sites I see in the wild usually looks quite the same (often using Material for MkDocs). See some greatly customized Docusaurus sites here: https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0#theming https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-... I'd be curious if you could show me some MkDocs sites with that level of customization

stonith 4y ago
> Why wouldn't you want to run JS outside of a browser? Not OP, but as someone working on backend, infra, and some part time game dev, JS isn't in my skillset in any meaningful way so I don't use tools within that ecosystem if I can avoid it. > IMHO Docusaurus is more flexible and customizable that MkDocs. Presumably only if you're comfortable working in JS?
- slorber 4y ago
  100% agree, if you are familiar with Python, just try MkDocs first and see if it works for you.
dzikimarian 4y ago
Not OP, but I was looking for documentation-oriented static site generator some time ago. In my experience: * There's usually mess in documentation for JS-based ones. For eg. "quick start" section of the docs uses npx. Then full installation manual uses entirely different commands. JS is not my main technology so it's very confusing. * Builds tend to be significantly slower when npm is involved. * Plugins and themes very often have compatibility issues. * They tend to use mdx, which is not necessarily very well supported outside of JS world and some solutions break when you try to bring your existing markdown. I'm aware that: * None of this is inherently JS property. * Docusaurus is actually not guilty of most of these issues and I would recommend it. * Probably it all makes sense/is avoidable, when you work with this ecosystem often. However I'm just trying to setup documentation page, not start new carrer patch and non-JS based solutions are usually better on understanding that.

stonith 4y ago

> Why wouldn't you want to run JS outside of a browser? Not OP, but as someone working on backend, infra, and some part time game dev, JS isn't in my skillset in any meaningful way so I don't use tools within that ecosystem if I can avoid it. > IMHO Docusaurus is more flexible and customizable that MkDocs. Presumably only if you're comfortable working in JS?

slorber 4y ago
100% agree, if you are familiar with Python, just try MkDocs first and see if it works for you.

dzikimarian 4y ago

Not OP, but I was looking for documentation-oriented static site generator some time ago. In my experience: * There's usually mess in documentation for JS-based ones. For eg. "quick start" section of the docs uses npx. Then full installation manual uses entirely different commands. JS is not my main technology so it's very confusing. * Builds tend to be significantly slower when npm is involved. * Plugins and themes very often have compatibility issues. * They tend to use mdx, which is not necessarily very well supported outside of JS world and some solutions break when you try to bring your existing markdown. I'm aware that: * None of this is inherently JS property. * Docusaurus is actually not guilty of most of these issues and I would recommend it. * Probably it all makes sense/is avoidable, when you work with this ecosystem often. However I'm just trying to setup documentation page, not start new carrer patch and non-JS based solutions are usually better on understanding that.