
MkDocs 1.0 - kylebarron
https://www.mkdocs.org/about/release-notes/#version-10-2018-08-03
======
therealmarv
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
Github hosts your docs for free, with a custom domain name?

~~~
therealmarv
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.

~~~
mixmastamyk
Cool, thanks. Looking at your yaml, it looks like the title of each doc has to
be configured separately? Is that required?

~~~
therealmarv
No this is optional. You can also just throw a bunch of .md files in a
directory structure and run mkdocs over it to generate a tree for navigation.

------
mc_
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!

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

~~~
brianjking
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/m...](https://github.com/brianjking/1upkeyboard-docs/blob/master/mkdocs.yml#L67-L88))

* 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/....](https://github.com/brianjking/1upkeyboard-docs/blob/master/.travis.yml))

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
sphinx allows to test code snippets in the documentation. is this available in
mkdocs?

------
zimmund
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/)

------
jcstk
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
Is that more efficient than building locally and pushing changes to a repo?

~~~
jcstk
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.

------
old-gregg
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)

------
yread
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
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
I've only tried the default one and made sure it's from the same release

------
ngrilly
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%...](https://github.com/mkdocs/mkdocs/issues?utf8=%E2%9C%93&q=is%3Aissue+i18n)

------
jamesadevine
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
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.

------
gravypod
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
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/...](https://github.com/Scifabric/docs.pybossa.com/blob/gh-
pages/mkdocs/search_index.json) (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
[http://asciidoctor.org](http://asciidoctor.org)

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

------
abakus
The proliferation of yaml is rather unfortunate.

~~~
kstrauser
All JSON is valid YAML, so you can format your YAML that way and be just fine.

~~~
Karunamon
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
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.

