The proliferation of yaml is rather unfortunate.
All JSON is valid YAML, so you can format your YAML that way and be just fine.
MkDocs 1.0
31–40 of 45 posts
Re: MkDocs 1.0
#32We 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:
Re: MkDocs 1.0
#33We 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…
> we also did not wanted to pay for our open source software documentation generation + hosting. Actually, rtd is free for OSS projects
Yes I know. It was not reliable enough for us and sometimes it failed generating the docs. Paying for it (don't know if this would improve the situation) was out of question for us.
Re: MkDocs 1.0
#34I'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.
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?
I've only tried the default one and made sure it's from the same release
Re: MkDocs 1.0
#35The proliferation of yaml is rather unfortunate.
All JSON is valid YAML, so you can format your YAML that way and be just fine.
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.
Re: MkDocs 1.0
#36Earlier quoted context omitted.
All JSON is valid YAML, so you can format your YAML that way and be just fine.
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.
In the spec (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.
Re: MkDocs 1.0
#37Earlier quoted context omitted.
> we also did not wanted to pay for our open source software documentation generation + hosting. Actually, rtd is free for OSS projects
Yes I know. It was not reliable enough for us and sometimes it failed generating the docs. Paying for it (don't know if this would improve the situation) was out of question for us.
I frequently see failures on RTD doc builds due to memory exhaustion.
Re: MkDocs 1.0
#38We 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…
This is quite nice, high quality documentation, the template is eye-catchy, very nicely structured, well done!
Re: MkDocs 1.0
#39The 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?
Re: MkDocs 1.0
#40We 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…
Can someone please compare this to https://github.com/facebook/Docusaurus and Jekyll? TIA