Thanks for reminding me to updated and test my container. ;)
MkDocs 1.0
21–30 of 45 posts
Re: MkDocs 1.0
#22How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
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 ( h…
sphinx allows to test code snippets in the documentation. is this available in mkdocs?
Re: MkDocs 1.0
#23I'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.
Re: MkDocs 1.0
#24Yet they still have no way for me to buy them a beer. https://github.com/mkdocs/mkdocs/issues/892
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.
Re: MkDocs 1.0
#25We 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…
I'm curious why you didn't use the sphinx markdown option and/or use travis and github pages to generate the sphinx docs instead.
Re: MkDocs 1.0
#26How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
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.
Re: MkDocs 1.0
#27Earlier quoted context omitted.
Github hosts your docs for free, with a custom domain name?
Github Pages doesn't cost money.
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-domai...). before that you had to use a provider like cloudflare to handle the termination.
Re: MkDocs 1.0
#28We 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…
I'm curious why you didn't use the sphinx markdown option and/or use travis and github pages to generate the sphinx docs instead.
You would loose online search capabilities with this approach or we had to implement it ourself which would be a waste of time because we wanted to write docs not the system behind the docs. We also faced problems with the styling on Sphinx over time (the ready to use styling templates on mkdocs only needed very little modifications from our side).
Re: MkDocs 1.0
#29We 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
Re: MkDocs 1.0
#30I'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?