Provide ZIP downloads for MkDocs

[marcelstoer]

I know there's no PDF for MkDocs projects (http://docs.readthedocs.org/en/latest/builds.html?highlight=pdf#mkdocs and #1174).

However, why can't there be at least a downloadable HTML bundle? You have to produce those files anyway, right? Or should there be an HTML bundle but my project https://readthedocs.org/projects/nodemcu/ simply isn't configured/working correctly?

[ericholscher]

Mkdocs doesn't generate PDF's, so there is no way for us to support this. Feel free to open a bug there to get PDF support.

We could do downloadable HTML of the mkdocs builds, if you want to add support, the code for it is here: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py

[marcelstoer]

Mkdocs doesn't generate PDF's, so there is no way for us to support this.

As I said, I know and understand that 😉 There are a number of issues over at MkDocs that circle around that topic but only mkdocs/mkdocs#374 (comment) currently has some momentum. We'll see...

Thanks for the pointer to mkdocs.py. Being familiar with neither your code base NOR Python makes this seem like a daunting task. However, even old dogs are never too old to learn new tricks. In pseudo-code I'd expect something like:

...
invokeMkDocsBuilder(outputDir)
zip = zip(outputDir)
copyFile(zip, 'https://readthedocs.org/projects/' + project + '/downloads/')
...

I'll look into the code and http://docs.readthedocs.org/en/latest/contribute.html#contributing-to-development to see if I think it'll get me somewhere.

[jgrassler]

On the subject of PDF generation: mkdocs/mkdocs#374 (comment) yielded a working PDF generator already: https://github.com/jgrassler/mkdocs-pandoc

In a nutshell, it generates a single Pandoc document from the original mkdocs source and uses Pandoc's PDF generator facilities. It may have a few more bugs that need ironing out, but it's at a point where I'd risk exposing it to a somewhat broader user base to trigger all these edge cases I probably haven't thought of :-)

[vlcinsky]

Why everybody talks here about PDF when the title asks for ZIP file and explicitly excludes PDF?

Maybe the title is confusing (using two negations is probably the problem). I would propose changing the title to Provide ZIP downloads for MkDocs

[RichardLitt]

Thanks @vlcinsky - good point. Changed.

[humitos]

Hello 👋🏼 We standardized the output paths for all the formats that Read the Docs supports in #9888. This allow people to output, for example, a PDF under _readthedocs/pdf/<project-slug>.pdf to be recognized by Read the Docs and expose it as a downloadable content (https://docs.readthedocs.io/en/stable/downloadable-documentation.html) 💯

I created an example at:

• Repository: https://github.com/readthedocs/test-builds/tree/mkdocs-pdf
• Build: https://readthedocs.org/projects/test-builds/builds/19330109/
• PDF: https://test-builds.readthedocs.io/_/downloads/en/mkdocs-pdf/pdf/

It uses the mkdocs-with-pdf MkDocs plugin: https://pypi.org/project/mkdocs-with-pdf/

---

I also created a similar example for HTML Zip files at:

• Repository: https://github.com/readthedocs/test-builds/tree/mkdocs-htmlzip
• Build: https://readthedocs.org/projects/test-builds/builds/19330237/
• HTMLZip: https://test-builds.readthedocs.io/_/downloads/en/mkdocs-htmlzip/htmlzip/

It uses the mkdocs-autozip MkDocs plugin: https://pypi.org/project/mkdocs-autozip/

Unfortunately, the Zip file provided by this plugin is just a zipped version of all the source files (.md) and not a self-contained web page. However, this is a limitation of the plugin 😞 , not Read the Docs.

I'm closing this issue since with the introduction of the standard output directories, users can solve this problem by themselves by using external plugins/tools to achieve this goal.