mkdocs.yml

site_name: PromptScript
site_url: https://getpromptscript.dev/
site_description: 'Prompt-as-Code for Enterprise AI. Standardize, audit, and deploy instructions across any AI coding assistant.'
site_author: PromptScript Team
repo_url: https://github.com/mrwogu/promptscript
repo_name: mrwogu/promptscript

# Exclude build artifacts from documentation
exclude_docs: |
  __snapshots__/

copyright: Copyright © 2026 PromptScript Contributors

hooks:
  - docs_extensions/mkdocs_hooks.py

theme:
  name: material
  custom_dir: docs/overrides
  language: en
  logo: assets/images/logo.svg
  favicon: assets/images/favicon.svg

  palette:
    # Light mode
    - media: '(prefers-color-scheme: light)'
      scheme: default
      primary: deep purple
      accent: purple
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - media: '(prefers-color-scheme: dark)'
      scheme: slate
      primary: deep purple
      accent: purple
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

  features:
    # Navigation
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.indexes
    - navigation.top
    - navigation.footer

    # Table of contents
    - toc.follow

    # Search
    - search.suggest
    - search.highlight
    - search.share

    # Content
    - content.code.copy
    - content.code.select
    - content.code.annotate
    - content.tabs.link
    - content.tooltips
    # Header
    - header.autohide
    - announce.dismiss

  icon:
    repo: fontawesome/brands/github

plugins:
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - minify:
      minify_html: true
  - llmstxt:
      full_output: llms-full.txt
      markdown_description: |
        PromptScript is a language and toolchain for standardizing AI coding
        assistant instructions across enterprise organizations. It compiles
        .prs files to native formats for 37 AI agent platforms including
        GitHub Copilot, Claude Code, Cursor, Windsurf, and more.
      sections:
        Getting Started:
          - getting-started.md
          - tutorial.md
        Reference:
          - reference/language.md: Complete PromptScript language specification
          - reference/cli.md: CLI commands and options
          - reference/config.md: Configuration file format
        Formatters:
          - reference/formatters/index.md: All 37 supported AI agent formatters
          - reference/formatters/claude.md: Claude Code output format, skills, agents, local files
          - reference/formatters/github.md: GitHub Copilot output format, instructions, prompts, skills
          - reference/formatters/cursor.md: Cursor output format, MDC frontmatter, commands
          - reference/formatters/antigravity.md: Antigravity output format, workflows, activation types
          - reference/formatters/factory.md: Factory AI output format, droids, skills
          - reference/formatters/gemini.md: Gemini CLI output format, commands, skills
          - reference/formatters/opencode.md: OpenCode output format, commands, skills, agents
        Guides:
          - guides/formatter-architecture.md: Internal architecture of formatters
          - guides/inheritance.md: PromptScript inheritance system
          - guides/multi-file.md: Multi-file organization
          - guides/ci.md: CI/CD integration
          - guides/registry.md: Building a PromptScript registry
          - guides/enterprise.md: Enterprise setup
          - guides/migration.md: Migration guide
        Examples:
          - examples/minimal.md: Minimal project setup
          - examples/team-setup.md: Team configuration
          - examples/enterprise.md: Enterprise example
          - examples/skills-and-local.md: Skills and local overrides
          - examples/agents.md: Claude agent configuration
        Optional:
          - guides/faq.md: Frequently asked questions
          - guides/vs-manual.md: Comparison with manual configuration
          - testing/parity-testing.md: Formatter parity testing
          - testing/feature-coverage.md: Feature coverage matrix

markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      toc_depth: 3

  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - 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.magiclink:
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: mrwogu
      repo: promptscript
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
        - name: promptscript
          class: highlight
          format: !!python/name:docs_extensions.mkdocs_hooks.format_promptscript
        - name: prs
          class: highlight
          format: !!python/name:docs_extensions.mkdocs_hooks.format_promptscript
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

extra:
  version:
    provider: mike
    default: latest
    alias: true
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/mrwogu/promptscript
    - icon: fontawesome/brands/npm
      link: https://www.npmjs.com/org/promptscript

extra_css:
  - assets/stylesheets/extra.css

extra_javascript:
  - assets/javascripts/compile-demo.js
  - assets/javascripts/init-demo.js

nav:
  - Home: index.md
  - Playground: /playground/
  - Getting Started:
      - getting-started.md
      - tutorial.md
  - Reference:
      - reference/index.md
      - Language: reference/language.md
      - CLI: reference/cli.md
      - Configuration: reference/config.md
      - Formatters:
          - reference/formatters/index.md
          - Claude Code: reference/formatters/claude.md
          - GitHub Copilot: reference/formatters/github.md
          - Cursor: reference/formatters/cursor.md
          - Antigravity: reference/formatters/antigravity.md
          - Factory AI: reference/formatters/factory.md
          - Gemini CLI: reference/formatters/gemini.md
          - OpenCode: reference/formatters/opencode.md
  - Guides:
      - guides/index.md
      - Using npx skills: guides/npx-skills.md
      - Building Skills: guides/building-skills.md
      - Skill Composition: guides/skill-composition.md
      - Skill Overlays: guides/skill-overlays.md
      - Local Skills: guides/local-skills.md
      - Skill Contracts: guides/skill-contracts.md
      - Shared Resources: guides/shared-resources.md
      - Build Your Registry: guides/registry.md
      - CI/CD Integration: guides/ci.md
      - Docker: guides/docker.md
      - Inheritance: guides/inheritance.md
      - Multi-File Organization: guides/multi-file.md
      - Enterprise Setup: guides/enterprise.md
      - Migration: guides/migration.md
      - FAQ: guides/faq.md
      - Markdown Imports: guides/markdown-imports.md
      - AI Tool Hooks: guides/hooks.md
      - Importing Instructions: guides/import.md
      - Security: guides/security.md
      - User Configuration: guides/user-config.md
      - Examples (Few-Shot): guides/examples.md
      - Policy Engine: guides/policy-engine.md
      - Guard Dependencies: guides/guard-dependencies.md
      - AI Migration Best Practices: guides/ai-migration-best-practices.md
      - Comparison: guides/vs-manual.md
  - API:
      - api-reference/README.md
      - Core: api-reference/core/src/README.md
      - Parser: api-reference/parser/src/README.md
      - Resolver: api-reference/resolver/src/README.md
      - Validator: api-reference/validator/src/README.md
      - Compiler: api-reference/compiler/src/README.md
      - Formatters: api-reference/formatters/src/README.md
      - CLI: api-reference/cli/src/README.md
  - Examples:
      - examples/index.md
      - Minimal: examples/minimal.md
      - Team Setup: examples/team-setup.md
      - Enterprise: examples/enterprise.md
      - Skills & Local: examples/skills-and-local.md
      - Claude Agents: examples/agents.md
  - Testing:
      - testing/index.md
      - Parity Testing: testing/parity-testing.md
      - Feature Coverage: testing/feature-coverage.md
  - Changelog: https://github.com/mrwogu/promptscript/releases