docs: Replace static page with mdBook site

Uses mdBook[1] to generate a documentation overview page instead of
the previous HTML site.

This makes it possible to add more elaborate documentation without
having to deal with finicky markup.

[1]: https://github.com/rust-lang-nursery/mdBook

11 files changed, 97 insertions, 108 deletions

diff --git a/tools/nixery/.gitattributes b/tools/nixery/.gitattributes
new file mode 100644
index 000000000000..74464db942e9
--- /dev/null
+++ b/tools/nixery/.gitattributes
@@ -0,0 +1,2 @@
+# Ignore stylesheet modifications for the book in Linguist stats
+*.css linguist-detectable=false
diff --git a/tools/nixery/docs/.gitignore b/tools/nixery/docs/.gitignore
new file mode 100644
index 000000000000..7585238efedf
--- /dev/null
+++ b/tools/nixery/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/tools/nixery/docs/book.toml b/tools/nixery/docs/book.toml
new file mode 100644
index 000000000000..bf6ccbb27f35
--- /dev/null
+++ b/tools/nixery/docs/book.toml
@@ -0,0 +1,8 @@
+[book]
+authors = ["Vincent Ambo <tazjin@google.com>"]
+language = "en"
+multilingual = false
+src = "src"
+
+[output.html]
+additional-css = ["theme/nixery.css"]
diff --git a/tools/nixery/docs/src/SUMMARY.md b/tools/nixery/docs/src/SUMMARY.md
new file mode 100644
index 000000000000..5d680b82e8d9
--- /dev/null
+++ b/tools/nixery/docs/src/SUMMARY.md
@@ -0,0 +1,4 @@
+# Summary
+
+- [Nixery](./nixery.md)
+- [Nix, the language](./nix-1p.md)
diff --git a/tools/nixery/docs/src/nix-1p.md b/tools/nixery/docs/src/nix-1p.md
new file mode 100644
index 000000000000..a21234150fc7
--- /dev/null
+++ b/tools/nixery/docs/src/nix-1p.md
@@ -0,0 +1,2 @@
+This page is a placeholder. During the build process, it is replaced by the
+actual `nix-1p` guide from https://github.com/tazjin/nix-1p
diff --git a/tools/nixery/static/nixery-logo.png b/tools/nixery/docs/src/nixery-logo.png
index fcf77df3d6a9..fcf77df3d6a9 100644
--- a/tools/nixery/static/nixery-logo.png
+++ b/tools/nixery/docs/src/nixery-logo.png
Binary files differdiff --git a/tools/nixery/docs/src/nixery.md b/tools/nixery/docs/src/nixery.md
new file mode 100644
index 000000000000..d3d1911d2880
--- /dev/null
+++ b/tools/nixery/docs/src/nixery.md
@@ -0,0 +1,77 @@
+![Nixery](./nixery-logo.png)
+
+------------
+
+Welcome to this instance of [Nixery][]. It provides ad-hoc container images that
+contain packages from the [Nix][] package manager. Images with arbitrary
+packages can be requested via the image name.
+
+Nix not only provides the packages to include in the images, but also builds the
+images themselves by using an interesting layering strategy described in [this
+blog post][layers].
+
+## Quick start
+
+Simply pull an image from this registry, separating each package you want
+included by a slash:
+
+    docker pull nixery.dev/shell/git/htop
+
+This gives you an image with `git`, `htop` and an interactively configured
+shell. You could run it like this:
+
+    docker run -ti nixery.dev/shell/git/htop bash
+
+Each path segment corresponds either to a key in the Nix package set, or a
+meta-package that automatically expands to several other packages.
+
+Meta-packages **must** be the first path component if they are used. Currently
+the only meta-package is `shell`, which provides a `bash`-shell with interactive
+configuration and standard tools like `coreutils`.
+
+**Tip:** When pulling from a private Nixery instance, replace `nixery.dev` in
+the above examples with your registry address.
+
+## FAQ
+
+If you have a question that is not answered here, feel free to file an issue on
+Github so that we can get it included in this section. The volume of questions
+is quite low, thus by definition your question is already frequently asked.
+
+### Where is the source code for this?
+
+Over [on Github][Nixery]. It is licensed under the Apache 2.0 license. Consult
+the documentation entries in the sidebar for information on how to set up your
+own instance of Nixery.
+
+### Which revision of `nixpkgs` is used for the builds?
+
+The instance at `nixery.dev` tracks a recent NixOS channel, currently NixOS
+19.03. The channel is updated several times a day.
+
+Private registries might be configured to track a different channel (such as
+`nixos-unstable`) or even track a git repository with custom packages.
+
+### Is this an official Google project?
+
+**No.** Nixery is not officially supported by Google.
+
+### Should I depend on `nixery.dev` in production?
+
+While we appreciate the enthusiasm, if you would like to use Nixery in your
+production project we recommend setting up a private instance. The public Nixery
+at `nixery.dev` is run on a best-effort basis and we make no guarantees about
+availability.
+
+### Who made this?
+
+Nixery was written mostly by [tazjin][].
+
+[grahamc][] authored the image layering strategy. Many people have contributed
+to Nix over time, maybe you could become one of them?
+
+[Nixery]: https://github.com/google/nixery
+[Nix]: https://nixos.org/nix
+[layers]: https://grahamc.com/blog/nix-and-layered-docker-images
+[tazjin]: https://github.com/tazjin
+[grahamc]: https://github.com/grahamc
diff --git a/tools/nixery/docs/theme/favicon.png b/tools/nixery/docs/theme/favicon.png
new file mode 100644
index 000000000000..f510bde197ac
--- /dev/null
+++ b/tools/nixery/docs/theme/favicon.png
Binary files differdiff --git a/tools/nixery/docs/theme/nixery.css b/tools/nixery/docs/theme/nixery.css
new file mode 100644
index 000000000000..c240e693d550
--- /dev/null
+++ b/tools/nixery/docs/theme/nixery.css
@@ -0,0 +1,3 @@
+h2, h3 {
+  margin-top: 1em;
+}
diff --git a/tools/nixery/static/favicon.ico b/tools/nixery/static/favicon.ico
deleted file mode 100644
index 7523e8513950..000000000000
--- a/tools/nixery/static/favicon.ico
+++ /dev/null
Binary files differdiff --git a/tools/nixery/static/index.html b/tools/nixery/static/index.html
deleted file mode 100644
index 24aa879a535d..000000000000
--- a/tools/nixery/static/index.html
+++ /dev/null
@@ -1,108 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Nixery</title>
-    <style>
-      body {
-        margin: 40px auto;
-        max-width: 650px;
-        line-height: 1.6;
-        font-size: 18px;
-        color: #444;
-        padding: 010px
-      }
-
-      .logo {
-          max-width: 650px;
-      }
-
-      h1, h2, h3 {
-        line-height: 1.2
-      }
-    </style>
-  </head>
-  <body>
-    <header>
-      <div align="center">
-        <img class="logo" src="nixery-logo.png">
-      </div>
-      <aside>ad-hoc container images - powered by <a href="https://nixos.org/nix/">Nix</a></aside>
-      <hr>
-    </header>
-
-    <p>
-      This is an instance
-      of <a href="https://github.com/google/nixery">Nixery</a>, which
-      provides the ability to pull ad-hoc container images from a
-      Docker-compatible registry server. The image names specify the
-      contents the image should contain, which are then retrieved and
-      built by the Nix package manager.
-    </p>
-    <p>
-      Nix is also responsible for the creation of the container images
-      themselves. To do this it uses an interesting layering strategy
-      described in
-      <a href="https://grahamc.com/blog/nix-and-layered-docker-images">this blog post</a>.
-    </p>
-    <h3>How does it work?</h3>
-    <p>
-      Simply point your local Docker installation (or other compatible
-      registry client) at Nixery and ask for an image with the
-      contents you desire. Image contents are path separated in the
-      name, so for example if you needed an image that contains a
-      shell and <code>emacs</code> you could pull it as such:
-    </p>
-    <p>
-      <code>nixery.dev/shell/emacs25-nox</code>
-    </p>
-    <p>
-      Image tags are currently ignored. Every package name needs to
-      correspond to a key in the
-      <a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix">nixpkgs package set</a>.
-    </p>
-    <p>
-      The special meta-package <i>shell </i> provides default packages
-      you would expect in an interactive environment (such as an
-      interactively configured bash). If you use this package
-      you <b>must</b> specify it as the first package in an image.
-    </p>
-    <h3>FAQ</h3>
-    <ul>
-      <li>
-        <strong>Where is the source code for this?</strong>
-        <br>
-        Over <a href="https://github.com/google/nixery">on Github</a>.
-      </li>
-      <li>
-        <strong>Which revision of <code>nixpkgs</code> is used?</strong>
-        <br>
-        Nixery imports a Nix channel
-        via <code>builtins.fetchTarball</code>. Currently the channel
-        to which this instance is pinned is NixOS 19.03.
-      </li>
-      <li>
-        <strong>Is this an official Google project?</strong>
-        <br>
-        <strong>No.</strong> Nixery is not officially supported by
-        Google.
-      </li>
-      <li>
-        <strong>Can I depend on the demo instance in production?</strong>
-        <br>
-        <strong>No.</strong> The demo instance is just a demo. It
-        might go down, move, or disappear entirely at any point.
-        <br>
-        To make use of Nixery in your project, please deploy a private
-        instance. Stay tuned for instructions for how to do this on
-        GKE.
-      </li>
-      <li>
-        <strong>Who made this?</strong>
-        <br>
-        <a href="https://github.com/tazjin">tazjin</a>
-      </li>
-    </ul>
-  </body>
-</html>