diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 5f029fad9..6b763aec8 100644
--- a/.github/workflows/pages.yml
+++ b/.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))
diff --git a/.github/workflows/verify-pages.yml b/.github/workflows/verify-pages.yml
index 02afb2858..99d405ad6 100644
--- a/.github/workflows/verify-pages.yml
+++ b/.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@v1
+ - uses: actions/cache@v3
+ name: Cache mdbook
with:
- path: ~/mdbook-bin
- key: cargo-bin-mdbook-2
+ path: |
+ ~/.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 ~/mdbook-bin/mdbook || (cd && cargo install --vers "^0.4" mdbook && cp -p ~/.cargo/bin/mdbook ~/mdbook-bin))
- (test -x ~/mdbook-bin/mdbook-linkcheck || (cd && cargo install mdbook-linkcheck && cp -p ~/.cargo/bin/mdbook-linkcheck ~/mdbook-bin))
- (test -x ~/mdbook-bin/mdbook-mermaid || (cd && cargo install mdbook-mermaid && cp -p ~/.cargo/bin/mdbook-mermaid ~/mdbook-bin))
- (test -x ~/mdbook-bin/gelatyx || (cd && cargo install gelatyx --version "^0.2" && cp -p ~/.cargo/bin/gelatyx ~/mdbook-bin))
+ (test -x ~/.cargo/bin/mdbook || (cd && cargo install mdbook --no-default-features --features search --vers "^0.4" --locked))
+ - name: Install mdBook linkcheck
+ run: |
+ (test -x ~/.cargo/bin/mdbook-linkcheck || (cd && cargo install mdbook-linkcheck --locked))
+ - 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
diff --git a/ci/build-docs.sh b/ci/build-docs.sh
index eb1db9666..fc7f7664b 100755
--- a/ci/build-docs.sh
+++ b/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
diff --git a/docs/book.toml b/docs/book.toml
index 122c1dab5..5405355ab 100644
--- a/docs/book.toml
+++ b/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`
diff --git a/docs/config/lua/config/window_decorations.md b/docs/config/lua/config/window_decorations.md
index af8346e1b..1a3dbdd52 100644
--- a/docs/config/lua/config/window_decorations.md
+++ b/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`.
+```
diff --git a/docs/mdbook-admonish.css b/docs/mdbook-admonish.css
new file mode 100644
index 000000000..5e360387d
--- /dev/null
+++ b/docs/mdbook-admonish.css
@@ -0,0 +1,352 @@
+@charset "UTF-8";
+:root {
+ --md-admonition-icon--note:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--abstract:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--info:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--tip:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--success:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--question:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--warning:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--failure:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--danger:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--bug:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--example:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-admonition-icon--quote:
+ url("data:image/svg+xml;charset=utf-8,");
+ --md-details-icon:
+ url("data:image/svg+xml;charset=utf-8,");
+}
+
+: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,');
+ -webkit-mask-image: url('data:image/svg+xml;charset=utf-8,');
+ 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);
+}