Zero Install documentation web-site

Hi all,

I finally got around to working on the idea of a shared documentation
web-site based on http://0install.net/ and http://0install.de/.

I forked https://github.com/0install/web-site to
https://github.com/0install/docs and removed all non-documentation content
(landing page, feeds, etc.). Then I moved and renamed files and directories
to match the menu structure. Next I replaced the XSLT-based build system
with the MkDocs (https://www.mkdocs.org/) static site generator. I believe
this provides a number of advantages:

MkDocs uses Markdown files as its input. Markdown is wildly popular for
documentation these days, dead simple to write and has native support in
many tools (e.g. GitHub's web interface). Speaking of GitHub, MkDocs
generates automatic "Edit this page on GitHub" links.

MkDocs comes with responsive themes, making the generated doc pages easier
to read on mobile devices. I added some custom CSS to better match look of
http://0install.net/. It also applies language-specific syntax highlighting
to Markdown code blocks, which makes the XML and Python samples in the docs
look nicer.

MkDocs automatically derives the menu structure from the file and directory
structure. This makes adding new pages very easy. It also detects and
reports dead links between pages during build.

I converted the HTML content of the existing web-site into Markdown using
Turndown (https://github.com/domchristie/turndown). Then I went through all
the pages manually improving the generated Markdown, adding code blocks,
etc..

Finally, I set up free automatic building and hosting using ReadTheDocs at
https://0install.readthedocs.io/. This service also supports custom domains
using CNAMEs, including automatically issuing TLS certificates. So we could
serve this from https://docs.0install.net/ for example.

Next, I will start integrating documentation for Zero Install for Windows
from http://0install.de/ into this web-site.

What do you guys think? Is this a viable approach? Any areas you think need
improvement?

Regards
Bastian


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot