commit-check · shenxianpeng · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -107,12 +107,15 @@ jobs:
           uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
           with:
             name: "commit-check_docs"
-            path: ${{ github.workspace }}/_build/html
+            path: ${{ github.workspace }}/site
 
         - name: Upload docs to github pages
           # only publish doc changes from main branch
           if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
           uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
-            publish_dir: ./_build/html
+            publish_dir: ./site
+            # Pinned explicitly so the custom domain cannot be lost when the
+            # publish branch is replaced.
+            cname: docs.commit-check.com
diff --git a/.gitignore b/.gitignore
@@ -19,3 +19,7 @@ _build/
 docs/_build
 docs/cli_args.rst
 docs/__pycache__
+
+# MkDocs
+site/
+docs/cli.md
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -12,6 +12,11 @@ repos:
     rev: v6.0.0
     hooks:
     -   id: check-yaml
+        # mkdocs.yml carries the `!!python/name:` tags that Material's emoji
+        # extension requires, which yaml.safe_load cannot construct. MkDocs
+        # validates the file itself on every build (`mkdocs build --strict`),
+        # so it is checked more thoroughly than this hook would manage.
+        exclude: ^mkdocs\.yml$
     -   id: check-toml
     -   id: end-of-file-fixer
     -   id: trailing-whitespace

diff --git a/commit_check/rules_catalog.py b/commit_check/rules_catalog.py
@@ -21,7 +21,7 @@
 from dataclasses import dataclass
 
 #: Base URL of the rules reference documentation.
-RULES_DOCS_URL = "https://docs.commit-check.com/rules.html"
+RULES_DOCS_URL = "https://docs.commit-check.com/rules/"
 
 
 @dataclass(frozen=True)

diff --git a/docs/README.rst b/docs/README.rst
diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css
diff --git a/docs/_static/logo.jpg b/docs/_static/logo.jpg
diff --git a/docs/assets/extra.css b/docs/assets/extra.css
@@ -0,0 +1,89 @@
+/* Brand palette -----------------------------------------------------------
+   Material's "custom" primary/accent read these variables. */
+:root {
+  --cc-brand: #2c9ccd;
+  --cc-brand-dark: #1e85a8;
+  --cc-brand-light: #5bb3d9;
+
+  --md-primary-fg-color: var(--cc-brand);
+  --md-primary-fg-color--light: var(--cc-brand-light);
+  --md-primary-fg-color--dark: var(--cc-brand-dark);
+  --md-accent-fg-color: var(--cc-brand-dark);
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: var(--cc-brand);
+  --md-accent-fg-color: var(--cc-brand-light);
+  --md-typeset-a-color: var(--cc-brand-light);
+}
+
+[data-md-color-scheme="default"] {
+  --md-typeset-a-color: var(--cc-brand-dark);
+}
+
+/* Landing page -------------------------------------------------------------
+   The hero is the first thing a visitor sees, so it carries the value
+   proposition rather than a badge wall. */
+.cc-hero {
+  text-align: center;
+  padding: 3.5rem 1rem 2.5rem;
+}
+
+.cc-hero h1 {
+  font-size: 2.9rem;
+  line-height: 1.15;
+  font-weight: 800;
+  letter-spacing: -0.02em;
+  margin: 0 0 0.6rem;
+}
+
+.cc-hero p {
+  font-size: 1.05rem;
+  max-width: 40rem;
+  margin: 0 auto 1.8rem;
+  color: var(--md-default-fg-color--light);
+}
+
+.cc-hero .md-button {
+  margin: 0.3rem;
+}
+
+/* Hide the redundant H1 that MkDocs renders above a custom hero. */
+.cc-hero + hr {
+  display: none;
+}
+
+/* Feature grid: uses Material's card grid, tightened up a little. */
+.md-typeset .grid.cards > ul > li {
+  border-radius: 0.4rem;
+  transition: border-color 125ms, box-shadow 125ms;
+}
+
+.md-typeset .grid.cards > ul > li:hover {
+  border-color: var(--cc-brand);
+  box-shadow: 0 0 0 1px var(--cc-brand);
+}
+
+.md-typeset .grid.cards > ul > li > hr {
+  margin: 0.6rem 0;
+}
+
+/* Tables -------------------------------------------------------------------
+   Cells align to the top so short values line up with a wrapped message. */
+.md-typeset table:not([class]) td,
+.md-typeset table:not([class]) th {
+  vertical-align: top;
+}
+
+/* In the rule index tables only, keep codes, names and CLI flags on one line
+   so the tables stay scannable. Other tables hold long regexes and lists that
+   must stay wrappable. */
+.md-typeset table.rules-index td code {
+  white-space: nowrap;
+}
+
+/* Sidebar section headings ("Getting started", "Reference", ...) */
+.md-nav__item--section > .md-nav__link {
+  font-weight: 700;
+  color: var(--md-default-fg-color);
+}
diff --git a/docs/assets/favicon.svg b/docs/assets/favicon.svg
diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg