docs: add mdbook-admonish

.github/workflows/pages.yml

@@ -44,6 +44,7 @@ jobs:
         env:
           ACTIONS_ALLOW_UNSECURE_COMMANDS: "true"
       - uses: actions/cache@v3
+        name: Cache mdbook
         with:
           path: |
             ~/.cargo/bin/
@@ -60,6 +61,9 @@ jobs:
       - name: Install mdBook mermaid
         run: |
           (test -x ~/.cargo/bin/mdbook-mermaid || (cd && cargo install mdbook-mermaid --locked))
+      - name: Install mdBook admonish
+        run: |
+          (test -x ~/.cargo/bin/mdbook-admonish || (cd && cargo install mdbook-admonish --locked))
       - name: Install gelatyx
         run: |
           (test -x ~/.cargo/bin/gelatyx || (cd && cargo install gelatyx --version "^0.2" --locked))

.github/workflows/verify-pages.yml

@@ -25,18 +25,30 @@ jobs:
           curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
           source $HOME/.cargo/env
           rustup update stable
-      - name: Cache mdBook
+      - uses: actions/cache@v3
-        uses: actions/cache@v1
+        name: Cache mdbook
         with:
-          path: ~/mdbook-bin
+          path: |
-          key: cargo-bin-mdbook-2
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('.github/workflows/verify-pages.yml') }}
       - name: Install mdBook
         run: |
-          mkdir -p ~/mdbook-bin
+          (test -x ~/.cargo/bin/mdbook || (cd && cargo install mdbook --no-default-features --features search --vers "^0.4" --locked))
-          (test -x ~/mdbook-bin/mdbook || (cd && cargo install --vers "^0.4" mdbook && cp -p ~/.cargo/bin/mdbook ~/mdbook-bin))
+      - name: Install mdBook linkcheck
-          (test -x ~/mdbook-bin/mdbook-linkcheck || (cd && cargo install mdbook-linkcheck && cp -p ~/.cargo/bin/mdbook-linkcheck ~/mdbook-bin))
+        run: |
-          (test -x ~/mdbook-bin/mdbook-mermaid || (cd && cargo install mdbook-mermaid && cp -p ~/.cargo/bin/mdbook-mermaid ~/mdbook-bin))
+         (test -x ~/.cargo/bin/mdbook-linkcheck || (cd && cargo install mdbook-linkcheck --locked))
-          (test -x ~/mdbook-bin/gelatyx || (cd && cargo install gelatyx --version "^0.2" && cp -p ~/.cargo/bin/gelatyx ~/mdbook-bin))
+      - name: Install mdBook mermaid
+        run: |
+          (test -x ~/.cargo/bin/mdbook-mermaid || (cd && cargo install mdbook-mermaid --locked))
+      - name: Install mdBook admonish
+        run: |
+          (test -x ~/.cargo/bin/mdbook-admonish || (cd && cargo install mdbook-admonish --locked))
+      - name: Install gelatyx
+        run: |
+          (test -x ~/.cargo/bin/gelatyx || (cd && cargo install gelatyx --version "^0.2" --locked))
       - name: Build
         run: |
           source $HOME/.cargo/env

ci/build-docs.sh

@@ -1,5 +1,11 @@
 #!/bin/bash
 
+for util in mdbook mdbook-linkcheck mdbook-mermaid mdbook-admonish gelatyx ; do
+  if ! hash $util 2>/dev/null ; then
+    cargo install $util --locked
+  fi
+done
+
 tracked_markdown=$(mktemp)
 trap "rm ${tracked_markdown}" "EXIT"
 git ls-tree -r HEAD --name-only docs | egrep '\.(markdown|md)$' > $tracked_markdown

docs/book.toml

@@ -8,7 +8,7 @@ build-dir = "../gh_pages"
 create-missing = false
 
 [output.html]
-additional-css = ["custom.css", "asciinema-player.css"]
+additional-css = ["custom.css", "asciinema-player.css", "mdbook-admonish.css"]
 default-theme = "ayu"
 preferred-dark-theme = "ayu"
 git-repository-url = "https://github.com/wez/wezterm"
@@ -25,3 +25,7 @@ traverse-parent-directories = false
 
 [preprocessor.mermaid]
 command = "mdbook-mermaid"
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "2.0.0" # do not edit: managed by `mdbook-admonish install`

docs/config/lua/config/window_decorations.md

@@ -28,13 +28,17 @@ When the resizable border is disabled you will need to use features of your
 desktop environment to resize the window.  Windows users may wish to consider
 [AltSnap](https://github.com/RamonUnch/AltSnap).
 
+```admonish warning
 Think twice before removing `RESIZE` from the set of decorations as it causes
 problems with resizing and minimizing the window. You usually want to keep
 `RESIZE` enabled.
+```
 
 If you just want to remove the title bar, set `window_decorations = "RESIZE"`
 as you will run into problems if you remove `RESIZE` from the set of
 decorations.
 
+```admonish
 You probably always want `RESIZE` to be listed in your `window_decorations`.
+```
 

docs/mdbook-admonish.css

@@ -0,0 +1,352 @@
+@charset "UTF-8";
+:root {
+  --md-admonition-icon--note:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z'/></svg>");
+  --md-admonition-icon--abstract:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M17 9H7V7h10m0 6H7v-2h10m-3 6H7v-2h7M12 3a1 1 0 0 1 1 1 1 1 0 0 1-1 1 1 1 0 0 1-1-1 1 1 0 0 1 1-1m7 0h-4.18C14.4 1.84 13.3 1 12 1c-1.3 0-2.4.84-2.82 2H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2z'/></svg>");
+  --md-admonition-icon--info:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M13 9h-2V7h2m0 10h-2v-6h2m-1-9A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2z'/></svg>");
+  --md-admonition-icon--tip:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M17.66 11.2c-.23-.3-.51-.56-.77-.82-.67-.6-1.43-1.03-2.07-1.66C13.33 7.26 13 4.85 13.95 3c-.95.23-1.78.75-2.49 1.32-2.59 2.08-3.61 5.75-2.39 8.9.04.1.08.2.08.33 0 .22-.15.42-.35.5-.23.1-.47.04-.66-.12a.58.58 0 0 1-.14-.17c-1.13-1.43-1.31-3.48-.55-5.12C5.78 10 4.87 12.3 5 14.47c.06.5.12 1 .29 1.5.14.6.41 1.2.71 1.73 1.08 1.73 2.95 2.97 4.96 3.22 2.14.27 4.43-.12 6.07-1.6 1.83-1.66 2.47-4.32 1.53-6.6l-.13-.26c-.21-.46-.77-1.26-.77-1.26m-3.16 6.3c-.28.24-.74.5-1.1.6-1.12.4-2.24-.16-2.9-.82 1.19-.28 1.9-1.16 2.11-2.05.17-.8-.15-1.46-.28-2.23-.12-.74-.1-1.37.17-2.06.19.38.39.76.63 1.06.77 1 1.98 1.44 2.24 2.8.04.14.06.28.06.43.03.82-.33 1.72-.93 2.27z'/></svg>");
+  --md-admonition-icon--success:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='m9 20.42-6.21-6.21 2.83-2.83L9 14.77l9.88-9.89 2.83 2.83L9 20.42z'/></svg>");
+  --md-admonition-icon--question:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='m15.07 11.25-.9.92C13.45 12.89 13 13.5 13 15h-2v-.5c0-1.11.45-2.11 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41a2 2 0 0 0-2-2 2 2 0 0 0-2 2H8a4 4 0 0 1 4-4 4 4 0 0 1 4 4 3.2 3.2 0 0 1-.93 2.25M13 19h-2v-2h2M12 2A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10c0-5.53-4.5-10-10-10z'/></svg>");
+  --md-admonition-icon--warning:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M13 14h-2V9h2m0 9h-2v-2h2M1 21h22L12 2 1 21z'/></svg>");
+  --md-admonition-icon--failure:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M20 6.91 17.09 4 12 9.09 6.91 4 4 6.91 9.09 12 4 17.09 6.91 20 12 14.91 17.09 20 20 17.09 14.91 12 20 6.91z'/></svg>");
+  --md-admonition-icon--danger:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M11 15H6l7-14v8h5l-7 14v-8z'/></svg>");
+  --md-admonition-icon--bug:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a5.985 5.985 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6.002 6.002 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20V8z'/></svg>");
+  --md-admonition-icon--example:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M7 13v-2h14v2H7m0 6v-2h14v2H7M7 7V5h14v2H7M3 8V5H2V4h2v4H3m-1 9v-1h3v4H2v-1h2v-.5H3v-1h1V17H2m2.25-7a.75.75 0 0 1 .75.75c0 .2-.08.39-.21.52L3.12 13H5v1H2v-.92L4 11H2v-1h2.25z'/></svg>");
+  --md-admonition-icon--quote:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M14 17h3l2-4V7h-6v6h3M6 17h3l2-4V7H5v6h3l-2 4z'/></svg>");
+  --md-details-icon:
+    url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M8.59 16.58 13.17 12 8.59 7.41 10 6l6 6-6 6-1.41-1.42Z'/></svg>");
+}
+
+:is(.admonition) {
+  display: flow-root;
+  margin: 1.5625em 0;
+  padding: 0 1.2rem;
+  color: var(--fg);
+  page-break-inside: avoid;
+  background-color: var(--bg);
+  border: 0 solid black;
+  border-inline-start-width: 0.4rem;
+  border-radius: 0.2rem;
+  box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05), 0 0 0.1rem rgba(0, 0, 0, 0.1);
+}
+@media print {
+  :is(.admonition) {
+    box-shadow: none;
+  }
+}
+:is(.admonition) > * {
+  box-sizing: border-box;
+}
+:is(.admonition) :is(.admonition) {
+  margin-top: 1em;
+  margin-bottom: 1em;
+}
+:is(.admonition) > .tabbed-set:only-child {
+  margin-top: 0;
+}
+html :is(.admonition) > :last-child {
+  margin-bottom: 1.2rem;
+}
+
+a.admonition-anchor-link {
+  display: none;
+  position: absolute;
+  left: -1.2rem;
+  padding-right: 1rem;
+}
+a.admonition-anchor-link:link, a.admonition-anchor-link:visited {
+  color: var(--fg);
+}
+a.admonition-anchor-link:link:hover, a.admonition-anchor-link:visited:hover {
+  text-decoration: none;
+}
+a.admonition-anchor-link::before {
+  content: "§";
+}
+
+:is(.admonition-title, summary) {
+  position: relative;
+  margin-block: 0;
+  margin-inline: -1.6rem -1.2rem;
+  padding-block: 0.8rem;
+  padding-inline: 4.4rem 1.2rem;
+  font-weight: 700;
+  background-color: rgba(68, 138, 255, 0.1);
+  display: flex;
+}
+:is(.admonition-title, summary) p {
+  margin: 0;
+}
+html :is(.admonition-title, summary):last-child {
+  margin-bottom: 0;
+}
+:is(.admonition-title, summary)::before {
+  position: absolute;
+  top: 0.625em;
+  inset-inline-start: 1.6rem;
+  width: 2rem;
+  height: 2rem;
+  background-color: #448aff;
+  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>');
+  -webkit-mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>');
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-size: contain;
+  content: "";
+}
+:is(.admonition-title, summary):hover a.admonition-anchor-link {
+  display: initial;
+}
+
+details.admonition > summary.admonition-title::after {
+  position: absolute;
+  top: 0.625em;
+  inset-inline-end: 1.6rem;
+  height: 2rem;
+  width: 2rem;
+  background-color: currentcolor;
+  mask-image: var(--md-details-icon);
+  -webkit-mask-image: var(--md-details-icon);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-size: contain;
+  content: "";
+  transform: rotate(0deg);
+  transition: transform 0.25s;
+}
+details[open].admonition > summary.admonition-title::after {
+  transform: rotate(90deg);
+}
+
+:is(.admonition):is(.note) {
+  border-color: #448aff;
+}
+
+:is(.note) > :is(.admonition-title, summary) {
+  background-color: rgba(68, 138, 255, 0.1);
+}
+:is(.note) > :is(.admonition-title, summary)::before {
+  background-color: #448aff;
+  mask-image: var(--md-admonition-icon--note);
+  -webkit-mask-image: var(--md-admonition-icon--note);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.abstract, .summary, .tldr) {
+  border-color: #00b0ff;
+}
+
+:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary) {
+  background-color: rgba(0, 176, 255, 0.1);
+}
+:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary)::before {
+  background-color: #00b0ff;
+  mask-image: var(--md-admonition-icon--abstract);
+  -webkit-mask-image: var(--md-admonition-icon--abstract);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.info, .todo) {
+  border-color: #00b8d4;
+}
+
+:is(.info, .todo) > :is(.admonition-title, summary) {
+  background-color: rgba(0, 184, 212, 0.1);
+}
+:is(.info, .todo) > :is(.admonition-title, summary)::before {
+  background-color: #00b8d4;
+  mask-image: var(--md-admonition-icon--info);
+  -webkit-mask-image: var(--md-admonition-icon--info);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.tip, .hint, .important) {
+  border-color: #00bfa5;
+}
+
+:is(.tip, .hint, .important) > :is(.admonition-title, summary) {
+  background-color: rgba(0, 191, 165, 0.1);
+}
+:is(.tip, .hint, .important) > :is(.admonition-title, summary)::before {
+  background-color: #00bfa5;
+  mask-image: var(--md-admonition-icon--tip);
+  -webkit-mask-image: var(--md-admonition-icon--tip);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.success, .check, .done) {
+  border-color: #00c853;
+}
+
+:is(.success, .check, .done) > :is(.admonition-title, summary) {
+  background-color: rgba(0, 200, 83, 0.1);
+}
+:is(.success, .check, .done) > :is(.admonition-title, summary)::before {
+  background-color: #00c853;
+  mask-image: var(--md-admonition-icon--success);
+  -webkit-mask-image: var(--md-admonition-icon--success);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.question, .help, .faq) {
+  border-color: #64dd17;
+}
+
+:is(.question, .help, .faq) > :is(.admonition-title, summary) {
+  background-color: rgba(100, 221, 23, 0.1);
+}
+:is(.question, .help, .faq) > :is(.admonition-title, summary)::before {
+  background-color: #64dd17;
+  mask-image: var(--md-admonition-icon--question);
+  -webkit-mask-image: var(--md-admonition-icon--question);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.warning, .caution, .attention) {
+  border-color: #ff9100;
+}
+
+:is(.warning, .caution, .attention) > :is(.admonition-title, summary) {
+  background-color: rgba(255, 145, 0, 0.1);
+}
+:is(.warning, .caution, .attention) > :is(.admonition-title, summary)::before {
+  background-color: #ff9100;
+  mask-image: var(--md-admonition-icon--warning);
+  -webkit-mask-image: var(--md-admonition-icon--warning);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.failure, .fail, .missing) {
+  border-color: #ff5252;
+}
+
+:is(.failure, .fail, .missing) > :is(.admonition-title, summary) {
+  background-color: rgba(255, 82, 82, 0.1);
+}
+:is(.failure, .fail, .missing) > :is(.admonition-title, summary)::before {
+  background-color: #ff5252;
+  mask-image: var(--md-admonition-icon--failure);
+  -webkit-mask-image: var(--md-admonition-icon--failure);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.danger, .error) {
+  border-color: #ff1744;
+}
+
+:is(.danger, .error) > :is(.admonition-title, summary) {
+  background-color: rgba(255, 23, 68, 0.1);
+}
+:is(.danger, .error) > :is(.admonition-title, summary)::before {
+  background-color: #ff1744;
+  mask-image: var(--md-admonition-icon--danger);
+  -webkit-mask-image: var(--md-admonition-icon--danger);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.bug) {
+  border-color: #f50057;
+}
+
+:is(.bug) > :is(.admonition-title, summary) {
+  background-color: rgba(245, 0, 87, 0.1);
+}
+:is(.bug) > :is(.admonition-title, summary)::before {
+  background-color: #f50057;
+  mask-image: var(--md-admonition-icon--bug);
+  -webkit-mask-image: var(--md-admonition-icon--bug);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.example) {
+  border-color: #7c4dff;
+}
+
+:is(.example) > :is(.admonition-title, summary) {
+  background-color: rgba(124, 77, 255, 0.1);
+}
+:is(.example) > :is(.admonition-title, summary)::before {
+  background-color: #7c4dff;
+  mask-image: var(--md-admonition-icon--example);
+  -webkit-mask-image: var(--md-admonition-icon--example);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+:is(.admonition):is(.quote, .cite) {
+  border-color: #9e9e9e;
+}
+
+:is(.quote, .cite) > :is(.admonition-title, summary) {
+  background-color: rgba(158, 158, 158, 0.1);
+}
+:is(.quote, .cite) > :is(.admonition-title, summary)::before {
+  background-color: #9e9e9e;
+  mask-image: var(--md-admonition-icon--quote);
+  -webkit-mask-image: var(--md-admonition-icon--quote);
+  mask-repeat: no-repeat;
+  -webkit-mask-repeat: no-repeat;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+.navy :is(.admonition) {
+  background-color: var(--sidebar-bg);
+}
+
+.ayu :is(.admonition), .coal :is(.admonition) {
+  background-color: var(--theme-hover);
+}
+
+.rust :is(.admonition) {
+  background-color: var(--sidebar-bg);
+  color: var(--sidebar-fg);
+}
+.rust .admonition-anchor-link:link, .rust .admonition-anchor-link:visited {
+  color: var(--sidebar-fg);
+}