update doc tooling to Zensical

Author: tomkralidis

.github/workflows/docs.yml

@@ -18,6 +18,22 @@ jobs:
           python-version: '3.12'
       - name: Install requirements 📦
         run: |
-          pip3 install mkdocs
-      - name: Deploy 📦
-        run: cd docs && mkdocs gh-deploy --force -m 'update website'
+          pip3 install zensical
+      - name: Build site 📦
+        run: |
+          zensical build --clean --strict
+          mv site /tmp/
+      - name: checkout gh-pages branch
+        uses: actions/checkout@master
+        with:
+          ref: gh-pages
+      - name: Deploy to GitHub Pages 📦
+        run: |
+          git checkout gh-pages
+          git config --global user.email "tomkralidis@gmail.com"
+          git config --global user.name "Tom Kralidis"
+          ls | grep -v ".nojekyll"| xargs rm -fr
+          mv -f /tmp/site/* .
+          git add .
+          git commit -am "update website via GitHub Actions"
+          git push

.github/workflows/main.yml

@@ -23,7 +23,7 @@ jobs:
         pip3 install ".[docs]"
         pip3 install ".[release]"
     - name: build docs 🏗️
-      run: mkdocs build -f docs/mkdocs.yml
+      run: zensical build --clean --strict
     - name: run flake8 ⚙️
       run: flake8
     - name: build Python package 🏗️

docs/README.md

@@ -1,7 +1,7 @@
 # pygeometa Website
 
 The pygeometa [website](https://geopython.github.io/pygeometa/) is powered
-by [MkDocs](https://www.mkdocs.org) which facilitates easy management
+by [Zensical](https://zensical.org) which facilitates easy management
 of website content and publishing.
 
 ## Setting up the website environment locally
@@ -16,9 +16,9 @@ git clone https://github.com/geopython/pygeometa.git
 pip3 install -r requirements-dev.txt
 cd pygeometa/doc
 # build the website
-mkdocs build
+zensical build --clean --strict
 # serve locally
-mkdocs serve  # website is made available on http://localhost:8000/
+zensical serve  # website is made available on http://localhost:8000/
 ```
 
 ## Content management workflow
@@ -39,10 +39,10 @@ The basic workflow is as follows:
 
 ```bash
 vi content/new-page.md  # add content
-vi mkdocs.yml  # add to navigation section
+vi zensical.toml # add to navigation section
 # edit any other files necessary which may want to link to the new page
 git add content/new-page.md
-git commit -m 'add new page on topic x' content/new-page.md mkdocs.yml
+git commit -m 'add new page on topic x' content/new-page.md zensical.toml
 git push origin master
 ```
 
@@ -56,8 +56,4 @@ git push origin master
 
 ## Publishing updates to the live site
 
-```bash
-# NOTE: you require access privileges to the GitHub repository
-# to publish live updates
-mkdocs gh-deploy -m 'add new page on topic x'
-```
+Website updates are automatically published via GitHub Actions.

docs/mkdocs.yml

@@ -0,0 +1,40 @@
+[project]
+site_name = "pygeometa: Metadata Creation for the Rest of Us"
+site_description = "pygeometa is a Python package to manage metadata for geospatial datasets"
+site_author = "the pygeometa team"
+copyright = "© 2009-2025 Government of Canada, 2015-2026 pygeometa development team"
+site_url = "https://geopython.github.io/pygeometa"
+repo_url = "https://github.com/geopython/pygeometa"
+docs_dir = "content"
+edit_uri = "edit/master/content"
+
+nav = [
+    {"Code" = "https://github.com/geopython/pygeometa"},
+    {"Tutorial" = "tutorial.md"},
+    {"Reference" = [
+        {"Metadata Control File" = [
+          {"Core" = "reference/mcf.md"},
+          {"Extensions" = [
+            {"ISO 19115-2, Part 2: Extensions for acquisition and processing" = "reference/extensions/iso19139-2.md"},
+            {"ISO Harmonized North American Profile (HNAP)" = "reference/extensions/iso19139-hnap.md"},
+            {"WMO Core Metadata Profile" = "reference/extensions/wmo-cmp.md"},
+            {"WMO Core Metadata Profile 2" = "reference/extensions/wmo-wcmp2.md"},
+            {"WMO WIGOS Metadata Standard" = "reference/extensions/wmo-wigos.md"}
+          ]},
+        ]},
+      ]},
+    {"pygeoapi plugin" = "pygeoapi-plugin.md"}
+]
+
+[project.theme]
+language = "en"
+features = [
+  "content.action.edit",
+  "content.action.view",
+  "navigation.top",
+  "navigation.tracking.prev_next",
+  "navigation.tracking.section"
+]
+
+[project.extra]
+homepage = "https://geopython.github.io/pygeometa"

docs/zensical.toml

@@ -36,7 +36,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["flake8"]
-docs = ["mkdocs", "mkdocs-bootswatch"]
+docs = ["zensical"]
 release = ["build", "twine", "wheel"]
 
 [project.scripts]