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 landing page is the exception: it
# frames docs/README.md with a hero that only makes sense on a web page.
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/develop/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 sidebar navigation (the
  # shipped partial minus tab-mode hiding of inactive top-level items); every
  # documentation page is otherwise the theme as shipped.
  custom_dir: overrides
  logo: assets/opensysml-mark-white.png
  favicon: assets/favicon.png
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.top
    - navigation.indexes
    - navigation.tabs
    - navigation.tabs.sticky
    - 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/footer.css
  - stylesheets/header.css
  - stylesheets/ecosystem.css

extra:
  social:
    - icon: fontawesome/solid/dragon
      link: https://lord.opensysml.org/
      name: Legend of the Red Dragon

extra_javascript:
  - assets/sysml-engine-loader.js

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: clients/python/index.md
        ecosystem.md: README.md
  - mkdocstrings:
      handlers:
        python:
          paths: [client/python]
          options:
            docstring_style: google
            docstring_options:
              warn_missing_types: false
            extensions: [scripts/griffe_sphinx_roles.py]
            show_source: false
            members_order: source
            filters: ["!^_"]
            show_root_heading: true
            show_signature_annotations: true
            separate_signature: true

not_in_nav: |
  guide/09-python.md
  internals/README.md
  internals/architecture.md
  internals/testing.md
  internals/performance.md
  internals/interface-records.md
  internals/execution-ir-design.md
  project/README.md
  project/spec-compliance.md
  project/exact-rational-evaluation.md
  project/expansion-regions.md
  project/bitwise-complement.md
  project/constraint-body-steps.md
  project/exception-handlers.md
  project/pilot-differential.md
  project/spec-pilot-gap-register.md
  project/roadmap.md
  project/nightly.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.
hooks:
  - scripts/mkdocs_repo_links.py
  - scripts/mkdocs_landing.py
  - scripts/mkdocs_census.py
  - scripts/mkdocs_suite_figures.py
  - scripts/mkdocs_install_scripts.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/performance-release-0.9.1-vs-0.9.0.md
  project/satellite-network-stress-test.md
  project/large-model-scaling-design.md
  project/native-compilation.md
  project/releasing.md
  project/mdk-parity.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/sysml-v1-transformation-census.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
  project/statemachines-library.md

nav:
  - Home: README.md
  - CLI: cli.md
  - Documentation: documentation.md
  - Clients:
      - clients.md
      - Python:
          - clients/python/index.md
          - Models and symbols: clients/python/models.md
          - Instances and values: clients/python/instances.md
          - Verification and analysis: clients/python/verification.md
          - Editing and saving: clients/python/editing-and-saving.md
          - Queries and documents: clients/python/queries.md
          - Errors: clients/python/errors.md
          - The service: clients/python/service.md
          - Typed classes: clients/python/typed-classes.md
          - Metamodel classes and JSON: clients/python/metamodel.md
      - Node: clients/node.md
      - Java: clients/java.md
      - Rust: clients/rust.md
      - Julia: clients/julia.md
      - MATLAB: clients/matlab.md
  - Community: community.md
  - Downloads: downloads.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
      - Importing data into a model: manual/importing-data.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
      - Diagnostics (lints): reference/diagnostics.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
      - FMI models: reference/fmi.md
      - Grammar: reference/grammar/README.md
      - Grammar conformance audit: reference/grammar/conformance-audit.md
      - WebAssembly builds: reference/wasm.md
      - Third-party notices: project/third-party-notices.md
  # internals/ and project/ contributor records are kept out of the tab bar; the
  # public third-party notices are the exception.