Updates doc builder to use mkpages

.github/workflows/publish-docs.yml

@@ -39,7 +39,7 @@ jobs:
 
       - name: Build Jekyll source tree
         run: |
-          python scripts/build_pages_site.py --output _site_src
+          mkpages build docs/ --output _site_src
 
       - name: Build site with Jekyll
         uses: actions/jekyll-build-pages@v1

.gitignore

@@ -19,4 +19,5 @@ baketest.env
 out.env
 .codex
 .agents/
-_site*
+_site*
+.mkpages/

README.md

@@ -161,4 +161,4 @@ pathbase match '/mnt/projects/demo/report.txt'
 
 Additional documentation lives in [docs/index.md](docs/index.md):
 
-- [Examples](docs/examples.md)
+- [Examples](docs/examples/index.md)

docs/api.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Pathbase API
+description: Python API patterns for formatting, parsing, and matching templates.
+---
+
 # Pathbase API
 
 This guide focuses on the Python API surface that is most useful when

docs/distribution.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Distribution
+description: How pathbase example environments are distributed with distman.
+---
+
 # Distribution
 
 `pathbase` includes a `dist.json` file for use with

examples/animation/README.md → docs/examples/animation/index.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Animation Example
+description: Example animation asset and publish templates for pathbase.
+---
+
 # Animation Example
 
 This example uses asset, department, and version-style naming common in
@@ -15,6 +21,13 @@ Example filepath:
 /mnt/projects/bigbuckbunny/assets/bunny/model/bunny_publish_v003.usd
 ```
 
+Example env file:
+[examples/animation/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/animation/pathbase.env)
+
+```bash
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/animation/pathbase.env -o pathbase.env
+```
+
 Try it:
 
 ```bash

examples/data-pipeline/README.md → docs/examples/data-pipeline/index.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Data Pipeline Example
+description: Example partitioned dataset templates for pathbase.
+---
+
 # Data Pipeline Example
 
 This example shows a partitioned data layout for datasets, dates, and shard
@@ -15,6 +21,13 @@ Example filepath:
 /mnt/data/orders/2026-07-26/region-us-west/part-0007.parquet
 ```
 
+Example env file:
+[examples/data-pipeline/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/data-pipeline/pathbase.env)
+
+```bash
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/data-pipeline/pathbase.env -o pathbase.env
+```
+
 Try it:
 
 ```bash

docs/examples.md → docs/examples/index.md

@@ -1,16 +1,29 @@
+---
+layout: default
+title: Pathbase Examples
+description: Example env layouts and parsing patterns for common pathbase workflows.
+---
+
 # Pathbase Examples
 
+This section collects example `pathbase.env` layouts for different industries
+and use cases. The example env files themselves still live under `examples/` in
+the repository.
+
 ## Example Flavors
 
 For concrete, domain-specific `pathbase.env` examples, see:
 
-- [Examples Overview](/examples/README.md)
-- [VFX](/examples/vfx/README.md)
-- [Animation](/examples/animation/README.md)
-- [Data Pipeline](/examples/data-pipeline/README.md)
-- [Logs](/examples/logs/README.md)
-- [ML Artifacts](/examples/ml-artifacts/README.md)
-- [Overrides](/examples/overrides/README.md)
+- [VFX](vfx/)
+- [Animation](animation/)
+- [Data Pipeline](data-pipeline/)
+- [Logs](logs/)
+- [ML Artifacts](ml-artifacts/)
+- [Overrides](overrides/)
+
+These examples are not part of the `pathbase` core API. They are intended to
+show different ways to model path templates without locking the library to one
+domain.
 
 ## Parse a Filepath Without Knowing the Template
 
@@ -47,7 +60,7 @@ without manually specifying the template name.
 
 The same auto-discovery model is available in Python API integrations via
 `match_template(path, env=...)` and `Template.from_path(path, env=...)`. See
-[API](api.md) for examples.
+[API](../api.md) for examples.
 
 If `envstack` is not installed, `pathbase` can still discover templates from
 plain environment variables:
@@ -432,17 +445,16 @@ Expected output:
 
 ## Envstack Example
 
-The repository includes several domain-specific env examples under
-[examples/README.md](../examples/README.md), showing how template strings can
-be supplied from environment configuration while keeping `pathbase` itself
-dependency-free.
+The repository includes several domain-specific env examples under this
+section, showing how template strings can be supplied from environment
+configuration while keeping `pathbase` itself dependency-free.
 
 For the shared-defaults plus project-overrides pattern, see
-[Overrides](overrides.md).
+[Overrides](../overrides.md).
 
 For `distman` target selection and deployment examples, including selecting an
 example flavor while always deploying to the same `pathbase.env` destination, see
-[Distribution](distribution.md).
+[Distribution](../distribution.md).
 
 ## CLI Examples
 

examples/logs/README.md → docs/examples/logs/index.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Logs Example
+description: Example service log storage templates for pathbase.
+---
+
 # Logs Example
 
 This example models service log storage grouped by environment, service, date,
@@ -15,6 +21,13 @@ Example filepath:
 /var/log/prod/render-api/2026-07-26/error.log
 ```
 
+Example env file:
+[examples/logs/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/logs/pathbase.env)
+
+```bash
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/logs/pathbase.env -o pathbase.env
+```
+
 Try it:
 
 ```bash

examples/ml-artifacts/README.md → docs/examples/ml-artifacts/index.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: ML Artifacts Example
+description: Example experiment artifact templates for pathbase.
+---
+
 # ML Artifacts Example
 
 This example stores experiment outputs under project, experiment, run, and
@@ -15,6 +21,13 @@ Example filepath:
 /mnt/ml/pathbase/baseline/run-001/metrics.json
 ```
 
+Example env file:
+[examples/ml-artifacts/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/ml-artifacts/pathbase.env)
+
+```bash
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/ml-artifacts/pathbase.env -o pathbase.env
+```
+
 Try it:
 
 ```bash

examples/overrides/README.md → docs/examples/overrides/index.md

@@ -1,10 +1,25 @@
+---
+layout: default
+title: Overrides Example
+description: Example shared and project-specific override templates for pathbase.
+---
+
 # Overrides Example
 
 This folder demonstrates a shared `pathbase.env` plus a higher-priority
 project-specific override.
 
-- [Shared](shared/pathbase.env)
-- [Big Buck Bunny Override](bigbuckbunny/pathbase.env)
+- Shared env file: `examples/overrides/shared/pathbase.env`
+- Big Buck Bunny override: `examples/overrides/bigbuckbunny/pathbase.env`
+
+GitHub source:
+- [examples/overrides/shared/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/overrides/shared/pathbase.env)
+- [examples/overrides/bigbuckbunny/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/overrides/bigbuckbunny/pathbase.env)
+
+```bash
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/overrides/shared/pathbase.env -o shared.pathbase.env
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/overrides/bigbuckbunny/pathbase.env -o bigbuckbunny.pathbase.env
+```
 
 Shared template example:
 

examples/vfx/README.md → docs/examples/vfx/index.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: VFX Example
+description: Example visual effects path templates for pathbase.
+---
+
 # VFX Example
 
 This example models a common visual effects layout with show, sequence, shot,
@@ -15,6 +21,13 @@ Example filepath:
 /mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr
 ```
 
+Example env file:
+[examples/vfx/pathbase.env](https://github.com/rsgalloway/pathbase/blob/master/examples/vfx/pathbase.env)
+
+```bash
+curl -L https://raw.githubusercontent.com/rsgalloway/pathbase/master/examples/vfx/pathbase.env -o pathbase.env
+```
+
 Try it:
 
 ```bash

docs/index.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Pathbase Docs
+description: Overview and quick-start examples for pathbase path templates.
+---
+
 # Pathbase Docs
 
 `pathbase` is a lightweight Python library for formatting paths, parsing paths

docs/mkpages.yml

@@ -0,0 +1,18 @@
+title: pathbase
+description: Lightweight bidirectional filesystem path templates for Python.
+theme: default
+navigation:
+  - label: Home
+    href: /
+  - label: API
+    href: /api/
+  - label: Examples
+    href: /examples/
+  - label: Distribution
+    href: /distribution/
+  - label: Overrides
+    href: /overrides/
+  - label: GitHub
+    href: https://github.com/rsgalloway/pathbase
+  - label: PyPI
+    href: https://pypi.org/project/pathbase/

docs/overrides.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Overrides
+description: Patterns for layering shared and project-specific pathbase templates.
+---
+
 # Overrides
 
 `pathbase` works especially well with envstack-managed environments, where

pyproject.toml

@@ -39,7 +39,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Utilities",
 ]
-optional-dependencies = { dev = ["pytest", "flake8==7.1.1", "mccabe==0.7.0", "isort==5.13.2", "black==24.8.0"], test = ["pytest"] }
+optional-dependencies = { dev = ["pytest", "flake8==7.1.1", "mccabe==0.7.0", "isort==5.13.2", "black==24.8.0", "mkpages"], test = ["pytest"] }
 
 [project.scripts]
 pathbase = "pathbase.cli:main"