diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index a9fed18ba..27140a996 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -17,6 +17,26 @@ jobs:
         with:
           mdbook-version: 'latest'
 
+      - name: Cache cargo registry
+        uses: actions/cache@v1
+        with:
+          path: ~/.cargo/registry
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo build
+        uses: actions/cache@v1
+        with:
+          path: target
+          key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Create usage-docs plugin
+        run: cargo build -p taskchampion-cli --features usage-docs --bin usage-docs
+
       - run: mdbook build docs
 
       - name: Deploy
diff --git a/.github/workflows/rust-tests.yml b/.github/workflows/rust-tests.yml
index 8d9eba149..ab56e3c39 100644
--- a/.github/workflows/rust-tests.yml
+++ b/.github/workflows/rust-tests.yml
@@ -75,5 +75,25 @@ jobs:
         with:
           mdbook-version: 'latest'
 
+      - name: Cache cargo registry
+        uses: actions/cache@v1
+        with:
+          path: ~/.cargo/registry
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo build
+        uses: actions/cache@v1
+        with:
+          path: target
+          key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Create usage-docs plugin
+        run: cargo build -p taskchampion-cli --features usage-docs --bin usage-docs
+
       - run: mdbook test docs
       - run: mdbook build docs
diff --git a/Cargo.lock b/Cargo.lock
index 6853f373a..144f8e56f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -47,7 +47,7 @@ dependencies = [
  "actix-service",
  "actix-threadpool",
  "actix-utils",
- "base64",
+ "base64 0.13.0",
  "bitflags",
  "brotli2",
  "bytes 0.5.6",
@@ -76,8 +76,8 @@ dependencies = [
  "regex",
  "serde",
  "serde_json",
- "serde_urlencoded",
- "sha-1",
+ "serde_urlencoded 0.7.0",
+ "sha-1 0.9.4",
  "slab",
  "time 0.2.26",
 ]
@@ -264,7 +264,7 @@ dependencies = [
  "regex",
  "serde",
  "serde_json",
- "serde_urlencoded",
+ "serde_urlencoded 0.7.0",
  "socket2",
  "time 0.2.26",
  "tinyvec",
@@ -297,6 +297,21 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "ammonia"
+version = "3.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ee7d6eb157f337c5cedc95ddf17f0cbc36d36eb7763c8e0d1c1aeb3722f6279"
+dependencies = [
+ "html5ever",
+ "lazy_static",
+ "maplit",
+ "markup5ever_rcdom",
+ "matches",
+ "tendril",
+ "url",
+]
+
 [[package]]
 name = "ansi_term"
 version = "0.11.0"
@@ -382,7 +397,7 @@ dependencies = [
  "actix-http",
  "actix-rt 1.1.1",
  "actix-service",
- "base64",
+ "base64 0.13.0",
  "bytes 0.5.6",
  "cfg-if 1.0.0",
  "derive_more",
@@ -393,7 +408,7 @@ dependencies = [
  "rand 0.7.3",
  "serde",
  "serde_json",
- "serde_urlencoded",
+ "serde_urlencoded 0.7.0",
 ]
 
 [[package]]
@@ -402,6 +417,12 @@ version = "0.2.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a4521f3e3d031370679b3b140beb36dfe4801b09ac77e30c61941f97df3ef28b"
 
+[[package]]
+name = "base64"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3441f0f7b02788e948e47f457ca01f1d7e6d92c693bc132c22b087d3141c03ff"
+
 [[package]]
 name = "base64"
 version = "0.13.0"
@@ -452,13 +473,34 @@ dependencies = [
  "constant_time_eq",
 ]
 
+[[package]]
+name = "block-buffer"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0940dc441f31689269e10ac70eb1002a3a1d3ad1390e030043662eb7fe4688b"
+dependencies = [
+ "block-padding",
+ "byte-tools",
+ "byteorder",
+ "generic-array 0.12.4",
+]
+
 [[package]]
 name = "block-buffer"
 version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4152116fd6e9dadb291ae18fc1ec3575ed6d84c29642d97890f4b4a3417297e4"
 dependencies = [
- "generic-array",
+ "generic-array 0.14.4",
+]
+
+[[package]]
+name = "block-padding"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa79dedbb091f449f1f39e53edf88d5dbe95f895dae6135a8d7b881fb5af73f5"
+dependencies = [
+ "byte-tools",
 ]
 
 [[package]]
@@ -499,6 +541,12 @@ version = "3.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63396b8a4b9de3f4fdfb320ab6080762242f66a8ef174c49d8e19b674db4cdbe"
 
+[[package]]
+name = "byte-tools"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7"
+
 [[package]]
 name = "byteorder"
 version = "1.4.3"
@@ -693,13 +741,22 @@ version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "524cbf6897b527295dff137cec09ecf3a05f4fddffd7dfcd1585403449e74198"
 
+[[package]]
+name = "digest"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3d0c8c8752312f9713efd397ff63acb9f85585afbf179282e720e7704954dd5"
+dependencies = [
+ "generic-array 0.12.4",
+]
+
 [[package]]
 name = "digest"
 version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d3dd60d1080a57a05ab032377049e0591415d2b31afd7028356dbf3cc6dcb066"
 dependencies = [
- "generic-array",
+ "generic-array 0.14.4",
 ]
 
 [[package]]
@@ -746,12 +803,33 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10"
 
+[[package]]
+name = "dtoa"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56899898ce76aaf4a0f24d914c97ea6ed976d42fec6ad33fcbb0a1103e07b2b0"
+
 [[package]]
 name = "either"
 version = "1.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e78d4f1cc4ae33bbfc157ed5d5a5ef3bc29227303d595861deb238fcec4e9457"
 
+[[package]]
+name = "elasticlunr-rs"
+version = "2.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "959fbc9a6ebced545cbe365fdce5e25c6ab7683f2ca4ecc9fb9d0db663bf73d5"
+dependencies = [
+ "lazy_static",
+ "regex",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "strum",
+ "strum_macros",
+]
+
 [[package]]
 name = "encode_unicode"
 version = "0.3.6"
@@ -779,6 +857,19 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "env_logger"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44533bbbb3bb3c1fa17d9f2e4e38bbbaf8396ba82193c4cb1b6445d711445d36"
+dependencies = [
+ "atty",
+ "humantime 1.3.0",
+ "log",
+ "regex",
+ "termcolor",
+]
+
 [[package]]
 name = "env_logger"
 version = "0.8.3"
@@ -786,12 +877,30 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "17392a012ea30ef05a610aa97dfb49496e71c9f676b27879922ea5bdf60d9d3f"
 dependencies = [
  "atty",
- "humantime",
+ "humantime 2.1.0",
  "log",
  "regex",
  "termcolor",
 ]
 
+[[package]]
+name = "fake-simd"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e88a8acf291dafb59c2d96e8f59828f3838bb1a70398823ade51a84de6a6deed"
+
+[[package]]
+name = "filetime"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d34cfa13a63ae058bfa601fe9e313bbdb3746427c1459185464ce0fcf62e1e8"
+dependencies = [
+ "cfg-if 1.0.0",
+ "libc",
+ "redox_syscall 0.2.6",
+ "winapi 0.3.9",
+]
+
 [[package]]
 name = "flate2"
 version = "1.0.20"
@@ -829,6 +938,25 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fsevent"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ab7d1bd1bd33cc98b0889831b72da23c0aa4df9cec7e0702f46ecea04b35db6"
+dependencies = [
+ "bitflags",
+ "fsevent-sys",
+]
+
+[[package]]
+name = "fsevent-sys"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41b048a94555da0f42f1d632e2e19510084fb8e303b0daa2816e733fb3644a0"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "fuchsia-zircon"
 version = "0.3.3"
@@ -851,6 +979,16 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fed34cd105917e91daa4da6b3728c47b068749d6a62c59811f06ed2ac71d9da7"
 
+[[package]]
+name = "futf"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c9c1ce3fa9336301af935ab852c437817d14cd33690446569392e65170aac3b"
+dependencies = [
+ "mac",
+ "new_debug_unreachable",
+]
+
 [[package]]
 name = "futures"
 version = "0.3.14"
@@ -952,6 +1090,15 @@ dependencies = [
  "byteorder",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.12.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ffdf9f34f1447443d37393cc6c2b8313aebddcd96906caf34e54c68d8e57d7bd"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "generic-array"
 version = "0.14.4"
@@ -962,6 +1109,15 @@ dependencies = [
  "version_check",
 ]
 
+[[package]]
+name = "getopts"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "14dbbfd5c71d70241ecf9e6f13737f7b5ce823821063188d7e46c41d371eebd5"
+dependencies = [
+ "unicode-width",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.1.16"
@@ -984,6 +1140,21 @@ dependencies = [
  "wasi 0.10.2+wasi-snapshot-preview1",
 ]
 
+[[package]]
+name = "gitignore"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78aa90e4620c1498ac434c06ba6e521b525794bbdacf085d490cc794b4a2f9a4"
+dependencies = [
+ "glob",
+]
+
+[[package]]
+name = "glob"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b919933a397b79c37e33b77bb2aa3dc8eb6e165ad809e58ff75bc7db2e34574"
+
 [[package]]
 name = "h2"
 version = "0.2.7"
@@ -1004,12 +1175,51 @@ dependencies = [
  "tracing-futures",
 ]
 
+[[package]]
+name = "handlebars"
+version = "3.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4498fc115fa7d34de968184e473529abb40eeb6be8bc5f7faba3d08c316cb3e3"
+dependencies = [
+ "log",
+ "pest",
+ "pest_derive",
+ "quick-error 2.0.0",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d7afe4a420e3fe79967a00898cc1f4db7c8a49a9333a29f8a4bd76a253d5cd04"
 
+[[package]]
+name = "headers"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0b7591fb62902706ae8e7aaff416b1b0fa2c0fd0878b46dc13baa3712d8a855"
+dependencies = [
+ "base64 0.13.0",
+ "bitflags",
+ "bytes 1.0.1",
+ "headers-core",
+ "http",
+ "mime",
+ "sha-1 0.9.4",
+ "time 0.1.43",
+]
+
+[[package]]
+name = "headers-core"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7f66481bfee273957b1f20485a4ff3362987f85b2c236580d81b4eb7a326429"
+dependencies = [
+ "http",
+]
+
 [[package]]
 name = "heck"
 version = "0.3.2"
@@ -1039,6 +1249,20 @@ dependencies = [
  "winapi 0.3.9",
 ]
 
+[[package]]
+name = "html5ever"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aafcf38a1a36118242d29b92e1b08ef84e67e4a5ed06e0a80be20e6a32bfed6b"
+dependencies = [
+ "log",
+ "mac",
+ "markup5ever",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "http"
 version = "0.2.4"
@@ -1050,18 +1274,67 @@ dependencies = [
  "itoa",
 ]
 
+[[package]]
+name = "http-body"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13d5ff830006f7646652e057693569bfe0d51760c0085a071769d142a205111b"
+dependencies = [
+ "bytes 0.5.6",
+ "http",
+]
+
 [[package]]
 name = "httparse"
 version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4a1ce40d6fc9764887c2fdc7305c3dcc429ba11ff981c1509416afd5697e4437"
 
+[[package]]
+name = "httpdate"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "494b4d60369511e7dea41cf646832512a94e542f68bb9c49e54518e0f468eb47"
+
+[[package]]
+name = "humantime"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df004cfca50ef23c36850aaaa59ad52cc70d0e90243c3c7737a4dd32dc7a3c4f"
+dependencies = [
+ "quick-error 1.2.3",
+]
+
 [[package]]
 name = "humantime"
 version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9a3a5bfb195931eeb336b2a7b4d761daec841b97f947d34394601737a7bba5e4"
 
+[[package]]
+name = "hyper"
+version = "0.13.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a6f157065790a3ed2f88679250419b5cdd96e714a0d65f7797fd337186e96bb"
+dependencies = [
+ "bytes 0.5.6",
+ "futures-channel",
+ "futures-core",
+ "futures-util",
+ "h2",
+ "http",
+ "http-body",
+ "httparse",
+ "httpdate",
+ "itoa",
+ "pin-project 1.0.7",
+ "socket2",
+ "tokio 0.2.25",
+ "tower-service",
+ "tracing",
+ "want",
+]
+
 [[package]]
 name = "idna"
 version = "0.2.3"
@@ -1083,6 +1356,35 @@ dependencies = [
  "hashbrown",
 ]
 
+[[package]]
+name = "inotify"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4816c66d2c8ae673df83366c18341538f234a26d65a9ecea5c348b453ac1d02f"
+dependencies = [
+ "bitflags",
+ "inotify-sys",
+ "libc",
+]
+
+[[package]]
+name = "inotify-sys"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e05c02b5e89bff3b946cedeca278abc628fe811e604f027c45a8aa3cf793d0eb"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "input_buffer"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19a8a95243d5a0398cae618ec29477c6e3cb631152be5c19481f80bc71559754"
+dependencies = [
+ "bytes 0.5.6",
+]
+
 [[package]]
 name = "instant"
 version = "0.1.9"
@@ -1163,6 +1465,12 @@ version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646"
 
+[[package]]
+name = "lazycell"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55"
+
 [[package]]
 name = "lexical-core"
 version = "0.7.5"
@@ -1261,6 +1569,44 @@ dependencies = [
  "linked-hash-map",
 ]
 
+[[package]]
+name = "mac"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c41e0c4fef86961ac6d6f8a82609f55f31b05e4fce149ac5710e439df7619ba4"
+
+[[package]]
+name = "maplit"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e2e65a1a2e43cfcb47a895c4c8b10d1f4a61097f9f254f183aee60cad9c651d"
+
+[[package]]
+name = "markup5ever"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a24f40fb03852d1cdd84330cddcaf98e9ec08a7b7768e952fad3b4cf048ec8fd"
+dependencies = [
+ "log",
+ "phf",
+ "phf_codegen",
+ "string_cache",
+ "string_cache_codegen",
+ "tendril",
+]
+
+[[package]]
+name = "markup5ever_rcdom"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f015da43bcd8d4f144559a3423f4591d69b8ce0652c905374da7205df336ae2b"
+dependencies = [
+ "html5ever",
+ "markup5ever",
+ "tendril",
+ "xml5ever",
+]
+
 [[package]]
 name = "match_cfg"
 version = "0.1.0"
@@ -1273,6 +1619,38 @@ version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7ffc5c5338469d4d3ea17d269fa8ea3512ad247247c30bd2df69e68309ed0a08"
 
+[[package]]
+name = "mdbook"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fed4060ccf332a0479df37e84c8435ad20be737d5337c3a90fa1b3b0d480a3a0"
+dependencies = [
+ "ammonia",
+ "anyhow",
+ "chrono",
+ "clap",
+ "elasticlunr-rs",
+ "env_logger 0.7.1",
+ "futures-util",
+ "gitignore",
+ "handlebars",
+ "lazy_static",
+ "log",
+ "memchr",
+ "notify",
+ "open",
+ "pulldown-cmark",
+ "regex",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "shlex",
+ "tempfile",
+ "tokio 0.2.25",
+ "toml",
+ "warp",
+]
+
 [[package]]
 name = "memchr"
 version = "2.3.4"
@@ -1285,6 +1663,16 @@ version = "0.3.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a60c7ce501c71e03a9c9c0d35b861413ae925bd979cc7a4e30d060069aaac8d"
 
+[[package]]
+name = "mime_guess"
+version = "2.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2684d4c2e97d99848d30b324b00c8fcc7e5c897b7cbb5819b09e7c90e8baf212"
+dependencies = [
+ "mime",
+ "unicase",
+]
+
 [[package]]
 name = "miniz_oxide"
 version = "0.4.4"
@@ -1327,6 +1715,18 @@ dependencies = [
  "winapi 0.3.9",
 ]
 
+[[package]]
+name = "mio-extras"
+version = "2.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52403fe290012ce777c4626790c8951324a2b9e3316b3143779c72b029742f19"
+dependencies = [
+ "lazycell",
+ "log",
+ "mio 0.6.23",
+ "slab",
+]
+
 [[package]]
 name = "mio-uds"
 version = "0.6.8"
@@ -1370,6 +1770,12 @@ dependencies = [
  "winapi 0.3.9",
 ]
 
+[[package]]
+name = "new_debug_unreachable"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4a24736216ec316047a1fc4252e27dabb04218aa4a3f37c6e7ddbf1f9782b54"
+
 [[package]]
 name = "nom"
 version = "6.1.2"
@@ -1389,6 +1795,24 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "61807f77802ff30975e01f4f071c8ba10c022052f98b3294119f3e615d13e5be"
 
+[[package]]
+name = "notify"
+version = "4.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae03c8c853dba7bfd23e571ff0cff7bc9dceb40a4cd684cd1681824183f45257"
+dependencies = [
+ "bitflags",
+ "filetime",
+ "fsevent",
+ "fsevent-sys",
+ "inotify",
+ "libc",
+ "mio 0.6.23",
+ "mio-extras",
+ "walkdir",
+ "winapi 0.3.9",
+]
+
 [[package]]
 name = "ntapi"
 version = "0.3.6"
@@ -1433,12 +1857,28 @@ version = "1.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "af8b08b04175473088b46763e51ee54da5f9a164bc162f615b91bc179dbf15a3"
 
+[[package]]
+name = "opaque-debug"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2839e79665f131bdb5782e51f2c6c9599c133c6098982a54c794358bf432529c"
+
 [[package]]
 name = "opaque-debug"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "624a8340c38c1b80fd549087862da4ba43e08858af025b236e509b6649fc13d5"
 
+[[package]]
+name = "open"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1711eb4b31ce4ad35b0f316d8dfba4fe5c7ad601c448446d84aae7a896627b20"
+dependencies = [
+ "which",
+ "winapi 0.3.9",
+]
+
 [[package]]
 name = "parking_lot"
 version = "0.11.1"
@@ -1470,6 +1910,87 @@ version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d4fd5641d01c8f18a23da7b6fe29298ff4b55afcccdf78973b24cf3175fee32e"
 
+[[package]]
+name = "pest"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10f4872ae94d7b90ae48754df22fd42ad52ce740b8f370b03da4835417403e53"
+dependencies = [
+ "ucd-trie",
+]
+
+[[package]]
+name = "pest_derive"
+version = "2.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "833d1ae558dc601e9a60366421196a8d94bc0ac980476d0b67e1d0988d72b2d0"
+dependencies = [
+ "pest",
+ "pest_generator",
+]
+
+[[package]]
+name = "pest_generator"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99b8db626e31e5b81787b9783425769681b347011cc59471e33ea46d2ea0cf55"
+dependencies = [
+ "pest",
+ "pest_meta",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pest_meta"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54be6e404f5317079812fc8f9f5279de376d8856929e21c184ecf6bbd692a11d"
+dependencies = [
+ "maplit",
+ "pest",
+ "sha-1 0.8.2",
+]
+
+[[package]]
+name = "phf"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3dfb61232e34fcb633f43d12c58f83c1df82962dcdfa565a4e866ffc17dafe12"
+dependencies = [
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_codegen"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cbffee61585b0411840d3ece935cce9cb6321f01c45477d30066498cd5e1a815"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_generator"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17367f0cc86f2d25802b2c26ee58a7b23faeccf78a396094c13dced0d0182526"
+dependencies = [
+ "phf_shared",
+ "rand 0.7.3",
+]
+
+[[package]]
+name = "phf_shared"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c00cf8b9eafe68dde5e9eaa2cef8ee84a9336a47d566ec55ca16589633b65af7"
+dependencies = [
+ "siphasher",
+]
+
 [[package]]
 name = "pin-project"
 version = "0.4.28"
@@ -1540,6 +2061,12 @@ version = "0.2.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857"
 
+[[package]]
+name = "precomputed-hash"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"
+
 [[package]]
 name = "predicates"
 version = "1.0.7"
@@ -1630,6 +2157,18 @@ version = "2.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1b7f4a129bb3754c25a4e04032a90173c68f85168f77118ac4cb4936e7f06f92"
 
+[[package]]
+name = "pulldown-cmark"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca36dea94d187597e104a5c8e4b07576a8a45aa5db48a65e12940d3eb7461f55"
+dependencies = [
+ "bitflags",
+ "getopts",
+ "memchr",
+ "unicase",
+]
+
 [[package]]
 name = "quick-error"
 version = "1.2.3"
@@ -1668,6 +2207,7 @@ dependencies = [
  "rand_chacha 0.2.2",
  "rand_core 0.5.1",
  "rand_hc 0.2.0",
+ "rand_pcg",
 ]
 
 [[package]]
@@ -1738,6 +2278,15 @@ dependencies = [
  "rand_core 0.6.2",
 ]
 
+[[package]]
+name = "rand_pcg"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16abd0c1b639e9eb4d7c50c0b8100b0d0f849be2349829c740fe8e6eb4816429"
+dependencies = [
+ "rand_core 0.5.1",
+]
+
 [[package]]
 name = "rand_xorshift"
 version = "0.3.0"
@@ -1870,7 +2419,7 @@ version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4b18820d944b33caa75a71378964ac46f58517c92b6ae5f762636247c09e78fb"
 dependencies = [
- "base64",
+ "base64 0.13.0",
  "blake2b_simd",
  "constant_time_eq",
  "crossbeam-utils",
@@ -1891,7 +2440,7 @@ version = "0.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "064fd21ff87c6e87ed4506e68beb42459caa4a0e2eb144932e6776768556980b"
 dependencies = [
- "base64",
+ "base64 0.13.0",
  "log",
  "ring",
  "sct",
@@ -1916,6 +2465,21 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "71d301d4193d031abdd79ff7e3dd721168a9572ef3fe51a1517aba235bd8f86e"
 
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "scoped-tls"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea6a9290e3c9cf0f18145ef7ffa62d68ee0bf5fcd651017e586dc7fd5da448c2"
+
 [[package]]
 name = "scopeguard"
 version = "1.1.0"
@@ -1978,6 +2542,18 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_urlencoded"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ec5d77e2d4c73717816afac02670d5c4f534ea95ed430442cad02e7a6e32c97"
+dependencies = [
+ "dtoa",
+ "itoa",
+ "serde",
+ "url",
+]
+
 [[package]]
 name = "serde_urlencoded"
 version = "0.7.0"
@@ -1990,17 +2566,29 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "sha-1"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7d94d0bede923b3cea61f3f1ff57ff8cdfd77b400fb8f9998949e0cf04163df"
+dependencies = [
+ "block-buffer 0.7.3",
+ "digest 0.8.1",
+ "fake-simd",
+ "opaque-debug 0.2.3",
+]
+
 [[package]]
 name = "sha-1"
 version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dfebf75d25bd900fd1e7d11501efab59bc846dbc76196839663e6637bba9f25f"
 dependencies = [
- "block-buffer",
+ "block-buffer 0.9.0",
  "cfg-if 1.0.0",
  "cpuid-bool",
- "digest",
- "opaque-debug",
+ "digest 0.9.0",
+ "opaque-debug 0.3.0",
 ]
 
 [[package]]
@@ -2009,6 +2597,12 @@ version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2579985fda508104f7587689507983eadd6a6e84dd35d6d115361f530916fa0d"
 
+[[package]]
+name = "shlex"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42a568c8f2cd051a4d283bd6eb0343ac214c1b0f1ac19f93e1175b2dee38c73d"
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.3.0"
@@ -2018,6 +2612,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "siphasher"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cbce6d4507c7e4a3962091436e56e95290cb71fa302d0d270e32130b75fbff27"
+
 [[package]]
 name = "slab"
 version = "0.4.2"
@@ -2117,12 +2717,55 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "213701ba3370744dcd1a12960caa4843b3d68b4d1c0a5d575e0d65b2ee9d16c0"
 
+[[package]]
+name = "string_cache"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ddb1139b5353f96e429e1a5e19fbaf663bddedaa06d1dbd49f82e352601209a"
+dependencies = [
+ "lazy_static",
+ "new_debug_unreachable",
+ "phf_shared",
+ "precomputed-hash",
+ "serde",
+]
+
+[[package]]
+name = "string_cache_codegen"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f24c8e5e19d22a726626f1a5e16fe15b132dcf21d10177fa5a45ce7962996b97"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+ "proc-macro2",
+ "quote",
+]
+
 [[package]]
 name = "strsim"
 version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ea5119cdb4c55b55d432abb513a0429384878c15dde60cc77b1c99de1a95a6a"
 
+[[package]]
+name = "strum"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57bd81eb48f4c437cadc685403cad539345bf703d78e63707418431cecd4522b"
+
+[[package]]
+name = "strum_macros"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87c85aa3f8ea653bfd3ddf25f7ee357ee4d204731f6aa9ad04002306f6e2774c"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "syn"
 version = "1.0.69"
@@ -2167,11 +2810,13 @@ dependencies = [
  "assert_cmd",
  "atty",
  "dirs-next",
- "env_logger",
+ "env_logger 0.8.3",
  "log",
+ "mdbook",
  "nom",
  "predicates",
  "prettytable-rs",
+ "serde_json",
  "taskchampion",
  "tempfile",
  "termcolor",
@@ -2189,7 +2834,7 @@ dependencies = [
  "actix-web",
  "anyhow",
  "clap",
- "env_logger",
+ "env_logger 0.8.3",
  "futures",
  "kv",
  "log",
@@ -2212,6 +2857,17 @@ dependencies = [
  "winapi 0.3.9",
 ]
 
+[[package]]
+name = "tendril"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9ef557cb397a4f0a5a3a628f06515f78563f2209e64d47055d9dc6052bf5e33"
+dependencies = [
+ "futf",
+ "mac",
+ "utf-8",
+]
+
 [[package]]
 name = "term"
 version = "0.5.2"
@@ -2373,6 +3029,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6703a273949a90131b290be1fe7b039d0fc884aa1935860dfcbe056f28cd8092"
 dependencies = [
  "bytes 0.5.6",
+ "fnv",
  "futures-core",
  "iovec",
  "lazy_static",
@@ -2383,6 +3040,7 @@ dependencies = [
  "pin-project-lite 0.1.12",
  "signal-hook-registry",
  "slab",
+ "tokio-macros",
  "winapi 0.3.9",
 ]
 
@@ -2402,6 +3060,30 @@ dependencies = [
  "winapi 0.3.9",
 ]
 
+[[package]]
+name = "tokio-macros"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e44da00bfc73a25f814cd8d7e57a68a5c31b74b3152a0a1d1f590c97ed06265a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio-tungstenite"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d9e878ad426ca286e4dcae09cbd4e1973a7f8987d97570e2469703dd7f5720c"
+dependencies = [
+ "futures-util",
+ "log",
+ "pin-project 0.4.28",
+ "tokio 0.2.25",
+ "tungstenite",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.3.1"
@@ -2436,6 +3118,12 @@ dependencies = [
  "linked-hash-map",
 ]
 
+[[package]]
+name = "tower-service"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "360dfd1d6d30e05fda32ace2c8c70e9c0a9da713275777f5a4dbb8a1893930c6"
+
 [[package]]
 name = "tracing"
 version = "0.1.25"
@@ -2512,12 +3200,52 @@ dependencies = [
  "trust-dns-proto",
 ]
 
+[[package]]
+name = "try-lock"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59547bce71d9c38b83d9c0e92b6066c4253371f15005def0c30d9657f50c7642"
+
+[[package]]
+name = "tungstenite"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0308d80d86700c5878b9ef6321f020f29b1bb9d5ff3cab25e75e23f3a492a23"
+dependencies = [
+ "base64 0.12.3",
+ "byteorder",
+ "bytes 0.5.6",
+ "http",
+ "httparse",
+ "input_buffer",
+ "log",
+ "rand 0.7.3",
+ "sha-1 0.9.4",
+ "url",
+ "utf-8",
+]
+
 [[package]]
 name = "typenum"
 version = "1.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "879f6906492a7cd215bfa4cf595b600146ccfac0c79bcbd1f3000162af5e8b06"
 
+[[package]]
+name = "ucd-trie"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56dee185309b50d1f11bfedef0fe6d036842e3fb77413abef29f8f8d1c5d4c1c"
+
+[[package]]
+name = "unicase"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50f37be617794602aabbeee0be4f259dc1778fabe05e2d67ee8f79326d5cb4f6"
+dependencies = [
+ "version_check",
+]
+
 [[package]]
 name = "unicode-bidi"
 version = "0.3.5"
@@ -2575,7 +3303,7 @@ version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6fbeb1aabb07378cf0e084971a74f24241273304653184f54cdce113c0d7df1b"
 dependencies = [
- "base64",
+ "base64 0.13.0",
  "chunked_transfer",
  "log",
  "once_cell",
@@ -2597,6 +3325,18 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "urlencoding"
+version = "1.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a1f0175e03a0973cf4afd476bef05c26e228520400eb1fd473ad417b1c00ffb"
+
+[[package]]
+name = "utf-8"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+
 [[package]]
 name = "uuid"
 version = "0.8.2"
@@ -2634,6 +3374,54 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "walkdir"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "808cf2735cd4b6866113f648b791c6adc5714537bc222d9347bb203386ffda56"
+dependencies = [
+ "same-file",
+ "winapi 0.3.9",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ce8a968cb1cd110d136ff8b819a556d6fb6d919363c61534f6860c7eb172ba0"
+dependencies = [
+ "log",
+ "try-lock",
+]
+
+[[package]]
+name = "warp"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41be6df54c97904af01aa23e613d4521eed7ab23537cede692d4058f6449407"
+dependencies = [
+ "bytes 0.5.6",
+ "futures",
+ "headers",
+ "http",
+ "hyper",
+ "log",
+ "mime",
+ "mime_guess",
+ "pin-project 0.4.28",
+ "scoped-tls",
+ "serde",
+ "serde_json",
+ "serde_urlencoded 0.6.1",
+ "tokio 0.2.25",
+ "tokio-tungstenite",
+ "tower-service",
+ "tracing",
+ "tracing-futures",
+ "urlencoding",
+]
+
 [[package]]
 name = "wasi"
 version = "0.9.0+wasi-snapshot-preview1"
@@ -2729,6 +3517,16 @@ dependencies = [
  "webpki",
 ]
 
+[[package]]
+name = "which"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b55551e42cbdf2ce2bedd2203d0cc08dba002c27510f86dab6d0ce304cba3dfe"
+dependencies = [
+ "either",
+ "libc",
+]
+
 [[package]]
 name = "widestring"
 version = "0.4.3"
@@ -2802,3 +3600,15 @@ name = "wyz"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85e60b0d1b5f99db2556934e21937020776a5d31520bf169e851ac44e6420214"
+
+[[package]]
+name = "xml5ever"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b1b52e6e8614d4a58b8e70cf51ec0cc21b256ad8206708bcff8139b5bbd6a59"
+dependencies = [
+ "log",
+ "mac",
+ "markup5ever",
+ "time 0.1.43",
+]
diff --git a/README.md b/README.md
index 6a0715ccb..1b4e1d664 100644
--- a/README.md
+++ b/README.md
@@ -33,3 +33,8 @@ There are three crates here:
  * [taskchampion-cli](./cli) - the command-line binary
  * [taskchampion-sync-server](./sync-server) - the server against which `task sync` operates
 
+## Documentation Generation
+
+The `mdbook` configuration contains a "preprocessor" implemented in the `taskchampion-cli` crate in order to reflect CLI usage information into the generated book.
+Tihs preprocessor is not built by default.
+To (re)build it, run `cargo build -p taskchampion-cli --features usage-docs --bin usage-docs`.
diff --git a/RELEASING.md b/RELEASING.md
index 160f2c230..e58e51da7 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -10,7 +10,7 @@
 1. Run `git tag vX.Y.Z`
 1. Run `git push upstream`
 1. Run `git push --tags upstream`
-1. Run `( cd docs; ./build.sh )`
+1. Run `( ./build-docs.sh )`
 1. Run `(cd taskchampion; cargo publish)` (note that the other crates do not get published)
 1. Navigate to the tag in the GitHub releases UI and create a release with general comments about the changes in the release
 1. Upload `./target/release/task` and `./target/release/task-sync-server` to the release
diff --git a/build-docs.sh b/build-docs.sh
new file mode 100755
index 000000000..b03c22ab9
--- /dev/null
+++ b/build-docs.sh
@@ -0,0 +1,31 @@
+#! /bin/bash
+
+REMOTE=origin
+
+set -e
+
+if ! [ -f "docs/src/SUMMARY.md" ]; then
+    echo "Run this from the root of the repo"
+    exit 1
+fi
+
+# build the latest version of the mdbook plugin
+cargo build -p taskchampion-cli --features usage-docs --bin usage-docs
+
+# create a worktree of this repo, with the `gh-pages` branch checked out
+if ! [ -d ./docs/tmp ]; then
+    git worktree add docs/tmp gh-pages
+fi
+
+# update the wortree
+(cd docs/tmp && git pull $REMOTE gh-pages)
+
+# remove all files in the worktree and regenerate the book there
+rm -rf docs/tmp/*
+mdbook build docs
+cp -rp docs/book/* docs/tmp
+
+# add everything in the worktree, commit, and push
+(cd docs/tmp && git add -A)
+(cd docs/tmp && git commit -am "update docs")
+(cd docs/tmp && git push $REMOTE gh-pages:gh-pages)
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
index 07b0e6aca..868565a88 100644
--- a/cli/Cargo.toml
+++ b/cli/Cargo.toml
@@ -20,6 +20,10 @@ atty = "^0.2.14"
 toml = "^0.5.8"
 toml_edit = "^0.2.0"
 
+# only needed for usage-docs
+mdbook = { version = "0.4", optional = true }
+serde_json = { version = "*", optional = true }
+
 [dependencies.taskchampion]
 path = "../taskchampion"
 
@@ -27,3 +31,14 @@ path = "../taskchampion"
 assert_cmd = "^1.0.3"
 predicates = "^1.0.7"
 tempfile = "3"
+
+[features]
+usage-docs = [ "mdbook", "serde_json" ]
+
+[[bin]]
+name = "ta"
+
+[[bin]]
+# this is an mdbook plugin and only needed when running `mdbook`
+name = "usage-docs"
+required-features = [ "usage-docs" ]
diff --git a/cli/src/argparse/modification.rs b/cli/src/argparse/modification.rs
index d449f1ef6..9628f2352 100644
--- a/cli/src/argparse/modification.rs
+++ b/cli/src/argparse/modification.rs
@@ -115,7 +115,9 @@ impl Modification {
             summary: "Set description",
             description: "
                 Set the task description.  Multiple arguments are combined into a single
-                space-separated description.",
+                space-separated description.  To avoid surprises from shell quoting, prefer
+                to use a single quoted argument, for example `ta 19 modify \"return library
+                books\"`",
         });
         u.modifications.push(usage::Modification {
             syntax: "+TAG",
diff --git a/cli/src/bin/usage-docs.rs b/cli/src/bin/usage-docs.rs
new file mode 100644
index 000000000..f78179c71
--- /dev/null
+++ b/cli/src/bin/usage-docs.rs
@@ -0,0 +1,50 @@
+use mdbook::book::{Book, BookItem};
+use mdbook::errors::Error;
+use mdbook::preprocess::{CmdPreprocessor, PreprocessorContext};
+use std::io;
+use std::process;
+use taskchampion_cli::Usage;
+
+/// This is a simple mdbook preprocessor designed to substitute information from the usage
+/// into the documentation.
+fn main() -> anyhow::Result<()> {
+    // cheap way to detect the "supports" arg
+    if std::env::args().len() > 1 {
+        // sure, whatever, we support it all
+        process::exit(0);
+    }
+
+    let (ctx, book) = CmdPreprocessor::parse_input(io::stdin())?;
+
+    if ctx.mdbook_version != mdbook::MDBOOK_VERSION {
+        eprintln!(
+            "Warning: This mdbook preprocessor was built against version {} of mdbook, \
+             but we're being called from version {}",
+            mdbook::MDBOOK_VERSION,
+            ctx.mdbook_version
+        );
+    }
+
+    let processed_book = process(&ctx, book)?;
+    serde_json::to_writer(io::stdout(), &processed_book)?;
+
+    Ok(())
+}
+
+fn process(_ctx: &PreprocessorContext, mut book: Book) -> Result<Book, Error> {
+    let usage = Usage::new();
+
+    book.for_each_mut(|sect| {
+        if let BookItem::Chapter(ref mut chapter) = sect {
+            let new_content = usage.substitute_docs(&chapter.content).unwrap();
+            if new_content != chapter.content {
+                eprintln!(
+                    "Substituting usage in {:?}",
+                    chapter.source_path.as_ref().unwrap()
+                );
+            }
+            chapter.content = new_content;
+        }
+    });
+    Ok(book)
+}
diff --git a/cli/src/lib.rs b/cli/src/lib.rs
index 6996e55f6..ba56704f0 100644
--- a/cli/src/lib.rs
+++ b/cli/src/lib.rs
@@ -47,6 +47,9 @@ mod usage;
 pub(crate) use errors::Error;
 use settings::Settings;
 
+// used by the `generate` command
+pub use usage::Usage;
+
 /// The main entry point for the command-line interface.  This builds an Invocation
 /// from the particulars of the operating-system interface, and then executes it.
 pub fn main() -> Result<(), Error> {
diff --git a/cli/src/settings/mod.rs b/cli/src/settings/mod.rs
index 896de38b8..c6a6ddd2f 100644
--- a/cli/src/settings/mod.rs
+++ b/cli/src/settings/mod.rs
@@ -7,5 +7,5 @@ mod report;
 mod settings;
 mod util;
 
-pub(crate) use report::{Column, Property, Report, Sort, SortBy};
+pub(crate) use report::{get_usage, Column, Property, Report, Sort, SortBy};
 pub(crate) use settings::Settings;
diff --git a/cli/src/settings/report.rs b/cli/src/settings/report.rs
index 959494e5d..f73dfe58d 100644
--- a/cli/src/settings/report.rs
+++ b/cli/src/settings/report.rs
@@ -2,6 +2,7 @@
 
 use crate::argparse::{Condition, Filter};
 use crate::settings::util::table_with_keys;
+use crate::usage::{self, Usage};
 use anyhow::{anyhow, bail, Result};
 use std::convert::{TryFrom, TryInto};
 
@@ -30,6 +31,7 @@ pub(crate) struct Column {
 /// Task property to display in a report
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum Property {
+    // NOTE: when adding a property here, add it to get_usage, below, as well.
     /// The task's ID, either working-set index or Uuid if not in the working set
     Id,
 
@@ -59,6 +61,7 @@ pub(crate) struct Sort {
 /// Task property to sort by
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum SortBy {
+    // NOTE: when adding a property here, add it to get_usage, below, as well.
     /// The task's ID, either working-set index or a UUID prefix; working
     /// set tasks sort before others.
     Id,
@@ -212,6 +215,34 @@ impl TryFrom<&toml::Value> for SortBy {
     }
 }
 
+pub(crate) fn get_usage(u: &mut Usage) {
+    u.report_properties.push(usage::ReportProperty {
+        name: "id",
+        as_sort_by: Some("Sort by the task's shorthand ID"),
+        as_column: Some("The task's shorthand ID"),
+    });
+    u.report_properties.push(usage::ReportProperty {
+        name: "uuid",
+        as_sort_by: Some("Sort by the task's full UUID"),
+        as_column: Some("The task's full UUID"),
+    });
+    u.report_properties.push(usage::ReportProperty {
+        name: "active",
+        as_sort_by: None,
+        as_column: Some("`*` if the task is active (started)"),
+    });
+    u.report_properties.push(usage::ReportProperty {
+        name: "description",
+        as_sort_by: Some("Sort by the task's description"),
+        as_column: Some("The task's description"),
+    });
+    u.report_properties.push(usage::ReportProperty {
+        name: "tags",
+        as_sort_by: None,
+        as_column: Some("The task's tags"),
+    });
+}
+
 #[cfg(test)]
 mod test {
     use super::*;
diff --git a/cli/src/usage.rs b/cli/src/usage.rs
index f1bacf674..59a2ba982 100644
--- a/cli/src/usage.rs
+++ b/cli/src/usage.rs
@@ -2,26 +2,31 @@
 //! a way that puts the source of that documentation near its implementation.
 
 use crate::argparse;
-use std::io::{Result, Write};
+use crate::settings;
+use anyhow::Result;
+use std::io::Write;
+
+#[cfg(feature = "usage-docs")]
+use std::fmt::Write as FmtWrite;
 
 /// A top-level structure containing usage/help information for the entire CLI.
 #[derive(Debug, Default)]
-pub(crate) struct Usage {
+pub struct Usage {
     pub(crate) subcommands: Vec<Subcommand>,
     pub(crate) filters: Vec<Filter>,
     pub(crate) modifications: Vec<Modification>,
+    pub(crate) report_properties: Vec<ReportProperty>,
 }
 
 impl Usage {
     /// Get a new, completely-filled-out usage object
-    pub(crate) fn new() -> Self {
+    pub fn new() -> Self {
         let mut rv = Self {
             ..Default::default()
         };
 
         argparse::get_usage(&mut rv);
-
-        // TODO: sort subcommands
+        settings::get_usage(&mut rv);
 
         rv
     }
@@ -77,6 +82,62 @@ impl Usage {
         }
         Ok(())
     }
+
+    #[cfg(feature = "usage-docs")]
+    /// Substitute strings matching
+    ///
+    /// ```text
+    /// <!-- INSERT GENERATED DOCUMENTATION - $type -->
+    /// ```
+    ///
+    /// With the appropriate documentation.
+    pub fn substitute_docs(&self, content: &str) -> Result<String> {
+        // this is not efficient, but it doesn't need to be
+        let mut lines = content.lines();
+        let mut w = String::new();
+
+        const DOC_HEADER_PREFIX: &str = "<!-- INSERT GENERATED DOCUMENTATION - ";
+        const DOC_HEADER_SUFFIX: &str = " -->";
+
+        for line in lines {
+            if line.starts_with(DOC_HEADER_PREFIX) && line.ends_with(DOC_HEADER_SUFFIX) {
+                let doc_type = &line[DOC_HEADER_PREFIX.len()..line.len() - DOC_HEADER_SUFFIX.len()];
+
+                match doc_type {
+                    "subcommands" => {
+                        for subcommand in self.subcommands.iter() {
+                            subcommand.write_markdown(&mut w)?;
+                        }
+                    }
+                    "filters" => {
+                        for filter in self.filters.iter() {
+                            filter.write_markdown(&mut w)?;
+                        }
+                    }
+                    "modifications" => {
+                        for modification in self.modifications.iter() {
+                            modification.write_markdown(&mut w)?;
+                        }
+                    }
+                    "report-columns" => {
+                        for prop in self.report_properties.iter() {
+                            prop.write_column_markdown(&mut w)?;
+                        }
+                    }
+                    "report-sort-by" => {
+                        for prop in self.report_properties.iter() {
+                            prop.write_sort_by_markdown(&mut w)?;
+                        }
+                    }
+                    _ => anyhow::bail!("Unkonwn doc type {}", doc_type),
+                }
+            } else {
+                writeln!(w, "{}", line)?;
+            }
+        }
+
+        Ok(w)
+    }
 }
 
 /// wrap an indented string
@@ -122,6 +183,15 @@ impl Subcommand {
         }
         Ok(())
     }
+
+    #[cfg(feature = "usage-docs")]
+    fn write_markdown<W: FmtWrite>(&self, mut w: W) -> Result<()> {
+        writeln!(w, "### `ta {}` - {}", self.name, self.summary)?;
+        writeln!(w, "```shell\nta {}\n```", self.syntax)?;
+        writeln!(w, "{}", indented(self.description, ""))?;
+        writeln!(w)?;
+        Ok(())
+    }
 }
 
 /// Usage documentation for a filter argument
@@ -152,6 +222,15 @@ impl Filter {
         }
         Ok(())
     }
+
+    #[cfg(feature = "usage-docs")]
+    fn write_markdown<W: FmtWrite>(&self, mut w: W) -> Result<()> {
+        writeln!(w, "* `{}` - {}", self.syntax, self.summary)?;
+        writeln!(w)?;
+        writeln!(w, "{}", indented(self.description, "  "))?;
+        writeln!(w)?;
+        Ok(())
+    }
 }
 
 /// Usage documentation for a modification argument
@@ -182,4 +261,51 @@ impl Modification {
         }
         Ok(())
     }
+
+    #[cfg(feature = "usage-docs")]
+    fn write_markdown<W: FmtWrite>(&self, mut w: W) -> Result<()> {
+        writeln!(w, "* `{}` - {}", self.syntax, self.summary)?;
+        writeln!(w)?;
+        writeln!(w, "{}", indented(self.description, "  "))?;
+        writeln!(w)?;
+        Ok(())
+    }
+}
+
+/// Usage documentation for a report property (which may be used for sorting, as a column, or
+/// both).
+#[derive(Debug, Default)]
+pub(crate) struct ReportProperty {
+    /// Name of the property
+    pub(crate) name: &'static str,
+
+    /// Usage description for sorting, if any
+    pub(crate) as_sort_by: Option<&'static str>,
+
+    /// Usage description as a column, if any
+    pub(crate) as_column: Option<&'static str>,
+}
+
+impl ReportProperty {
+    #[cfg(feature = "usage-docs")]
+    fn write_sort_by_markdown<W: FmtWrite>(&self, mut w: W) -> Result<()> {
+        if let Some(as_sort_by) = self.as_sort_by {
+            writeln!(w, "* `{}`", self.name)?;
+            writeln!(w)?;
+            writeln!(w, "{}", indented(as_sort_by, "  "))?;
+            writeln!(w)?;
+        }
+        Ok(())
+    }
+
+    #[cfg(feature = "usage-docs")]
+    fn write_column_markdown<W: FmtWrite>(&self, mut w: W) -> Result<()> {
+        if let Some(as_column) = self.as_column {
+            writeln!(w, "* `{}`", self.name)?;
+            writeln!(w)?;
+            writeln!(w, "{}", indented(as_column, "  "))?;
+            writeln!(w)?;
+        }
+        Ok(())
+    }
 }
diff --git a/docs/README.md b/docs/README.md
index 7aaa35c16..586cf2663 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,3 +1,10 @@
 This is an [mdbook](https://rust-lang.github.io/mdBook/index.html) book.
 Minor modifications can be made without installing the mdbook tool, as the content is simple Markdown.
 Changes are verified on pull requests.
+
+To build the docs locally, you will need to build `usage-docs`:
+
+```
+cargo build -p taskchampion-cli --feature usage-docs --bin usage-docs
+mdbook build docs/
+```
diff --git a/docs/book.toml b/docs/book.toml
index 7e2fa9820..3ab678ad0 100644
--- a/docs/book.toml
+++ b/docs/book.toml
@@ -7,3 +7,6 @@ title = "TaskChampion"
 
 [output.html]
 default-theme = "ayu"
+
+[preprocessor.usage-docs]
+command = "target/debug/usage-docs"
diff --git a/docs/build.sh b/docs/build.sh
deleted file mode 100755
index 06dc662c7..000000000
--- a/docs/build.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#! /bin/bash
-
-REMOTE=origin
-
-set -e
-
-if ! [ -f "./src/SUMMARY.md" ]; then
-    echo "Run this from the docs/ dir"
-    exit 1
-fi
-
-if ! [ -d ./tmp ]; then
-    git worktree add tmp gh-pages
-fi
-
-(cd tmp && git pull $REMOTE gh-pages)
-
-rm -rf tmp/*
-mdbook build
-cp -rp book/* tmp
-(cd tmp && git add -A)
-(cd tmp && git commit -am "update docs")
-(cd tmp && git push $REMOTE gh-pages:gh-pages)
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index f69280b27..822dc4f7f 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -3,9 +3,11 @@
 - [Welcome to TaskChampion](./welcome.md)
   * [Installation](./installation.md)
   * [Using the Task Command](./using-task-command.md)
-    * [Configuration](./config-file.md)
     * [Reports](./reports.md)
     * [Tags](./tags.md)
+    * [Filters](./filters.md)
+    * [Modifications](./modifications.md)
+    * [Configuration](./config-file.md)
     * [Environment](./environment.md)
     * [Synchronization](./task-sync.md)
   * [Running the Sync Server](./running-sync-server.md)
diff --git a/docs/src/filters.md b/docs/src/filters.md
new file mode 100644
index 000000000..e2be669d7
--- /dev/null
+++ b/docs/src/filters.md
@@ -0,0 +1,9 @@
+# Filters
+
+Filters are used to select specific tasks for reports or to specify tasks to be modified.
+When more than one filter is given, only tasks which match all of the filters are selected.
+When no filter is given, the command implicitly selects all tasks.
+
+Filters can have the following forms:
+
+<!-- INSERT GENERATED DOCUMENTATION - filters -->
diff --git a/docs/src/modifications.md b/docs/src/modifications.md
new file mode 100644
index 000000000..017969951
--- /dev/null
+++ b/docs/src/modifications.md
@@ -0,0 +1,5 @@
+# Modifications
+
+Modifications can have the following forms:
+
+<!-- INSERT GENERATED DOCUMENTATION - modifications-->
diff --git a/docs/src/reports.md b/docs/src/reports.md
index 05026da6f..4f106e35b 100644
--- a/docs/src/reports.md
+++ b/docs/src/reports.md
@@ -49,9 +49,8 @@ columns = [
 ]
 ```
 
-The filter is a list of filter arguments, just like those that can be used on the command line.
-See the `ta help` output for more details on this syntax.
-It will be merged with any filters provided on the command line, when the report is invoked.
+The `filter` property is a list of [filters](./filters.md).
+It will be merged with any filters provided on the command line when the report is invoked.
 
 The sort order is defined by an array of tables containing a `sort_by` property and an optional `ascending` property.
 Tasks are compared by the first criterion, and if that is equal by the second, and so on.
@@ -70,11 +69,11 @@ sort = [
 
 The available values of `sort_by` are
 
-(TODO: generate automatically)
+<!-- INSERT GENERATED DOCUMENTATION - report-sort-by -->
 
 Finally, the `columns` configuration specifies the list of columns to display.
 Each element has a `label` and a `property`, as shown in the example above.
 
 The avaliable properties are:
 
-(TODO: generate automatically)
+<!-- INSERT GENERATED DOCUMENTATION - report-columns -->
diff --git a/docs/src/using-task-command.md b/docs/src/using-task-command.md
index d2e7f0ca0..355dcc898 100644
--- a/docs/src/using-task-command.md
+++ b/docs/src/using-task-command.md
@@ -4,6 +4,13 @@ The main interface to your tasks is the `ta` command, which supports various sub
 Customizable [reports](./reports.md) are also available as subcommands, such as `next`.
 The command reads a [configuration file](./config-file.md) for its settings, including where to find the task database.
 And the `sync` subcommand [synchronizes tasks with a sync server](./task-sync.md).
-You can find a list of all subcommands, as well as the built-in reports, with `ta help`.
 
 > NOTE: the `task` interface does not precisely match that of TaskWarrior.
+
+## Subcommands
+
+The sections below describe each subcommand of the `ta` command.
+The syntax of `[filter]` is defined in [filters](./filters.md), and that of `[modification]` in [modifications](./modifications.md).
+You can also find a summary of all subcommands, as well as filters, built-in reports, and so on, with `ta help`.
+
+<!-- INSERT GENERATED DOCUMENTATION - subcommands -->