📌 Add mdbook-admonish plugin support

It's frequently desirable to have sections dedicated to aside-material
like warnings, errors, tips, etc. One such case this is already a need
in the book is to prefix certain sections as not being fully
representative for the system in its current state.

To support such a case, the dependency `mdbook-admonish` has been
adopted, which leverages material design themes to accomplish this.
Some sections have been added making use of this to verify that it does
work as intended as well.

.github/workflows/deploy-github-pages.yaml

@@ -37,6 +37,15 @@ jobs:
         with:
           target: mdbook-mermaid
 
+      - name: Install mdbook-admonish
+        uses: ./.github/actions/cargo-install
+        with:
+          target: mdbook-admonish
+
+      - name: Install mdbook-dependencies
+        working-directory: docs
+        run: mdbook-admonish install
+
       - name: Install cargo-llvm-cov
         uses: taiki-e/install-action@cargo-llvm-cov
 

docs/.gitignore

@@ -1,3 +1,4 @@
 book
 mermaid-init.js
 mermaid.min.js
+mdbook-admonish.css

docs/book.toml

@@ -8,5 +8,10 @@ title = "Alloy Game Engine (Rust)"
 [preprocessor.mermaid]
 command = "mdbook-mermaid"
 
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`
+
 [output.html]
 additional-js = ["mermaid.min.js", "mermaid-init.js"]
+additional-css = ["./mdbook-admonish.css"]

docs/src/community.md

@@ -1,5 +1,10 @@
 # Community
 
+```admonish note
+This community section aggregates the same community-contribution files that
+can be found from within the GitHub UI.
+```
+
 1. [Code of Conduct](./community/CODE_OF_CONDUCT.md)
 2. [Contributing](./community/CONTRIBUTING.md)
 3. [Project Governance](./community/GOVERNANCE.md)

docs/src/tour/editors.md

@@ -1,5 +1,10 @@
 # Tour of the Editors
 
+```admonish note
+Many of these sections are "forward-thinking" as these are still
+in-progress unless otherwise specified.
+```
+
 This section provides a tour of the different editors that are available within
 Alloy.
 

docs/src/tour/engine.md

@@ -1,5 +1,10 @@
 # Tour of the Alloy Engine
 
+```admonish note
+Many of these sections are "forward-thinking" as these are still
+in-progress unless otherwise specified.
+```
+
 This is a tour of the Alloy Engine's software integration. This section will
 provide detailed instructions to set up and prepare an Alloy application.