Migrate from Material for MkDocs to Zensical

.github/workflows/ci_cd.yml

@@ -27,7 +27,7 @@ jobs:
         uses: apppackio/setup-apppack-cli@v1
 
       - name: CLI docs
-        run: apppack docgen --directory src/command-line-reference
+        run: make cli-docs
       - name: Build
         run: APPPACK_VERSION=$(apppack version) make build
       - uses: actions/upload-artifact@v5

Makefile

@@ -1,6 +1,6 @@
 .PHONY: build
 build:
-	SITE_URL=https://docs.apppack.io/ uv run mkdocs build
+	SITE_URL=https://docs.apppack.io/ uv run zensical build
 
 .PHONY: deploy
 deploy:
@@ -15,7 +15,8 @@ clean:
 .PHONY: cli-docs
 cli-docs:
 	apppack docgen --directory src/command-line-reference
+	python3 scripts/generate_cli_nav.py
 
 .PHONY: run
 run:
-	uv run mkdocs serve
+	uv run zensical serve

mkdocs.yml

@@ -13,29 +13,147 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:zensical.extensions.emoji.twemoji
+      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
   - tables
 plugins:
   - search
   - macros
-  - literate-nav:
-      nav_file: _navigation.md
 repo_url: https://github.com/apppackio/apppack-docs/
 edit_uri: edit/main/src/
 extra_css:
   - stylesheets/extra.css
-exclude_docs: |
-  _navigation.md
 theme:
-  name: material
+  name: zensical
   custom_dir: theme_overrides
   palette:
     primary: slate blue
   logo: assets/mark-white.svg
   favicon: assets/favicon.ico
   icon:
     repo: fontawesome/brands/github
-validation:
-  links:
-    absolute_links: relative_to_docs
+nav:
+  - index.md
+  - Tutorials:
+      - tutorials/initial-setup.md
+      - tutorials/deploy-first-app.md
+  - How-to guides:
+      - Add ons:
+          - how-to/add-ons/sending-email.md
+          - how-to/add-ons/using-databases.md
+          - how-to/add-ons/using-redis.md
+          - how-to/add-ons/using-s3.md
+          - how-to/add-ons/using-sqs.md
+          - how-to/add-ons/working-with-files.md
+      - Apps:
+          - how-to/apps/apppack_toml.md
+          - how-to/apps/apps.md
+          - how-to/apps/config-variables.md
+          - how-to/apps/deploy-django-app.md
+          - how-to/apps/destroy-app.md
+          - how-to/apps/dockerfile-builds.md
+          - how-to/apps/releases.md
+          - how-to/apps/review-apps.md
+      - Domains:
+          - how-to/domains/bring-your-own-cluster-domain.md
+          - how-to/domains/custom-domains.md
+      - Set up:
+          - how-to/set-up/choose-aws-region.md
+          - how-to/set-up/github-actions.md
+          - how-to/set-up/github-deployment.md
+          - how-to/set-up/install.md
+  - Under the hood:
+      - under-the-hood/index.md
+      - under-the-hood/domains.md
+      - under-the-hood/how-apppack-works.md
+      - under-the-hood/pricing.md
+  # The command line reference section is generated by `make cli-docs`.
+  # Do not edit it by hand.
+  - Command line reference:
+      # BEGIN cli-nav (generated)
+      - command-line-reference/apppack.md
+      - command-line-reference/apppack_access.md
+      - command-line-reference/apppack_access_add.md
+      - command-line-reference/apppack_access_remove.md
+      - command-line-reference/apppack_admins.md
+      - command-line-reference/apppack_admins_add.md
+      - command-line-reference/apppack_admins_remove.md
+      - command-line-reference/apppack_auth.md
+      - command-line-reference/apppack_auth_accounts.md
+      - command-line-reference/apppack_auth_apps.md
+      - command-line-reference/apppack_auth_login.md
+      - command-line-reference/apppack_auth_logout.md
+      - command-line-reference/apppack_auth_whoami.md
+      - command-line-reference/apppack_aws-exec.md
+      - command-line-reference/apppack_build.md
+      - command-line-reference/apppack_build_list.md
+      - command-line-reference/apppack_build_start.md
+      - command-line-reference/apppack_build_status.md
+      - command-line-reference/apppack_build_wait.md
+      - command-line-reference/apppack_build_watch.md
+      - command-line-reference/apppack_completion.md
+      - command-line-reference/apppack_completion_bash.md
+      - command-line-reference/apppack_completion_fish.md
+      - command-line-reference/apppack_completion_powershell.md
+      - command-line-reference/apppack_completion_zsh.md
+      - command-line-reference/apppack_config.md
+      - command-line-reference/apppack_config_export.md
+      - command-line-reference/apppack_config_get.md
+      - command-line-reference/apppack_config_import.md
+      - command-line-reference/apppack_config_list.md
+      - command-line-reference/apppack_config_set.md
+      - command-line-reference/apppack_config_unset.md
+      - command-line-reference/apppack_create.md
+      - command-line-reference/apppack_create_app.md
+      - command-line-reference/apppack_create_cluster.md
+      - command-line-reference/apppack_create_custom-domain.md
+      - command-line-reference/apppack_create_database.md
+      - command-line-reference/apppack_create_pipeline.md
+      - command-line-reference/apppack_create_redis.md
+      - command-line-reference/apppack_create_region.md
+      - command-line-reference/apppack_dash.md
+      - command-line-reference/apppack_db.md
+      - command-line-reference/apppack_db_dump.md
+      - command-line-reference/apppack_db_load.md
+      - command-line-reference/apppack_db_shell.md
+      - command-line-reference/apppack_destroy.md
+      - command-line-reference/apppack_destroy_account.md
+      - command-line-reference/apppack_destroy_app.md
+      - command-line-reference/apppack_destroy_cluster.md
+      - command-line-reference/apppack_destroy_custom-domain.md
+      - command-line-reference/apppack_destroy_database.md
+      - command-line-reference/apppack_destroy_pipeline.md
+      - command-line-reference/apppack_destroy_redis.md
+      - command-line-reference/apppack_destroy_region.md
+      - command-line-reference/apppack_events.md
+      - command-line-reference/apppack_logs.md
+      - command-line-reference/apppack_logs_open.md
+      - command-line-reference/apppack_modify.md
+      - command-line-reference/apppack_modify_app.md
+      - command-line-reference/apppack_open.md
+      - command-line-reference/apppack_ps.md
+      - command-line-reference/apppack_ps_exec.md
+      - command-line-reference/apppack_ps_resize.md
+      - command-line-reference/apppack_ps_restart.md
+      - command-line-reference/apppack_ps_scale.md
+      - command-line-reference/apppack_reviewapps.md
+      - command-line-reference/apppack_reviewapps_create.md
+      - command-line-reference/apppack_reviewapps_destroy.md
+      - command-line-reference/apppack_scheduled-tasks.md
+      - command-line-reference/apppack_scheduled-tasks_create.md
+      - command-line-reference/apppack_scheduled-tasks_delete.md
+      - command-line-reference/apppack_shell.md
+      - command-line-reference/apppack_stacks.md
+      - command-line-reference/apppack_upgrade.md
+      - command-line-reference/apppack_upgrade_account.md
+      - command-line-reference/apppack_upgrade_app.md
+      - command-line-reference/apppack_upgrade_cluster.md
+      - command-line-reference/apppack_upgrade_database.md
+      - command-line-reference/apppack_upgrade_pipeline.md
+      - command-line-reference/apppack_upgrade_redis.md
+      - command-line-reference/apppack_upgrade_region.md
+      - command-line-reference/apppack_version.md
+      - command-line-reference/apppack_version_check.md
+      - command-line-reference/apppack_version_update.md
+      # END cli-nav (generated)
+  - why-apppack.md

pyproject.toml

@@ -5,7 +5,7 @@ description = "Documentation for AppPack.io"
 authors = [
     {name = "Peter Baumgartner", email = "pete@lincolnloop.com"},
 ]
-dependencies = ["mkdocs", "mkdocs-literate-nav", "mkdocs-material", "mkdocs-macros-plugin", "setuptools", "pymdown-extensions"]
+dependencies = ["zensical"]
 requires-python = ">=3.14"
 dynamic = ["classifiers"]
 license = {text = "MIT"}

scripts/generate_cli_nav.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Regenerate the command line reference nav section in mkdocs.yml.
+
+The pages in src/command-line-reference are generated by `apppack docgen`
+and not committed, so their nav entries are regenerated alongside them
+(see the cli-docs target in the Makefile). Page titles are taken from
+each page's H1 at build time, so only the paths are listed here.
+"""
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+CONFIG = ROOT / "mkdocs.yml"
+CLI_DOCS = ROOT / "src" / "command-line-reference"
+BEGIN = "# BEGIN cli-nav (generated)"
+END = "# END cli-nav (generated)"
+
+
+def main() -> int:
+    pages = sorted(p.name for p in CLI_DOCS.glob("*.md"))
+    if not pages:
+        print(f"No pages found in {CLI_DOCS}. Run `apppack docgen` first.", file=sys.stderr)
+        return 1
+
+    lines = CONFIG.read_text().splitlines()
+    try:
+        begin = next(i for i, l in enumerate(lines) if l.strip() == BEGIN)
+        end = next(i for i, l in enumerate(lines) if l.strip() == END)
+    except StopIteration:
+        print(f"cli-nav markers not found in {CONFIG}", file=sys.stderr)
+        return 1
+
+    indent = " " * (len(lines[begin]) - len(lines[begin].lstrip()))
+    entries = [f"{indent}- command-line-reference/{name}" for name in pages]
+    lines[begin + 1 : end] = entries
+    CONFIG.write_text("\n".join(lines) + "\n")
+    print(f"Wrote {len(pages)} command line reference nav entries to {CONFIG}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/how-to/add-ons/using-databases.md

@@ -4,7 +4,7 @@ Postgres and MySQL databases are available as an add-on and are backed by [AWS R
 
 ## Creating a database cluster
 
-First you must setup the database in your AppPack Cluster. This can be done with [`apppack create database`](/command-line-reference/apppack_create_database.md).
+First you must setup the database in your AppPack Cluster. This can be done with [`apppack create database`](../../command-line-reference/apppack_create_database.md).
 
 !!! example
     ```

src/how-to/add-ons/using-redis.md

@@ -4,7 +4,7 @@ Redis is available as an add-on and is backed by [AWS Elasticache](https://aws.a
 
 ## Creating a Redis cluster
 
-First you must setup Redis in your AppPack Cluster. This can be done with [`apppack create redis`](/command-line-reference/apppack_create_redis.md).
+First you must setup Redis in your AppPack Cluster. This can be done with [`apppack create redis`](../../command-line-reference/apppack_create_redis.md).
 
 !!! example
     ```

src/how-to/apps/apppack_toml.md

@@ -79,7 +79,7 @@ The command used to release your app. Only used if `build.system` is set to `doc
 
 ## `[review_app]`
 
-This section is only applicable for review apps. See [Review Apps](/how-to/apps/review-apps.md#handling-initial-data) for more information.
+This section is only applicable for review apps. See [Review Apps](review-apps.md#handling-initial-data) for more information.
 
 ### `initialize_command`
 

src/how-to/apps/config-variables.md

@@ -4,7 +4,7 @@ Config variables are used to store secrets and pass environment-specific informa
 
 ## Setting a config variable
 
-[`apppack config set`](/command-line-reference/apppack_config_set.md) is used to set a config variable. For example, if you wanted to store a config variable named `SECRET_KEY` with the value `this-is-a-secret` for your app `my-app`, you would run:
+[`apppack config set`](../../command-line-reference/apppack_config_set.md) is used to set a config variable. For example, if you wanted to store a config variable named `SECRET_KEY` with the value `this-is-a-secret` for your app `my-app`, you would run:
 
 !!! example
     ```

src/how-to/apps/destroy-app.md

@@ -5,7 +5,7 @@ If you are no longer using an application, it should be destroyed to avoid payin
 !!! danger
     Destroying an application destroys _everything_ related to the application. If you've configured add-ons which are storing data (database, Redis, S3, etc.), all data in those stores will be erased. Be sure to back up any data to a separate location before destroying the application.
 
-When you're ready to destroy your application, you can use the [`apppack destroy app`](/command-line-reference/apppack_destroy_app.md) command. Only administrators can perform this action.
+When you're ready to destroy your application, you can use the [`apppack destroy app`](../../command-line-reference/apppack_destroy_app.md) command. Only administrators can perform this action.
 
 !!! example
     ```

src/how-to/domains/custom-domains.md

@@ -17,7 +17,7 @@ This can be done automatically for domains which are already setup as a Route53
 
 ### Automatic Setup
 
-The CLI includes an [`apppack create custom-domain`](/command-line-reference/apppack_create_custom-domain.md) command for domains which already have a Route53 Hosted Zone in your AWS account. It will handle certificate creation/validation, attaching the certificate to the load balancer, and creating `ALIAS` records which point the domain(s) to the load balancer.
+The CLI includes an [`apppack create custom-domain`](../../command-line-reference/apppack_create_custom-domain.md) command for domains which already have a Route53 Hosted Zone in your AWS account. It will handle certificate creation/validation, attaching the certificate to the load balancer, and creating `ALIAS` records which point the domain(s) to the load balancer.
 
 <script id="asciicast-bwwgM6iTcA3xQR8xoQjKGbjMP" src="https://asciinema.org/a/bwwgM6iTcA3xQR8xoQjKGbjMP.js" data-rows="20" data-theme="monokai" async></script>