mkdocs.yml

# The site is the docs/ tree unmodified: every page stays a Markdown file read on
# GitHub, and MkDocs is only the renderer. The exceptions are the landing page, which
# frames docs/README.md with a hero that only makes sense on a web page, and the header
# menu, which links the sites GitHub's own header cannot.
site_name: OpenSysML
site_description: A SysML v2 and KerML implementation in Go — language server, REPL, execution runtime, and Go, Python, Node, Java and Rust clients
site_url: https://opensysml.org/
repo_url: https://github.com/Open-MBEE/OpenSysML
repo_name: Open-MBEE/OpenSysML
edit_uri: edit/main/docs/
# The affiliation is a span rather than its own line because the footer's copyright is the
# only place the theme lets a site put text; stylesheets/footer.css moves it to the right.
copyright: >-
  Apache-2.0
  <span class="osml-affiliation">part of <a href="https://www.openmbee.org/">Open-MBEE</a>,
  a <a href="https://numfocus.org">NumFOCUS</a> project</span>

docs_dir: docs

theme:
  name: material
  # overrides/ holds the landing page template and the header menu; every documentation
  # page is otherwise the theme as shipped.
  custom_dir: overrides
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.top
    - navigation.indexes
    - content.code.copy
    - content.action.edit
    - search.highlight
    - search.suggest
    - toc.follow
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

extra_css:
  - stylesheets/nav-menu.css
  - stylesheets/footer.css

plugins:
  - search
  # A page published under another name keeps answering there: the site redirects the old
  # URL, and the pointer file left at the old path answers the links GitHub serves.
  - redirects:
      redirect_maps:
        guide/09-python.md: guide/09-clients.md

not_in_nav: |
  guide/09-python.md

# repo_links: links out of docs/ (examples/, Go sources, CONTRIBUTING.md) are correct
# on GitHub and 404 here, so they are rewritten to the repository at build time.
# landing: docs/README.md is rendered with the landing page template.
# header_menu: the header override stays the shipped header plus the menu include.
hooks:
  - scripts/mkdocs_repo_links.py
  - scripts/mkdocs_landing.py
  - scripts/mkdocs_header_menu.py
  - scripts/mkdocs_census.py
  - scripts/mkdocs_suite_figures.py

markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - md_in_html
  - tables
  - toc:
      permalink: true
      # GitHub's own slugger, so an anchor written for a page read on GitHub is
      # the same anchor here and #a--b (a dropped em dash) still resolves.
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

validation:
  nav:
    # A page absent from both nav and not_in_nav fails the build: publishing a
    # page nothing navigates to is the mistake, not an omission.
    omitted_files: warn
    not_found: warn
  links:
    absolute_links: warn
    unrecognized_links: warn
    anchors: warn

# Publish what a user or contributor reads; engineering records under docs/project/
# and staged plans stay in the repository and are read on GitHub.
exclude_docs: |
  API.md
  ARCHITECTURE.md
  MACOS_DISTRIBUTION.md
  QUICKSTART.md
  RDF_INTEROP.md
  RELEASING.md
  SPEC_COMPLIANCE.md
  TRAINING_EXAMPLES.md
  internals/design/**
  internals/notes/**
  project/*.json
  project/omg-issues.md
  project/performance-census-2026-09.md
  project/execution-performance-2026-09.md
  project/performance-profile-2026-09.md
  project/performance-release-0.5-vs-0.4.3.md
  project/performance-release-0.6-vs-0.4.2.md
  project/performance-release-0.8-vs-0.7.0.md
  project/satellite-network-stress-test.md
  project/large-model-scaling-design.md
  project/native-compilation.md
  project/releasing.md
  project/macos-distribution.md
  project/demo.md
  project/training-examples.md
  project/pilot-corpora.md
  project/rdf-corpus-roundtrip.md
  project/pssm-migration.md
  project/pilot-xpect.md
  project/pilot-rejection.md
  project/pilot-execution-referee.md
  project/pssm-referee.md
  project/fuml-referee.md
  project/behavior-semantic-oracle.md
  project/grammar-coverage.md
  project/validation-constraints.md
  project/element-identity-annotations.md
  project/diagram-layout-annotations.md
  project/html-document-backend.md
  project/view-rendering-forms.md
  project/adjudications.md
  project/element-scoped-tier-gating.md
  project/protocol-state-machines.md
  project/lossless-library-records.md
  project/errata-overlay.md
  project/oosem-library.md
  project/mosa-library.md

nav:
  - Documentation: README.md
  - Guide:
      - guide/README.md
      - guide/01-install.md
      - guide/02-first-model.md
      - guide/03-command-line.md
      - guide/04-repl.md
      - guide/05-checking.md
      - guide/06-behavior.md
      - guide/07-saving-and-rdf.md
      - guide/08-editors.md
      - guide/09-clients.md
      - guide/10-troubleshooting.md
      - guide/11-migrating-from-sysml-v1.md
      - guide/modeling-fleets.md
  - Document generation:
      - manual/README.md
      - Introduction and concepts: manual/introduction.md
      - Getting started: manual/getting-started.md
      - Query cookbook: manual/query-cookbook.md
      - Which query is which: manual/query-kinds.md
      - Document authoring: manual/authoring.md
      - Outputs: manual/outputs.md
      - Interfaces: manual/interfaces.md
      - Worked example: manual/worked-example.md
      - Requirements traceability examples: manual/traceability-examples.md
      - Recording analysis runs: manual/recording-analysis-runs.md
      - Running external programs from a model: manual/running-external-programs.md
      - Limitations and troubleshooting: manual/troubleshooting.md
      - Worked example output: manual/examples/observatory.md
      - Requirements example output: manual/examples/requirements.md
      - Traceability example output: manual/examples/traceability.md
      - Traceability tier 1 output: manual/examples/trace-1-basic.md
      - Traceability tier 2 output: manual/examples/trace-2-hierarchy.md
      - Traceability tier 3 output: manual/examples/trace-3-derivation.md
      - Traceability tier 4 output: manual/examples/trace-4-program.md
  - Reference:
      - reference/README.md
      - CLI: reference/cli.md
      - REPL commands: reference/repl-commands.md
      - OSLC Query text: reference/oslc-query.md
      - Environment variables: reference/environment.md
      - External engines: reference/external-engines.md
      - Language server: reference/lsp.md
      - Client libraries: reference/clients.md
      - Go packages: reference/api.md
      - Python API: reference/python-api.md
      - Node API: reference/node-api.md
      - Java API: reference/java-api.md
      - Rust API: reference/rust-api.md
      - Julia API: reference/julia-api.md
      - MATLAB API: reference/matlab-api.md
      - Service transports: reference/service-transports.md
      - Wire contract: reference/wire-contract.md
      - RDF mapping: reference/rdf-mapping.md
      - SysML v1 migration: reference/sysml-v1-migration.md
      - Grammar: reference/grammar/README.md
      - Grammar conformance audit: reference/grammar/conformance-audit.md
  - Internals:
      - internals/README.md
      - Architecture: internals/architecture.md
      - Testing: internals/testing.md
      - Performance: internals/performance.md
      - Execution IR design: internals/execution-ir-design.md
  - Project:
      - project/README.md
      - Spec compliance: project/spec-compliance.md
      - Exact-rational evaluation: project/exact-rational-evaluation.md
      - Expansion regions: project/expansion-regions.md
      - Bitwise complement: project/bitwise-complement.md
      - Exception handlers: project/exception-handlers.md
      - Pilot differential: project/pilot-differential.md
      - Roadmap: project/roadmap.md
      - Nightly snapshots: project/nightly.md