7 ms·

MkDocs 1.0

115 points by kylebarron 8y ago

lima 8y ago
How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
- mixmastamyk 8y ago
  Also wondering about extensions, how are those handled? Or is this for plain documents only? For example in Sphinx you can mark up figures, youtube videos, graphviz graphs, etc. Are those plugins available with mkdocs? What about a book with parts? That's one area that Sphinx falls down, and they've been dragging their feet on it so far.
  - therealmarv 8y ago
    There are plenty of mkdocs plugins for advanced documentation features.
- brianjking 8y ago
  I'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs. POSITIVES OF MkDocs over Sphinx * Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText. * MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/. * Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/mkdocs.yml#L67-L88 https://github.com/brianjking/1upkeyboard-docs/blob/master/m...) * Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjking/1upkeyboard-docs/blob/master/.travis.yml https://github.com/brianjking/1upkeyboard-docs/blob/master/....) The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience): * If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/ https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc https://github.com/search?q=mkdocs+pandoc). * Sphinx seems better for auto documentation for APIs and other code documentation.
  - sashk 8y ago
    sphinx allows to test code snippets in the documentation. is this available in mkdocs?
- type0 8y ago
  They're are quite different beasts all together. I can't think of any reason to use reST and Sphinx under any circumstance other than Python projects. Asciidoctor.js actually has a site generator these days called Antora (aimed at building docs from multiple git repos) it is still far from complete on features compared to Sphinx. MkDocs looks good for small projects although I probably would just use mdBook if there's a need to write in Markdown for some reason.
zimmund 8y ago
If anyone finds it useful, some time ago I made a Docker image of `mkdocs` [1] (with a few extensions, check the dockerfile for details). [1]: https://hub.docker.com/r/elamperti/docker-mkdocs/ https://hub.docker.com/r/elamperti/docker-mkdocs/
therealmarv 8y ago
We migrated a while ago all our python docs from sphinx and the free readthedocs to mkdocs. Two main reasons: - we like markdown more and starting (actually we converted to markdown with pandoc) with a bunch of markdown files was a breeze. We also did not lost advanced documentation features because there are plenty of fantastic mkdocs plugins. - readthedocs was unreliable for us but we also did not wanted to pay for our open source software documentation generation + hosting. At the end we have an auto generated mkdocs with GitHub+Travis and all searchable with the fantastic mkdocs static page search functionality (maybe the biggest feature of mkdocs) End result: https://docs.pybossa.com https://docs.pybossa.com (hosted on GitHub) Source: https://github.com/scifabric/docs.pybossa.com https://github.com/scifabric/docs.pybossa.com
- mixmastamyk 8y ago
  Github hosts your docs for free, with a custom domain name?
  - detaro 8y ago
    Github Pages doesn't cost money.
    - mixmastamyk 8y ago
      Custom domain is usually where sites look for revenue ops, though VC/MS money should last for a while.
    - burdzwastaken 8y ago
      you're right it doesn't cost money however GitHub pages only just started handling SSL certificates for custom domains recently (https://blog.github.com/2018-05-01-github-pages-custom-domains-https/ https://blog.github.com/2018-05-01-github-pages-custom-domai...). before that you had to use a provider like cloudflare to handle the termination.
  - therealmarv 8y ago
    Yep, just search for DNS CNAME handling on GitHub docs. We put also Cloudflare DNS in front of it to get TLS/SSL but I've heard this is not necessary anymore nowadays.
jamesadevine 8y ago
Yet they still have no way for me to buy them a beer. https://github.com/mkdocs/mkdocs/issues/892 https://github.com/mkdocs/mkdocs/issues/892
- styfle 8y ago
  Some projects are hard to divide up donations. Does it split evenly to anyone who wrote code? What about people who only review and merge PRs? What about if someone was unavailable for a month or two—do they still get a cut for current donations? I help maintain marked.js.org and we currently don’t accept donations because of these questions.
abakus 8y ago
The proliferation of yaml is rather unfortunate.
- kstrauser 8y ago
  All JSON is valid YAML, so you can format your YAML that way and be just fine.
  - Karunamon 8y ago
    How the.. I just tried this, and it works, but I don't understand why. I mean YAML is just another data serialization format and so can be trivially converted anyways, but I thought that YAML had completely different formatting rules than JSON.
    - kstrauser 8y ago
      In the spec (http://yaml.org/spec/1.2/spec.html#id2759572 http://yaml.org/spec/1.2/spec.html#id2759572) it says: > YAML can therefore be viewed as a natural superset of JSON, offering improved human readability and a more complete information model. This is also the case in practice; every JSON file is also a valid YAML file. This makes it easy to migrate from JSON to YAML if/when the additional features are required. I think that's why I absolutely love YAML: I was able to start using it by writing JSON, then replacing parts of my documents with their "native" equivalents as I got comfortable with it.
jcstk 8y ago
Awesome and congrats. We started using MkDocs for https://aqueduct.io/docs/ https://aqueduct.io/docs/, and have since used it for a ton of projects. Some things that we found really useful were that it indexes all of your content for full text search automatically, and it’s stupid simple to deploy it to gh-pages. With a minimal amount of scripting, we push to a mkdocs source branch and it builds and deploys nearly immediately. It has saved us a ton of time and delivered tremendous value.
- mixmastamyk 8y ago
  Is that more efficient than building locally and pushing changes to a repo?
  - jcstk 8y ago
    I’ve found that I’m at least more willing to make quick typo fixes and deploy them when I just have to make the change locally and do a single push. This is especially true (for me) when there is some additional web content that is not generated by mkdocs.
mc_ 8y ago
We moved the majority of docs for our projects (https://github.com/2600hz https://github.com/2600hz) to use mkdocs to build our doc sites (https://docs.2600hz.com/dev https://docs.2600hz.com/dev https://docs.2600hz.com/ui https://docs.2600hz.com/ui etc). I have a simple script that receives github webhooks on PR merges to master that fetches the latest version of master and builds the site. So from PR merge to the docs site being updated is now seconds of time. We also integrated building the doc sites into our CI process so PRs will fail if they would cause mkdocs to fail to build the site (borked yaml, make sure docs are included in the yaml, other things). This has been a boon for our community of users and developers. Coupled with our AST parsers that look for code changes that require doc changes, we're getting better about alerting developers of the need to document something, and reviewers of the need if the developer forgot. Not a panacea but has significantly improved doc coverage for Kazoo which has a broad set of APIs available to different types of users. Cheers to 1.0!
JakeTyo 8y ago
Thanks for reminding me to updated and test my container. ;)
yread 8y ago
I've just started writing documentation for my project in MkDocs like last week. So far, it's pretty good. But I had to switch off the search functionality because it was causing a slowdown when displaying the page (you couldn't even scroll?). Also I would appreciate if they made changing the theme easier - currently there is only a minified bootstrap css which is a PITA to modify.
- therealmarv 8y ago
  Sounds like a theme issue with the online search (we had also problems with search when theme was older or newer than mkdocs), do you experience same behaviour with other themes?
  - yread 8y ago
    I've only tried the default one and made sure it's from the same release
old-gregg 8y ago
We love MkDocs! When we originally discovered it we believed it was "good for small projects" but as our product got more complicated we actually never hit any issues. It's amazingly easy to use, extend and customize with great results: https://gravitational.com/teleport/docs https://gravitational.com/teleport/docs
gravypod 8y ago
The search feature is nothing short of amazing. I love how fast it is. Is it scalable to large amounts of documentation? How is it indexed?
- therealmarv 8y ago
  It flattens the text into one big json file and with some JS it searches this flat text file: https://github.com/Scifabric/docs.pybossa.com/blob/gh-pages/mkdocs/search_index.json https://github.com/Scifabric/docs.pybossa.com/blob/gh-pages/... (1.1 MB) all done automatically on building the site. There are for sure some limits to this approach because it's all in memory/browser but we only write some software documentation on our side and not really big books.
Jahak 8y ago
http://asciidoctor.org http://asciidoctor.org
ngrilly 8y ago
What about i18n/multilingual documentation with MkDocs? Edit: Some answers in the issue tracker: https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%3Aissue+i18n https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%...

MkDocs 1.0

115 points by kylebarron 8y ago

lima 8y ago

How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?

mixmastamyk 8y ago
Also wondering about extensions, how are those handled? Or is this for plain documents only? For example in Sphinx you can mark up figures, youtube videos, graphviz graphs, etc. Are those plugins available with mkdocs? What about a book with parts? That's one area that Sphinx falls down, and they've been dragging their feet on it so far.
- therealmarv 8y ago
  There are plenty of mkdocs plugins for advanced documentation features.
brianjking 8y ago
I'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs. POSITIVES OF MkDocs over Sphinx * Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText. * MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/. * Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/mkdocs.yml#L67-L88 https://github.com/brianjking/1upkeyboard-docs/blob/master/m...) * Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjking/1upkeyboard-docs/blob/master/.travis.yml https://github.com/brianjking/1upkeyboard-docs/blob/master/....) The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience): * If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/ https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc https://github.com/search?q=mkdocs+pandoc). * Sphinx seems better for auto documentation for APIs and other code documentation.
- sashk 8y ago
  sphinx allows to test code snippets in the documentation. is this available in mkdocs?
type0 8y ago
They're are quite different beasts all together. I can't think of any reason to use reST and Sphinx under any circumstance other than Python projects. Asciidoctor.js actually has a site generator these days called Antora (aimed at building docs from multiple git repos) it is still far from complete on features compared to Sphinx. MkDocs looks good for small projects although I probably would just use mdBook if there's a need to write in Markdown for some reason.

zimmund 8y ago

If anyone finds it useful, some time ago I made a Docker image of `mkdocs` [1] (with a few extensions, check the dockerfile for details). [1]: https://hub.docker.com/r/elamperti/docker-mkdocs/ https://hub.docker.com/r/elamperti/docker-mkdocs/

therealmarv 8y ago

We migrated a while ago all our python docs from sphinx and the free readthedocs to mkdocs. Two main reasons: - we like markdown more and starting (actually we converted to markdown with pandoc) with a bunch of markdown files was a breeze. We also did not lost advanced documentation features because there are plenty of fantastic mkdocs plugins. - readthedocs was unreliable for us but we also did not wanted to pay for our open source software documentation generation + hosting. At the end we have an auto generated mkdocs with GitHub+Travis and all searchable with the fantastic mkdocs static page search functionality (maybe the biggest feature of mkdocs) End result: https://docs.pybossa.com https://docs.pybossa.com (hosted on GitHub) Source: https://github.com/scifabric/docs.pybossa.com https://github.com/scifabric/docs.pybossa.com

mixmastamyk 8y ago
Github hosts your docs for free, with a custom domain name?
- detaro 8y ago
  Github Pages doesn't cost money.
  - mixmastamyk 8y ago
    Custom domain is usually where sites look for revenue ops, though VC/MS money should last for a while.
  - burdzwastaken 8y ago
    you're right it doesn't cost money however GitHub pages only just started handling SSL certificates for custom domains recently (https://blog.github.com/2018-05-01-github-pages-custom-domains-https/ https://blog.github.com/2018-05-01-github-pages-custom-domai...). before that you had to use a provider like cloudflare to handle the termination.
- therealmarv 8y ago
  Yep, just search for DNS CNAME handling on GitHub docs. We put also Cloudflare DNS in front of it to get TLS/SSL but I've heard this is not necessary anymore nowadays.

jamesadevine 8y ago

Yet they still have no way for me to buy them a beer. https://github.com/mkdocs/mkdocs/issues/892 https://github.com/mkdocs/mkdocs/issues/892

styfle 8y ago
Some projects are hard to divide up donations. Does it split evenly to anyone who wrote code? What about people who only review and merge PRs? What about if someone was unavailable for a month or two—do they still get a cut for current donations? I help maintain marked.js.org and we currently don’t accept donations because of these questions.

abakus 8y ago

The proliferation of yaml is rather unfortunate.

kstrauser 8y ago
All JSON is valid YAML, so you can format your YAML that way and be just fine.
- Karunamon 8y ago
  How the.. I just tried this, and it works, but I don't understand why. I mean YAML is just another data serialization format and so can be trivially converted anyways, but I thought that YAML had completely different formatting rules than JSON.
  - kstrauser 8y ago
    In the spec (http://yaml.org/spec/1.2/spec.html#id2759572 http://yaml.org/spec/1.2/spec.html#id2759572) it says: > YAML can therefore be viewed as a natural superset of JSON, offering improved human readability and a more complete information model. This is also the case in practice; every JSON file is also a valid YAML file. This makes it easy to migrate from JSON to YAML if/when the additional features are required. I think that's why I absolutely love YAML: I was able to start using it by writing JSON, then replacing parts of my documents with their "native" equivalents as I got comfortable with it.

jcstk 8y ago

Awesome and congrats. We started using MkDocs for https://aqueduct.io/docs/ https://aqueduct.io/docs/, and have since used it for a ton of projects. Some things that we found really useful were that it indexes all of your content for full text search automatically, and it’s stupid simple to deploy it to gh-pages. With a minimal amount of scripting, we push to a mkdocs source branch and it builds and deploys nearly immediately. It has saved us a ton of time and delivered tremendous value.

mixmastamyk 8y ago
Is that more efficient than building locally and pushing changes to a repo?
- jcstk 8y ago
  I’ve found that I’m at least more willing to make quick typo fixes and deploy them when I just have to make the change locally and do a single push. This is especially true (for me) when there is some additional web content that is not generated by mkdocs.

mc_ 8y ago

We moved the majority of docs for our projects (https://github.com/2600hz https://github.com/2600hz) to use mkdocs to build our doc sites (https://docs.2600hz.com/dev https://docs.2600hz.com/dev https://docs.2600hz.com/ui https://docs.2600hz.com/ui etc). I have a simple script that receives github webhooks on PR merges to master that fetches the latest version of master and builds the site. So from PR merge to the docs site being updated is now seconds of time. We also integrated building the doc sites into our CI process so PRs will fail if they would cause mkdocs to fail to build the site (borked yaml, make sure docs are included in the yaml, other things). This has been a boon for our community of users and developers. Coupled with our AST parsers that look for code changes that require doc changes, we're getting better about alerting developers of the need to document something, and reviewers of the need if the developer forgot. Not a panacea but has significantly improved doc coverage for Kazoo which has a broad set of APIs available to different types of users. Cheers to 1.0!

JakeTyo 8y ago

Thanks for reminding me to updated and test my container. ;)

yread 8y ago

I've just started writing documentation for my project in MkDocs like last week. So far, it's pretty good. But I had to switch off the search functionality because it was causing a slowdown when displaying the page (you couldn't even scroll?). Also I would appreciate if they made changing the theme easier - currently there is only a minified bootstrap css which is a PITA to modify.

therealmarv 8y ago
Sounds like a theme issue with the online search (we had also problems with search when theme was older or newer than mkdocs), do you experience same behaviour with other themes?
- yread 8y ago
  I've only tried the default one and made sure it's from the same release

old-gregg 8y ago

We love MkDocs! When we originally discovered it we believed it was "good for small projects" but as our product got more complicated we actually never hit any issues. It's amazingly easy to use, extend and customize with great results: https://gravitational.com/teleport/docs https://gravitational.com/teleport/docs

gravypod 8y ago

The search feature is nothing short of amazing. I love how fast it is. Is it scalable to large amounts of documentation? How is it indexed?

therealmarv 8y ago
It flattens the text into one big json file and with some JS it searches this flat text file: https://github.com/Scifabric/docs.pybossa.com/blob/gh-pages/mkdocs/search_index.json https://github.com/Scifabric/docs.pybossa.com/blob/gh-pages/... (1.1 MB) all done automatically on building the site. There are for sure some limits to this approach because it's all in memory/browser but we only write some software documentation on our side and not really big books.

Jahak 8y ago

http://asciidoctor.org http://asciidoctor.org

ngrilly 8y ago

What about i18n/multilingual documentation with MkDocs? Edit: Some answers in the issue tracker: https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%3Aissue+i18n https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%...