service/documentation.md

@@ -892,6 +892,10 @@ WARNING -  Documentation file 'service/lists.md' contains a link to 'service/org
 A full rebuild of the site takes 2.18 seconds. Incremental rebuilds
 are not faster, which is somewhat worrisome.
 
+Another problem with mkdocs is that the sidebar table of contents is
+not scrollable. It also doesn't seem to outline nested headings below
+H2 correctly.
+
 ### hugo
 
 Tests with hugo were really inconclusive. We had to do `hugo new site
@@ -906,6 +910,24 @@ failed to find *any* content whatsoever.
 Lektor is similarly challenging: all files would need to be re-written
 to add a `body:` tag on top and renamed to `.lr`.
 
+### mdBook
+
+mdBook has the same linking issues as mkdocs, but at least it seems
+like the same syntax.
+
+A more serious problem is that *all* pages need to listed explicitly
+in the [SUMMARY.md](https://rust-lang.github.io/mdBook/format/summary.html) file, otherwise they don't render at all, even
+if another page links to it.
+
+This means, for example, that `service.md` would need to be entirely
+rewritten (if not copied) to follow the much stricter syntax
+SUMMARY.md adheres to, and that new page would fail to build if they
+are not automatically added.
+
+In other words, I don't think it's practical to use mdBook unless we
+start explicitly enumerating all pages in the site, and i'm not sure
+we want that.
+
 ### Testing
 
 To use those tests, wikis need to be backed by a GitLab project (see