mkdocs.yml

# CapiscIO Unified Documentation
# Monorepo aggregating all product documentation

site_name: CapiscIO Documentation
site_url: https://docs.capisc.io
site_description: Unified documentation for CapiscIO - The Authority Layer for the Agent-to-Agent (A2A) Protocol.
site_author: CapiscIO Team
copyright: Copyright © 2025 CapiscIO

repo_name: capiscio
repo_url: https://github.com/capiscio
edit_uri: ""

theme:
  name: material
  logo: assets/logo.png
  favicon: assets/favicon.ico
  custom_dir: docs/overrides
  font:
    text: Inter
    code: JetBrains Mono
  palette:
    - scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
    - scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
  
  features:
    - navigation.instant
    - navigation.instant.progress
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    # - navigation.sections  # Disabled: makes nested items appear at same level
    # - navigation.expand    # Disabled: auto-expands all sections
    - navigation.path
    - navigation.indexes
    - navigation.top
    - navigation.footer
    - toc.follow
    # - toc.integrate  # Disabled: keeps right-hand TOC for long pages
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - content.tooltips
    - header.autohide

plugins:
  - search
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true
      cache_safe: true
  - monorepo:
      enabled: !ENV [ENABLE_MONOREPO, true]
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
      fallback_to_build_date: true
      enabled: !ENV [ENABLE_GIT_DATES, true]
      strict: false
  - mkdocstrings:
      enabled: !ENV [ENABLE_MKDOCSTRINGS, true]
      default_handler: python
      handlers:
        python:
          paths: ["../capiscio-sdk-python", "../capiscio-mcp-python"]
          import:
            # Enable cross-references to Python stdlib and pydantic
            - https://docs.python.org/3/objects.inv
            - https://docs.pydantic.dev/latest/objects.inv
          options:
            show_source: false
            show_root_heading: true
            show_signature_annotations: true
            separate_signature: true
            docstring_style: google
            members_order: source
            show_if_no_docstring: false
            # Preload pydantic to resolve base classes
            preload_modules:
              - pydantic

markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      permalink_title: Anchor link to this section
      toc_depth: 3
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - 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.smartsymbols
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

hooks:
  - hooks/version_vars.py

extra:
  capiscio_version: "2.6.0"
  protocol_version: "0.3.0"
  homepage: https://docs.capisc.io
  # Analytics: Cloudflare Pages auto-injects Web Analytics at the edge
  # Enable in: CF Dashboard → Pages → capiscio-docs → Settings → Web Analytics
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/capiscio
      name: CapiscIO on GitHub
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/capiscio
      name: CapiscIO on Twitter

extra_css:
  - assets/stylesheets/custom.css

nav:
  - Home: index.md
  - Overview: overview/index.md
  
  - Getting Started:
      - getting-started/index.md
      - Validate Your Agent:
          - getting-started/validate/1-intro.md
          - getting-started/validate/2-install.md
          - getting-started/validate/3-validate.md
          - getting-started/validate/4-reports.md
          - getting-started/validate/5-next.md
      - Secure Your Agent:
          - getting-started/secure/1-intro.md
          - getting-started/secure/2-sdk.md
          - getting-started/secure/3-guard.md
          - getting-started/secure/4-test.md
          - getting-started/secure/5-production.md
      - Protect MCP Tools:
          - mcp-guard/getting-started/installation.md
          - mcp-guard/getting-started/quickstart.md
      - CI/CD Integration:
          - getting-started/cicd/1-intro.md
          - getting-started/cicd/2-action.md
          - getting-started/cicd/3-thresholds.md
          - getting-started/cicd/4-comments.md
          - getting-started/cicd/5-matrix.md
      - Complete Workflow: getting-started/complete-workflow.md
      - Sample Files: samples.md

  - Concepts:
      - concepts/index.md
      - Identity & DIDs: identity/index.md
      - Trust Badges: trust/index.md
      - Trust Levels: concepts/trust-model.md
      - Agent Registry: registry/index.md
      - Validation & Scoring:
          - concepts/validation.md
          - concepts/scoring.md
      - Enforcement: concepts/enforcement.md
      - Policy Scoping: concepts/policy-scoping.md
      - MCP Security:
          - Overview: concepts/mcp-security.md

  - How-To Guides:
      - how-to/index.md
      - Validation:
          - Validate from URL: how-to/validation/validate-url.md
          - Bulk Validation: how-to/validation/bulk-validate.md
          - Schema-Only Mode: how-to/validation/schema-only.md
          - Strict Mode: how-to/validation/strict-mode.md
          - Custom Timeout: how-to/validation/custom-timeout.md
          - Trust Scores: how-to/validation/trust-scores.md
      - Security:
          - Sign Outbound: how-to/security/sign-outbound.md
          - Verify Inbound: how-to/security/verify-inbound.md
          - Trust Badges: how-to/security/badges.md
          - Badge Keeper: how-to/security/badge-keeper.md
          - Policy Enforcement: how-to/security/policy-enforcement.md
          - Security Gateway: how-to/security/gateway-setup.md
          - Ephemeral Deployment: how-to/security/ephemeral-deployment.md
          - Dev Mode: how-to/security/dev-mode.md
          - Key Rotation: how-to/security/key-rotation.md
          - Trust Store: how-to/security/trust-store.md
      - MCP Security:
          - Protect MCP Tools: mcp-guard/guides/server-side.md
          - Verify MCP Servers: mcp-guard/guides/client-side.md
          - Server Registration: mcp-guard/guides/server-registration.md
          - Evidence Logging: mcp-guard/guides/evidence.md
          - MCP SDK Integration: mcp-guard/guides/mcp-integration.md
      - Integrations:
          - FastAPI: how-to/integrations/fastapi.md
          - Flask: how-to/integrations/flask.md
          - Express: how-to/integrations/express.md
          - LangChain: how-to/integrations/langchain.md
      - Policy:
          - Configure Agent Policy: how-to/configure-agent-policy.md
          - Embedded Policy Enforcement: how-to/embedded-policy-enforcement.md
      - CI/CD:
          - Pre-commit Hook: how-to/cicd/pre-commit.md
          - GitLab CI: how-to/cicd/gitlab-ci.md
          - Jenkins: how-to/cicd/jenkins.md

  - Reference:
      - reference/index.md
      - CapiscIO Core:
          - CLI Reference: reference/cli/index.md
          - Validation Reference: reference/cli/validation.md
          - Go API: reference/go-api.md
          - gRPC Services: reference/grpc.md
      - Agent Guard:
          - reference/sdk-python/index.md
          - Badge: reference/sdk-python/badge.md
          - SecurityConfig: reference/sdk-python/config.md
          - CapiscioSecurityExecutor: reference/sdk-python/executor.md
          - SimpleGuard: reference/sdk-python/simple-guard.md
          - MCP: reference/sdk-python/mcp.md
          - Types: reference/sdk-python/types.md
          - Errors: reference/sdk-python/errors.md
          - PIP Types: reference/sdk-python/pip.md
      - MCP Guard: '!include ../capiscio-mcp-python/mkdocs.yml'
      - Server API:
          - reference/server/index.md
          - API Reference: reference/server/api.md
          - Deployment: reference/server/deployment.md
          - Badge CA: reference/server/badge-ca.md
          - Policy Enforcement: reference/server/policy-enforcement.md
      - Policy:
          - Policy Config YAML: reference/policy-config-yaml.md
          - Policy API: reference/policy-api.md
      - Configuration: reference/configuration.md
      - Agent Card Schema: reference/agent-card-schema.md
      - Installation:
          - reference/wrappers/index.md
          - Python (pip): reference/wrappers/python.md
          - Node.js (npm): reference/wrappers/node.md
          - GitHub Action: reference/wrappers/github-action.md

  - Troubleshooting: troubleshooting.md

  - Community:
      - Contributing: community/contributing.md
      - Support: community/support.md

  - RFCs: '!include ../capiscio-rfcs/mkdocs.yml'

# watch:
#   - docs
#   - ../capiscio-core/docs
#   - ../capiscio-python/docs
#   - ../capiscio-node/docs
#   - ../validate-a2a/docs
#   - ../capiscio-sdk-python/docs