Bump stable to latest MkDocs and to Material for MkDocs

Author: mpilgrem

doc/css/extra.css

@@ -1,3 +1,12 @@
 .hidden-warning {
     display: none
 }
+
+/* The Read the Docs flyout is formatted with a font-size that is 90% of the
+body's. Material for MkDocs has a body font-size that is 0.5rem. This body
+font-size will result in the flyout having a font-size of 0.7rem, consistent
+with the font-size of other elements in the theme.
+*/
+body {
+    font-size: 0.777778rem;
+}

doc/requirements.txt

@@ -0,0 +1,14 @@
+# pip requirements file for MkDocs, used by Read The Docs
+#
+# See:
+#
+# The Read The Docs recommendation to 'pin' the MkDocs version used to build
+# documentation:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#pinning-dependencies
+#
+# The pip guide to its requirements file format:
+# https://pip.pypa.io/en/stable/reference/requirements-file-format/
+#
+# Current version as at 31 August 2022
+mkdocs==1.3.1
+mkdocs-material

mkdocs.yml

@@ -6,13 +6,22 @@ edit_uri: tree/stable/doc/
 copyright: Copyright (c) 2015-2022, Stack contributors
 docs_dir: doc
 site_dir: _site
-theme: readthedocs
+theme:
+  name: material
+    palette:
+    primary: 'deep purple'
+    accent: 'deep purple'
+  icon:
+    logo: material/language-haskell
 extra_css:
 - css/extra.css
 extra_javascript:
 - js/searchhack.js
+# Read the Docs requires JQuery for its JavaScript code to inject the flyout
+# menu. Material for MkDocs does not come with JQuery.
+- 'https://code.jquery.com/jquery-3.6.1.min.js'
 
-pages:
+nav:
 - Home: README.md
 - Changelog: ChangeLog.md
 - Tool documentation:
@@ -40,8 +49,9 @@ pages:
 - Advanced documentation:
   - Build overview: build_overview.md
 - Project documentation:
-  - Contributor's guide: CONTRIBUTING.md
-- Maintainer's guide:
+  - Contributors:
+    - Contributor's guide: CONTRIBUTING.md
+- Maintainers:
   - Releases: maintainers/releases.md
   - Maintainer team process: maintainers/team_process.md
   - Add GHC version: maintainers/ghc.md
@@ -54,3 +64,8 @@ pages:
 markdown_extensions:
 - toc:
     permalink: true
+- pymdownx.highlight:
+    anchor_linenums: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.superfences