Specification: Migrate Documentation Pipeline to Zensical with Capability Parity + Code Copy Button

[MariusStorhaug]

Context

Process-PSModule currently builds module documentation with MkDocs/Material. We have completed initial evaluation in #255, and there is an open draft PR #334 that adds content.code.copy in fixture configs for copy-button support. We now need an implementation specification that migrates to Zensical while preserving current behavior and explicitly carrying forward the code-copy capability.

Goal

Migrate the docs build pipeline from MkDocs/Material to Zensical, adopting the modern zensical.toml configuration format while maintaining backward compatibility with existing module repositories.

Scope

• Process-PSModule workflow and docs build path.
• Fixture config transformation and/or compatibility bridge for module repos.
• Pages artifact/deploy shape remains compatible with existing release flow.
• Include copy-button behavior equivalent to the current MkDocs content.code.copy intent from Enable MkDocs code-copy buttons in documentation site configs #334.

Current Capability Baseline (Must Keep)

• Existing docs artifact ingestion and site structuring behavior in Build-Site workflow.
• Existing repo token replacement in config (currently -{{ REPO_NAME }}-, -{{ REPO_OWNER }}- in mkdocs.yml context).
• Existing navigation/search behavior from current config profile.
• Existing markdown extension behavior in rendered pages.
• Existing social links/metadata behavior where configured.
• Existing docs output and upload-pages-artifact flow.
• Code block copy affordance (copy button) on documentation pages.

Required Changes

1. Primary configuration format: Adopt zensical.toml as the target format for new/migrated configs.

   • Define PSModule-standard zensical.toml template with Zensical setup/basics recommendations applied.
   • Include all feature flags for parity with current experience (nav.instant, search.highlight, etc.).

2. Migration strategy:

   • Replace docs tool install/build commands from MkDocs/Material to Zensical in Build-Site workflow.
   • Implement a config discovery/transformation layer:
     • If zensical.toml exists, use it directly.
     • If only mkdocs.yml exists, use Zensical's native mkdocs.yml support (backward compat).
     • Provide optional conversion tool for module maintainers to migrate from mkdocs.yml → zensical.toml.

3. Configuration contract:

   • Define PSModule-approved feature subset for zensical.toml (nav/search/theme/markdown extensions).
   • Document Tier 1 plugin equivalents from Zensical (search, markdown extensions, etc.).
   • Explicitly address Tier 2 plugins that may need validation or workarounds (git-authors, git-revision-date-localized, git-committers).

4. Copy-button support in Zensical:

   • Verify that Zensical markdown extension pymdownx.superfences or equivalent provides code copy affordance.
   • If not native, document how to enable via theme customization or CSS extension.
   • Test with generated fixture repos.

5. Placeholder substitution:

   • Adapt token replacement logic to work with zensical.toml TOML syntax.
   • Preserve repo owner/name injection at build time.

6. Documentation updates:

   • Update Process-PSModule README to reference Zensical and zensical.toml.
   • Create migration guide for module maintainers (mkdocs.yml → zensical.toml conversion steps).
   • Document the supported feature set for PSModule projects.

Acceptance Criteria

• Site builds successfully with Zensical using zensical.toml in Process-PSModule CI.
• Docs output is published through existing pages artifact flow with no deployment regressions.
• Existing test fixture repositories still build docs successfully using the migrated flow.
• Search, navigation, and markdown rendering parity is verified against baseline pages.
• Code blocks show a working copy button in generated docs (Zensical-rendered pages).
• Config discovery/transformation logic handles both zensical.toml and mkdocs.yml (for backward compat).
• No required capability from the current baseline is removed without explicit follow-up issue.
• Enable MkDocs code-copy buttons in documentation site configs #334 is either merged into this migration (if applicable) or closed as superseded with rationale.
• Migration guide and PSModule zensical.toml template are documented for rollout to other repos.

Implementation Notes

• Start with zensical.toml as the primary target, but ensure mkdocs.yml graceful fallback for repos not yet migrated.
• Keep migration incremental and reviewable (workflow/tooling changes first, then config parity refinements).
• Validate Tier 2 plugin equivalents early (git-authors, git-committers, git-revision-date-localized).
• Capture any parity gaps as separate issues with mitigation paths.
• Leverage Zensical's documented feature parity page to cross-check requirements.
• Versioning and comment systems are out of scope for this migration; they can be added in follow-up work if needed.

Zensical Documentation References

• Transition strategy: https://zensical.org/compatibility/
• Setup/Basics: https://zensical.org/docs/setup/basics/
• Feature parity: https://zensical.org/compatibility/features/
• Plugin parity (Tier 1/2): https://zensical.org/compatibility/plugins/
• Navigation: https://zensical.org/docs/setup/navigation/
• Search: https://zensical.org/docs/setup/search/

Out of Scope

• Versioning support (can be added in follow-up issue if needed).
• Comment system integration (can be added in follow-up issue if needed).
• Full documentation IA/content redesign.
• Non-essential theme redesign unrelated to parity.
• Breaking URL structure changes unless explicitly approved.

Related

• Evaluation issue: Migrate documentation generator from MkDocs to Zensical #255
• Potentially stale/superseded copy-button PR: Enable MkDocs code-copy buttons in documentation site configs #334