mkdocs.yml

# SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev>
# SPDX-License-Identifier: Apache-2.0
#
# mkdocs.yml — MkDocs Material configuration for zenzic-doc
# Migrated from zensical.toml in Sprint 0.14.1.
# ADR-037 Compliance: No hardcoded SemVer. Version injected via extra.zenzic_version.

site_name: Zenzic
site_url: https://zenzic.dev/
docs_dir: docs
site_dir: site
repo_url: https://github.com/PythonWoods/zenzic
repo_name: PythonWoods/zenzic
edit_uri: edit/main/docs/
copyright: "Copyright &copy; 2026 PythonWoods &mdash; Apache-2.0 License"

extra_css:
  - assets/css/zenzic-tailwind.min.css
  - assets/css/extra.css
  # EXTERNAL BUILD ARTIFACT — compiled by human-run Tailwind CLI (no Node.js in CI).
  # Preflight (CSS Reset) is DISABLED to prevent interference with Material base typography.
  # See docs/assets/css/README.md for the build protocol.

extra_javascript:
  - javascripts/mathjax.js


exclude_docs: |
  assets/css/README.md
  includes/*

not_in_nav: |
  includes/*

# --- Navigation (4 tabs: Home / User Documentation / Developer Documentation / Blog)
# navigation.tabs maps each top-level nav entry to a tab in the header.
nav:
  - Home: index.md

  - User Documentation:
    - Getting Started:
      - Tutorials Index: tutorials/index.md
      - Quick Start Tutorial: tutorials/first-audit.md
      - Install & First Run: how-to/install.md
      - Configuration Setup: how-to/initialize-configuration.md
    - Delivery Mechanisms:
      - Editor Index: editor/index.md
      - VS Code Extension (LSP): editor/vscode.md
      - Third-Party Editors (LSP): how-to/editor-integrations.md
      - GitHub Action (CI/CD): how-to/configure-ci-cd.md
      - GitHub Action Reference: reference/zenzic-action.md


    - How-to Guides:
      - How-to Index: how-to/index.md
      - Manage Technical Debt: how-to/handle-technical-debt.md
      - Add Custom Rules: how-to/add-custom-rules.md
      - Configure Adapters: how-to/configure-adapter.md
      - Privacy Gate: how-to/configure-privacy-gate.md
      - Configuration Strategy: how-to/configuration-strategy.md
      - Cross-Site Links: how-to/manage-cross-site-links.md
      - Engine Migration: how-to/migrate-engines.md
      - Use Brand System: how-to/use-brand-system.md
      - Workflow Integration: how-to/workflow-integration.md
      - Configure Social Metadata: how-to/configure-social-metadata.md
      - Add Status Badges: how-to/add-badges.md
      - Troubleshooting: how-to/troubleshooting.md
    - Rule Reference & Catalog:
      - Rules Index: rules/index.md
      - Finding Codes Index: reference/finding-codes.md
      - Core Rule Checks: reference/checks.md
      - Rule Specification Cards:
        - rules/Z000.md
        - rules/Z001.md
        - rules/Z101.md
        - rules/Z102.md
        - rules/Z103.md
        - rules/Z104.md
        - rules/Z105.md
        - rules/Z106.md
        - rules/Z107.md
        - rules/Z108.md
        - rules/Z109.md
        - rules/Z110.md
        - rules/Z111.md
        - rules/Z113.md
        - rules/Z114.md
        - rules/Z620.md
        - rules/Z120.md
        - rules/Z121.md
        - rules/Z122.md
        - rules/Z123.md
        - rules/Z124.md
        - rules/Z201.md
        - rules/Z202.md
        - rules/Z203.md
        - rules/Z204.md
        - rules/Z205.md
        - rules/Z301.md
        - rules/Z302.md
        - rules/Z303.md
        - rules/Z401.md
        - rules/Z402.md
        - rules/Z403.md
        - rules/Z404.md
        - rules/Z405.md
        - rules/Z406.md
        - rules/Z410.md
        - rules/Z411.md
        - rules/Z501.md
        - rules/Z502.md
        - rules/Z503.md
        - rules/Z504.md
        - rules/Z505.md
        - rules/Z506.md
        - rules/Z510.md
        - rules/Z511.md
        - rules/Z512.md
        - rules/Z513.md
        - rules/Z514.md
        - rules/Z515.md
        - rules/Z516.md
        - rules/Z517.md
        - rules/Z518.md
        - rules/Z519.md
        - rules/Z520.md
        - rules/Z601.md
        - rules/Z603.md
        - rules/Z610.md
        - rules/Z611.md
        - rules/Z612.md
        - rules/Z613.md
        - rules/Z614.md
        - rules/Z615.md
        - rules/Z616.md
        - rules/Z617.md
        - rules/Z618.md
        - rules/Z619.md
        - rules/Z901.md
        - rules/Z902.md
        - rules/Z906.md
      - Interactive Rule Examples:
        - tutorials/examples/index.md
        - Z0xx Core Index: tutorials/examples/z0xx-core/index.md
        - tutorials/examples/z0xx-core/z001-config-error.md
        - Z1xx Links Index: tutorials/examples/z1xx-links/index.md
        - tutorials/examples/z1xx-links/z101-broken-links.md
        - tutorials/examples/z1xx-links/z102-anchor-missing.md
        - tutorials/examples/z1xx-links/z103-orphan-link.md
        - tutorials/examples/z1xx-links/z104-file-not-found.md
        - tutorials/examples/z1xx-links/z105-absolute-path.md
        - tutorials/examples/z1xx-links/z107-circular-anchor.md
        - tutorials/examples/z1xx-links/z108-empty-link-text.md
        - tutorials/examples/z1xx-links/z109-external-link-broken.md
        - tutorials/examples/z1xx-links/z110-stale-allowlist.md
        - tutorials/examples/z1xx-links/z120-unknown-html-attr.md
        - tutorials/examples/z1xx-links/z121-missing-href.md
        - tutorials/examples/z1xx-links/z122-jump-link.md
        - tutorials/examples/z1xx-links/z123-non-http-scheme.md
        - tutorials/examples/z1xx-links/z124-opaque-context.md
        - Z2xx Security Index: tutorials/examples/z2xx-security/index.md
        - tutorials/examples/z2xx-security/z201-credentials.md
        - tutorials/examples/z2xx-security/z202-path-traversal.md
        - tutorials/examples/z2xx-security/z204-forbidden-term.md
        - tutorials/examples/z2xx-security/z205-forbidden-scheme.md
        - Z3xx References Index: tutorials/examples/z3xx-references/index.md
        - tutorials/examples/z3xx-references/z301-dangling-ref.md
        - tutorials/examples/z3xx-references/z302-dead-def.md
        - tutorials/examples/z3xx-references/z303-duplicate-def.md
        - Z4xx Topology Index: tutorials/examples/z4xx-topology/index.md
        - tutorials/examples/z4xx-topology/z401-missing-directory-index.md
        - tutorials/examples/z4xx-topology/z402-orphan-page.md
        - tutorials/examples/z4xx-topology/z403-missing-alt.md
        - tutorials/examples/z4xx-topology/z404-config-asset-missing.md
        - tutorials/examples/z4xx-topology/z405-unused-assets.md
        - tutorials/examples/z4xx-topology/z406-nav-contract.md
        - Z5xx Content Index: tutorials/examples/z5xx-content/index.md
        - tutorials/examples/z5xx-content/z501-placeholder.md
        - tutorials/examples/z5xx-content/z502-short-content.md
        - tutorials/examples/z5xx-content/z503-snippet-error.md
        - tutorials/examples/z5xx-content/z505-untagged-code-block.md
        - tutorials/examples/z5xx-content/z506-malformed-frontmatter.md
        - Z6xx Brand Index: tutorials/examples/z6xx-brand/index.md
        - tutorials/examples/z6xx-brand/z601-brand-obsolescence.md
        - tutorials/examples/z6xx-brand/z603-dead-suppression.md
        - tutorials/examples/z6xx-brand/z620-stale-global-suppression.md
    - Technical Reference:
      - CLI Specification: reference/cli.md
      - Configuration Schema: reference/configuration-reference.md
      - Suppression Policy: reference/suppression-policy.md
      - DQS Scoring Algorithm: reference/scoring-algorithm.md
      - Engine Adapters: reference/engines.md
      - Advanced Features: reference/advanced-features.md
      - JSON & SARIF API: reference/api-json.md
      - Brand Kit: reference/brand-kit.md
      - Brand System: reference/brand-system.md
      - Glossary: reference/glossary.md
      - GitHub Action Reference: reference/zenzic-action.md
      - Reference Index: reference/index.md
    - Core Architecture:
      - Explanation Index: explanation/index.md
      - Architecture Index: architecture/index.md
      - Why Zenzic: explanation/why-zenzic.md
      - System Architecture: explanation/architecture.md
      - Language Server Architecture: explanation/language-server-architecture.md
      - Core Mechanics: explanation/core-mechanics.md
      - Scoring System: explanation/scoring-system.md
      - Baseline Tracking: explanation/baseline-tracking.md
      - Discovery Engine: explanation/discovery.md
      - Configuration Loading: explanation/configuration-loading.md
      - Exclusion Design: explanation/exclusion-design.md
      - Structural Integrity: explanation/structural-integrity.md
      - Auto-Fix Philosophy: explanation/auto-fix-philosophy.md
      - Engine Migration Design: explanation/engine-migration-design.md
      - The Zenzic Trinity: explanation/the-zenzic-trinity.md
      - GitHub Action Internals: explanation/github-action-internals.md
      - Privacy Gate: explanation/privacy-gate.md
      - Brand Philosophy: explanation/brand-philosophy.md
      - Community Index: explanation/community-index.md


  - Developer Documentation:
    - developers/index.md
    - How-to:
      - Developer How-to Index: developers/how-to/index.md
      - Contribute:
        - developers/how-to/contribute/index.md
        - developers/how-to/contribute/pull-requests.md
        - developers/how-to/contribute/report-a-bug.md
        - developers/how-to/contribute/report-a-docs-issue.md
        - developers/how-to/contribute/request-a-change.md
      - developers/how-to/implement-adapter.md
      - developers/how-to/release-governance-protocol.md
      - developers/how-to/write-a-check.md
      - developers/how-to/write-plugin.md
      - developers/how-to/write-ast-rule.md
      - developers/how-to/troubleshooting.md
    - Reference:
      - Developer Reference Index: developers/reference/index.md
      - developers/reference/adapter-api.md
      - developers/reference/adapter-examples.md
      - developers/reference/ast-foundations.md
      - developers/reference/cli-architecture.md
      - developers/reference/credential-scanner-obligations.md
      - developers/reference/supply-chain-assurance-profile.md
      - developers/reference/zenzic-style.md
    - Explanation:
      - Developer Explanation Index: developers/explanation/index.md
      - developers/explanation/adapter-internals.md
      - Architecture:
        - architecture/lsp-integration.md
      - ADR Vault:
        - developers/explanation/adr-vault/index.md
        - ADR Records Index: developers/explanation/adr-vault/records/index.md

        - developers/explanation/adr-vault/records/adr-002-zero-subprocesses.md
        - developers/explanation/adr-vault/records/adr-007-sovereign-sandbox.md
        - developers/explanation/adr-vault/records/adr-020-mirror-law.md
        - developers/explanation/adr-vault/records/adr-021-parallel-audit.md
        - developers/explanation/adr-vault/records/adr-022-english-only-governance.md
        - developers/explanation/adr-vault/records/adr-075-radical-unawareness.md
        - developers/explanation/adr-vault/records/adr-090-silent-on-success-unix-philosophy.md
        - developers/explanation/adr-vault/records/adr-091-single-pass-ast-and-cqs.md
        - developers/explanation/adr-vault/records/adr-092-comprehensive-bump-coverage.md
        - developers/explanation/adr-vault/records/adr-agnostic-universalism.md
        - developers/explanation/adr-vault/records/adr-bilingual-structural.md
        - developers/explanation/adr-vault/records/adr-decentralized-cli.md
        - developers/explanation/adr-vault/records/adr-discovery.md
        - developers/explanation/adr-vault/records/adr-lint-source.md
        - developers/explanation/adr-vault/records/adr-native-telemetry.md
        - developers/explanation/adr-vault/records/adr-path-sovereignty.md
        - developers/explanation/adr-vault/records/adr-regex-acl.md
        - developers/explanation/adr-vault/records/adr-unified-perimeter.md
      - developers/explanation/core-laws.md
      - developers/explanation/mdx-asset-rationale.md
      - developers/explanation/sovereign-verification-model.md
      - developers/explanation/tailwind-mkdocs-bridge.md
      - Governance:
        - developers/explanation/governance/index.md
        - developers/explanation/governance/evolution_policy.md
        - developers/explanation/governance/exit_strategy.md
        - developers/explanation/governance/licensing.md
        - developers/explanation/governance/technical-debt.md
        - developers/explanation/governance/lpgp.md

  - Blog: blog/


theme:
  name: material
  custom_dir: overrides
  logo: assets/brand/svg/zenzic-icon.svg
  favicon: assets/brand/svg/zenzic-icon.svg
  language: en
  font: false
  palette:
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.breadcrumbs
    - navigation.path
    - navigation.top
    - toc.follow
    - content.action.edit
    - content.action.view
    - content.code.copy

extra:
  # ADR-037: No hardcoded SemVer in any .html or .md source.
  # CI pipeline passes the current version at build time, e.g.:
  #   uv run mkdocs build --extra zenzic_version=0.14.1
  zenzic_version: "0.30.0"  # release sync
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/PythonWoods/zenzic
      name: Zenzic on GitHub
    - icon: fontawesome/brands/hashnode
      link: https://hashnode.com/@Pythonwoods
      name: PythonWoods on Hashnode
    - icon: fontawesome/solid/screwdriver-wrench
      link: https://devtool.io
      name: Featured on DevTool.io
    - icon: fontawesome/solid/rss
      link: /blog/rss.xml
      name: RSS Feed
    - icon: fontawesome/solid/square-rss
      link: /blog/atom.xml
      name: Atom Feed

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

plugins:
  - search
  - blog:
      blog_dir: blog
      archive: true
      categories: true
      pagination: true
      pagination_per_page: 10
      pagination_url_format: "page/{page}"
  - rss:
      match_path: "blog/posts/.*"
      date_from_meta:
        as_creation: date
      use_material_blog: true
      use_material_social_cards: true
      abstract_delimiter: <!-- more -->
      abstract_chars_count: 500
      pretty_print: true
      image: https://zenzic.dev/assets/brand/svg/zenzic-icon.svg
      feed_description: "Engineering insights, release notes and documentation quality guides from the Zenzic team."
      feed_ttl: 1440
      stylesheet: /blog/rss.xsl
      feeds_filenames:
        rss_created: blog/rss.xml
        rss_updated: blog/atom.xml
  - minify:
      minify_html: true
      minify_css: true
      minify_js: false

# MkDocs strict-mode link validation.
# tutorials/examples/ pages intentionally contain extensionless/malformed links
# to demonstrate Zenzic's own rule findings (Z101, Z103, etc.) — docs-as-code
# test fixtures. Suppress INFO-level warnings that would abort --strict build.
validation:
  links:
    unrecognized_links: ignore
  nav:
    not_found: ignore