Ability to build docs for use without a web server.

[bwmarrin]

The main use for mkdocs is to upload the generated files to a webserver, clearly.

However, for my use, I may need to occasionally send someone the documentation in a format they can just open. There may be some html 2 pdf options that would mostly work but any cool JS or HTML specific awesomesause would be lost.

I thought, well I could just zip up the files. But if you open the main index.html file directly from a file folder on your comptuer (windows in my case) it works. But as you click on the links they're built with the assumption that the browser will pull the index.html file for paths like file://folder/folder/docs/projects/ but instead the browser is just showing the list of files in that folder. So you can click on the index.html file but it's just not the user experience you would want.

So, what I would like (maybe it exists?) is a way to bundle up the docs for use without a web server in as convenient a manor as possible for the end user. If somehow it could all get shoved into a single file that would be really neat :) But, just having an option so that all links point to the actual .html files would be a start.

[d0ugal]

You just need to set the config option. This will link directly to the index.html file.

use_directory_urls: false

http://www.mkdocs.org/user-guide/configuration/#use_directory_urls

[bwmarrin]

Ah, well now I feel bad opening a ticket :)

Though, having the ability to build the whole thing to a single file somehow would still be pretty handy.

[d0ugal]

In terms of portability, I think the only viable idea is to add support for Dash (#520 ).

I'm not interested in creating a PDF export or functionality to bundle the documentation into one or less files. When we eventually have a plugin API, it should be possible to do it with that, but it will be a while until we are at that stage.

I certainly see the value in something like this, for some people, but it's just a case of my limited bandwidth.

[d0ugal]

Having said that, if there is an easy way to do something like this. I would be interested to hear about them, but as it stands, I can only think of complicated solutions.

[bwmarrin]

The only thing I've come up with so far is the MHT file format. But there's some draw backs because it's not 100% supported by everything - though, I guess.. few things are. I'm not sure if there's an easy way or -quality- existing Python project/library that would handle all the hard work or not. If all of that did work, it would be nice to have an option so,

mkdocs build --format=?

or if in the config there was an option to build to the MHT, or even better, would be an option to build both normal, and MHT formats. So the file would always just be there.

Maybe, though. This is best left to the browser as it seems some of them can already "Save As" a MHT file. -shrug- That's all I got :)

[waylan]

I think a good model for this sort of thing is to look at what Python does. They offer PDF, HTML, Plain Text, EPUB, and (for Windows) .chm files. Let's briefly consider each in turn:

• I would expect that any PDF solution would be one which converted the HTML to PDF, so this can exist completely outside of mkdocs (various existing tools already to this type of conversation). Perhaps a theme which generates HTML in a format more suitable for conversion to PDF would be helpful, but anyone can create their own themes.
• Obviously, HTML is already fully supported. I suppose as part of Document deploying #477, a deploy subcommand which zipped the docs up might make sense, but I see no need to do anything else here.
• Plain text is already available as the docs are all in Markdown. However, I do wonder if a clean export of the Markdown docs only would be worth doing. Haven't looked at how Python's plain text docs are formatted or arranged yet, so not sure about this.
• I would expect that a HTML-to-EPUB converter would do the trick here. The same issues that apply to PDFs would likely apply here. Or it may be possible to construct an EPUB solely by creating an appropriate theme. An EPUB is just a bunch of HTML files all zipped up with a manifest file in a specific arrangement after all.
• Windows help files (.chm) are interesting, but again, I believe there are third party tools to do the conversion from HTML.
• @d0ugal already mentioned Dash, which is more-or-less a Mac equivalent of Windows Help Files which also happens to have viewers available for Windows and Linux. And the tool pointed to in Download as Dash docset? #520 is another third party tool which converts from the HTML docs.

Perhaps you have noticed a trend here. There is not really anything mkdocs needs to do to make any of those possible. I suppose a few unique needs for the custom themes might arise, but those could be addressed in turn as people create those themes. Everything else is really just an external tool which already exists and takes the output of mkdocs and converts it into the appropriate format.

[d0ugal]

Everything else is really just an external tool which already exists and takes the output of mkdocs and converts it into the appropriate format.

That's why I see this as something that could live as a plugin, called mkdocs-publish maybe. It could then include all the integration and custom themes if they are needed too.

The idea of having to support multiple combinations of formats and themes builtin to MkDocs scares me :)

[waylan]

The idea of having to support multiple combinations of formats and themes builtin to MkDocs scares me :)

As it should. To be clear, I agree that none of these should be included in or directly supported by mkdocs. Even if/when a plugin API becomes available, I question what value such a plugin would add outside of offering a set of defaults known to work with mkdocs built content. This, like #477 is really just a matter of providing documentation for the common use cases. I would probably expect the various output formats mentioned above to be documented via publicly editable wiki pages (right here on GitHub) perhaps with a link from the documentation. That way, people can add details and/or alternatives as they discover them.

[d0ugal]

+1, I agree.

[bwmarrin]

The one draw back to each? of those formats is they loose the javascript, right and I would image any special HTML5 features? So the new search box wouldn't work (though, I suppose that wouldn't be as big a deal in most of those formats), but if you had some fancy Datatable.js tables with sortable headers and search box, all of that wouldn't work. That's what makes the MHTML format look pretty nice as another option to figure out.

[brianjking]

@bwmarrin @d0ugal @waylan Btw, I found this the other day and it works really quite well. Only issues I found were I had an SVG image on one page that I had to remove from the mkdocs.pd file and a few image paths that were messed up due to relative path usages. Once I corrected those manually in the mkdocs.pd file the pdf package exported nicely.

https://github.com/jgrassler/mkdocs-pandoc

[bwmarrin]

Oh, nice. Good find and that is for sharing