Migrate from mkdocs-material to zensical

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical mkdocstrings-python
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -11,3 +11,6 @@ wheels/
 
 # pytest
 .coverage
+
+# Zensical site
+/site/

README.md

@@ -6,11 +6,11 @@
 [![CI tests](https://github.com/pharmaverse/py-pkglite/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/pharmaverse/py-pkglite/actions/workflows/ci-tests.yml)
 [![Mypy check](https://github.com/pharmaverse/py-pkglite/actions/workflows/mypy.yml/badge.svg)](https://github.com/pharmaverse/py-pkglite/actions/workflows/mypy.yml)
 [![Ruff check](https://github.com/pharmaverse/py-pkglite/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/pharmaverse/py-pkglite/actions/workflows/ruff-check.yml)
-[![mkdocs](https://github.com/pharmaverse/py-pkglite/actions/workflows/mkdocs.yml/badge.svg)](https://pharmaverse.github.io/py-pkglite/)
+[![Documentation](https://github.com/pharmaverse/py-pkglite/actions/workflows/docs.yml/badge.svg)](https://pharmaverse.github.io/py-pkglite/)
 ![License](https://img.shields.io/pypi/l/pkglite)
 
-A simple framework for packing source projects of any language into portable
-text files and restoring them into the original directory structure.
+A simple framework for packing source projects of any programming language into
+portable text files and restoring them into the original directory structure.
 
 Besides the Python API, a command line interface is also provided.
 

docs/index.md

@@ -6,11 +6,11 @@
 [![CI tests](https://github.com/pharmaverse/py-pkglite/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/pharmaverse/py-pkglite/actions/workflows/ci-tests.yml)
 [![Mypy check](https://github.com/pharmaverse/py-pkglite/actions/workflows/mypy.yml/badge.svg)](https://github.com/pharmaverse/py-pkglite/actions/workflows/mypy.yml)
 [![Ruff check](https://github.com/pharmaverse/py-pkglite/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/pharmaverse/py-pkglite/actions/workflows/ruff-check.yml)
-[![mkdocs](https://github.com/pharmaverse/py-pkglite/actions/workflows/mkdocs.yml/badge.svg)](https://pharmaverse.github.io/py-pkglite/)
+[![Documentation](https://github.com/pharmaverse/py-pkglite/actions/workflows/docs.yml/badge.svg)](https://pharmaverse.github.io/py-pkglite/)
 ![License](https://img.shields.io/pypi/l/pkglite)
 
-A simple framework for packing source projects of any language into portable
-text files and restoring them into the original directory structure.
+A simple framework for packing source projects of any programming language into
+portable text files and restoring them into the original directory structure.
 
 Besides the Python API, a command line interface is also provided.
 

docs/reference/classify.md

@@ -5,5 +5,3 @@
       members:
         - is_text_file
         - classify_file
-      show_root_heading: true
-      show_source: false

docs/reference/pack.md

@@ -4,5 +4,3 @@
     options:
       members:
         - pack
-      show_root_heading: true
-      show_source: false

docs/reference/unpack.md

@@ -4,5 +4,3 @@
     options:
       members:
         - unpack
-      show_root_heading: true
-      show_source: false

docs/reference/use.md

@@ -4,5 +4,3 @@
     options:
       members:
         - use_pkglite
-      show_root_heading: true
-      show_source: false

docs/scripts/sync.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-echo "Sync root-level docs into mkdocs..."
+echo "Sync root-level docs into Zensical site..."
 
 # Sync README.md with modified image path for docs/index.md
 awk '{gsub("https://github.com/pharmaverse/py-pkglite/raw/main/docs/assets/logo.png", "assets/logo.png"); print}' README.md >docs/index.md

docs/stylesheets/extra.css

@@ -1,19 +1,20 @@
-/* Color scheme */
+/* Typography */
 
-:root {
-    --md-primary-fg-color: hsla(175, 100%, 26%, 1);
-    --md-primary-fg-color--light: hsla(175, 100%, 36%, 1);
-    --md-primary-fg-color--dark: hsla(175, 100%, 16%, 1);
-    --md-primary-bg-color: hsla(0, 0%, 100%, 1);
-    --md-primary-bg-color--light: hsla(0, 0%, 100%, 0.7);
-    --md-accent-fg-color: hsla(175, 100%, 40%, 1);
-    --md-accent-fg-color--transparent: hsla(220, 76%, 61%, 0.1);
-    --md-accent-bg-color: hsla(0, 0%, 100%, 1);
-    --md-accent-bg-color--light: hsla(0, 0%, 100%, 0.7);
-    --md-code-font: "JetBrains Mono";
+@font-face {
+    font-display: swap;
+    font-family: "Source Sans 3";
+    src: url("../assets/SourceSans3-Variable.woff2") format("woff2");
+    font-weight: 200 900;
+    font-style: normal;
 }
 
-/* Typography */
+@font-face {
+    font-display: swap;
+    font-family: "Source Sans 3";
+    src: url("../assets/SourceSans3-Variable-Italic.woff2") format("woff2");
+    font-weight: 200 900;
+    font-style: italic;
+}
 
 @font-face {
     font-display: swap;
@@ -31,45 +32,94 @@
     font-style: italic;
 }
 
+:root {
+    --md-text-font: "Source Sans 3", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+    --md-code-font: "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+}
+
 body {
     -webkit-font-smoothing: auto;
 }
 
+/* Header */
+
+.md-header__topic:first-child {
+    font-weight: 400;
+}
+
+.md-header__title {
+    letter-spacing: normal;
+}
+
+/* Navigation */
+
 .md-nav {
-    font-size: 0.85rem;
-    line-height: 1.2;
+    font-size: 1rem;
+}
+
+.md-nav__item--section>.md-nav__link {
+    font-weight: 600;
+}
+
+.md-nav--secondary .md-nav__title {
+    font-weight: 600;
+}
+
+.md-nav__item--nested .md-nav__icon::after {
+    height: 150%;
+}
+
+/* Content */
+
+.md-typeset {
+    font-size: 1rem;
+    letter-spacing: normal;
+}
+
+.md-path {
+    font-size: 1rem;
 }
 
 .md-typeset h1,
 .md-typeset h2,
 .md-typeset h3 {
-    color: var(--md-default-fg-color--dark);
-    font-weight: 600;
+    font-weight: 500;
 }
 
-h2 h3,
-code {
+h2 code,
+h3 code,
+h4 code {
     font-weight: 400;
 }
 
-.md-typeset {
-    font-size: 0.85rem;
+.md-typeset h1 {
+    font-size: 2.4rem;
+}
+
+.md-typeset .admonition,
+.md-typeset details {
+    font-size: 0.9rem;
 }
 
 .md-typeset code {
-    font-size: 0.85em;
+    font-size: 0.8em;
 }
 
 .md-typeset table:not([class]) {
     font-size: 0.8rem;
 }
 
-.md-typeset .admonition,
-.md-typeset details {
-    font-size: 0.85rem;
-}
+/* Banner */
 
 .md-banner {
-    color: var(--md-typeset-color);
+    color: #000000DE;
     background-color: oklch(96.2% 0.059 95.617);
+}
+
+.md-banner .md-banner__inner {
+    font-size: 0.9rem;
+}
+
+.md-banner .md-banner__inner a {
+    text-decoration: none;
 }