fix: resolve readthedocs build failure and finalize zensical migration

[JacksonFergusonDev]

Overview

This PR resolves the Read the Docs (RTD) build failure following the migration from mkdocs-material to zensical.

The primary failure point was RTD's default execution logic; the presence of a mkdocs: configuration block in .readthedocs.yaml triggered the built-in MkDocs pipeline. This environment attempts to run python -m mkdocs build, which is incompatible with a project transitioned to the Zensical stack. The resolution involves implementing a decoupled, custom build flow. We now leverage uv for deterministic dependency management, execute zensical build directly, and explicitly route the generated static HTML artifacts to the designated RTD output directory.

Changes

• .readthedocs.yaml

  • Deprecation of mkdocs: block: Removed the native section to prevent RTD from invoking its automated, legacy MkDocs build sequence.
  • Custom Job Flow: Implemented a manual build override using uv to provision the environment and install the required docs dependency group.
  • Artifact Management: Added a build step that executes zensical build and maps the output to $READTHEDOCS_OUTPUT/html/, ensuring RTD can correctly ingest and serve the documentation.

• mkdocs.yml

  • Namespace Refactoring: Updated the emoji handler namespace to zensical.extensions.emoji.*. This aligns the project with the Zensical compatibility layer, replacing the previous Material module paths.
  • Configuration Preservation: Maintained the mkdocs.yml schema rather than migrating to zensical.toml. This utilizes Zensical’s native support for legacy MkDocs configurations, minimizing friction during the transition.

Why this works

While Zensical functions as a drop-in replacement for the MkDocs and Material ecosystem, it requires direct execution control. RTD’s internal logic defaults to the standard MkDocs binary if it detects the relevant YAML keys. By shifting to a command-based pipeline, we bypass the restrictive default environment and allow Zensical to parse the existing mkdocs.yml metadata and generate the site independently.

Verification

• Local Environment: Verified that zensical build compiles the documentation successfully against the current configuration without schema errors.
• Read the Docs CI: Confirmed the project successfully builds via the custom pipeline. The CI logs show correct artifact generation and deployment from the $READTHEDOCS_OUTPUT/html/ path.