mkdocs.yml

site_name: Spectral Micro
site_description: Documentation for the Spectral Micro BLDC motor controller by Source Robotics.
# Where the site is published: the organisation's docs domain, this repository's path. Search engines take each
# page's address from here, and the sitemap is built from it. mike adds the version under it (/Spectral-BLDC-docs/107/).
site_url: https://docs.source-robotics.com/Spectral-BLDC-docs/
# The docs repository: the "edit this page" target. The header card points at the firmware repository instead
# (extra.repos below, overrides/partials/source.html).
repo_url: https://github.com/Source-Robotics/Spectral-BLDC-docs
repo_name: Source-Robotics/Spectral-BLDC-docs
edit_uri: edit/main/docs/
copyright: |
  &copy; 2026 <a href="https://source-robotics.com" target="_blank" rel="noopener">Source Robotics d.o.o.</a> ·
  Text and images <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="noopener">CC BY-SA 4.0</a> ·
  Code examples <a href="https://github.com/Source-Robotics/Spectral-BLDC-docs/blob/main/LICENSE-CODE" target="_blank" rel="noopener">MIT</a>

theme:
  name: material
  custom_dir: overrides
  logo: assets/logo_new_2.png
  favicon: assets/Icon2.png
  language: en
  font:
    text: Roboto
    code: Roboto Mono
  icon:
    repo: fontawesome/brands/github
    edit: material/pencil
    view: material/eye
  features:
    - navigation.tabs          # one tab per part: Manual, API reference, Guides, Support
    - navigation.tabs.sticky
    - navigation.sections      # the bold sidebar groups
    - navigation.indexes       # a chapter is a folder with its own page
    - navigation.footer        # Previous / Next
    - navigation.top
    - navigation.path
    - toc.follow
    - search.suggest
    - search.highlight
    - search.share
    - content.tabs.link
    - content.code.copy
    - content.code.annotate
    - content.action.view
    - content.action.edit
    - content.tooltips          # title="..." on links and abbreviations become tooltips
    - content.footnote.tooltips
  palette:                      # the same as the PAR6 docs
    - scheme: slate            # dark by default
      primary: black
      accent: green
      toggle:
        icon: material/weather-night
        name: Switch to light mode
    - scheme: default
      primary: black
      accent: green
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode

plugins:
  - search
  - glightbox                 # click any image to zoom
  - social:
      cards_layout: default
      enabled: !ENV [ENABLE_SOCIAL, false]   # social cards only in CI (ENABLE_SOCIAL=true; they need Cairo + Pillow)
  # The addresses of the pages before the manual was restructured (firmware 101) keep working.
  - redirects:
      redirect_maps:
        apage1_specs.md: 03-technical-data/ratings.md
        apage2_getting_started.md: 04-mounting/index.md
        apage3_flashing_firmware.md: 07-firmware/index.md
        apage4_calibration.md: 05-setup/calibration.md
        apage5_PID_tuning.md: 05-setup/tuning.md
        apage6_uart.md: reference/uart/index.md
        apage7_can.md: reference/can/index.md
        apage9_3_tested_motors.md: 03-technical-data/tested-motors.md
        apage9_4_theory_corner.md: appendix/theory.md
        apage9_5_troublestooting.md: 08-troubleshooting.md
        Guides/Mobile robot guide.md: guides/mobile-robot.md
        Guides/Python guide.md: guides/python.md
        Guides/Quadruped guide.md: guides/quadruped.md
        Guides/Gravity compensation guide.md: guides/gravity-compensation.md
        Guides/Bilateral teleoperation guide.md: guides/bilateral-teleoperation.md
        Guides/SIMPLEFOC guide.md: guides/simplefoc.md

# The version facts of versions.yml written into the pages (the version box and the list of documents), and the
# reference pages built from the firmware facts (docs/includes/generated/firmware_facts.json, written by
# tools/sync_firmware.py from the release tag) and the hand-written command descriptions (docs/includes/*.yml).
hooks:
  - hooks/versions.py
  - hooks/firmware_pages.py

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - tables
  - def_list
  - footnotes
  - abbr
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.snippets:
      base_path:
        - docs/includes
      check_paths: true
      auto_append:
        - abbreviations.md    # site-wide abbreviations -> tooltips on every page
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.smartsymbols

extra:
  # The version selector in the header (built by mike: one entry per published firmware release + "latest").
  version:
    provider: mike
    default: latest
    alias: true
  # The header's repository card per section (overrides/partials/source.html): page-URL prefix -> repository.
  # A longer prefix listed later overrides a shorter one listed earlier.
  repos:
    - prefix: ""
      name: Source-Robotics/Spectral-Micro-BLDC-controller
      url: https://github.com/Source-Robotics/Spectral-Micro-BLDC-controller
    - prefix: guides/
      name: Source-Robotics/Spectral-BLDC-Python
      url: https://github.com/Source-Robotics/Spectral-BLDC-Python
    - prefix: reference/python/
      name: Source-Robotics/Spectral-BLDC-Python
      url: https://github.com/Source-Robotics/Spectral-BLDC-Python
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/Source-Robotics
    - icon: fontawesome/brands/instagram
      link: https://www.instagram.com/5arcrnjak/
    - icon: fontawesome/brands/x-twitter
      link: https://twitter.com/SourceRobotics
    - icon: fontawesome/brands/linkedin
      link: https://www.linkedin.com/in/petar-crnjak-009b43180/
    - icon: fontawesome/brands/discord
      link: https://discord.gg/prjUvjmGpZ
    - icon: fontawesome/brands/patreon
      link: https://www.patreon.com/PCrnjak
  # Page status markers (front matter `status: ...`) shown as an icon in the sidebar.
  status:
    new: Recently added
    deprecated: Deprecated
    draft: Not written yet

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js   # sortable tables (click a header)
  - javascripts/tablesort.js

exclude_docs: |
  includes/

validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn

nav:
  - Spectral Micro Manual:
      - index.md
      - Before you start:
          - Quick start: quick-start.md
          - About this manual: about.md
      - Chapters:
          - 1. Overview:
              - 01-overview/index.md
              - The driver at a glance: 01-overview/driver-at-a-glance.md
              - Spectral Micro and STEPFOC: 01-overview/spectral-and-stepfoc.md
              - What you need: 01-overview/what-you-need.md
          - 2. Safety: 02-safety.md
          - 3. Technical data:
              - 03-technical-data/index.md
              - Ratings and limits: 03-technical-data/ratings.md
              - Connectors and pinout: 03-technical-data/connectors.md
              - Dimensions and CAD: 03-technical-data/dimensions.md
              - Tested motors: 03-technical-data/tested-motors.md
          - 4. Mounting and wiring:
              - 04-mounting/index.md
              - The encoder magnet: 04-mounting/magnet.md
              - Mounting on the motor: 04-mounting/mounting.md
              - Wiring the motor: 04-mounting/wiring.md
              - Power and the CAN daisy chain: 04-mounting/power-and-can.md
              - Thermistor: 04-mounting/thermistor.md
          - 5. First setup:
              - 05-setup/index.md
              - Motor GUI: 05-setup/motor-gui.md
              - The serial terminal: 05-setup/terminal.md
              - Calibration: 05-setup/calibration.md
              - Current limit and loop tuning: 05-setup/tuning.md
              - Saving the configuration: 05-setup/saving.md
          - 6. Operation:
              - 06-operation/index.md
              - Control modes: 06-operation/modes.md
              - Over UART: 06-operation/uart.md
              - Over CAN: 06-operation/can.md
              - With Python: 06-operation/python.md
              - Working in Motor GUI: 06-operation/motor-gui.md
              - Errors and recovery: 06-operation/errors.md
              - Gripper mode: 06-operation/gripper-mode.md
          - 7. Firmware:
              - 07-firmware/index.md
              - Releases and versions: 07-firmware/releases.md
              - The bootloader: 07-firmware/the-bootloader.md
              - Updating through the bootloader: 07-firmware/update.md
              - Installing the bootloader on an older board: 07-firmware/bootloader.md
              - Building from source: 07-firmware/building.md
          - 8. Troubleshooting: 08-troubleshooting.md
      - Appendix:
          - Firmware release notes: appendix/firmware-release-notes.md
          - Versions and compatibility: appendix/compatibility.md
          - Hardware revisions: appendix/hardware-revisions.md
          - Theory corner: appendix/theory.md
      - Resources:
          - Glossary: terminology.md
          - CAD and downloads: cad-files.md

  - API reference:
      - reference/index.md
      - CAN messages:
          - reference/can/index.md
          - Motion: reference/can/motion.md
          - Gains and limits: reference/can/gains-and-limits.md
          - Status requests: reference/can/status.md
          - System: reference/can/system.md
          - Gripper: reference/can/gripper.md
      - UART commands:
          - reference/uart/index.md
          - Motion: reference/uart/motion.md
          - Gains and limits: reference/uart/gains.md
          - Calibration and motor parameters: reference/uart/calibration.md
          - Status and utility: reference/uart/utility.md
          - Gripper: reference/uart/gripper.md
      - Defaults: reference/defaults.md
      - Errors and LED states: reference/errors.md
      - Python library: reference/python.md

  - Guides:
      - guides/index.md
      - Python: guides/python.md
      - Mobile robot: guides/mobile-robot.md
      - Quadruped leg: guides/quadruped.md
      - Gravity compensation: guides/gravity-compensation.md
      - Bilateral teleoperation: guides/bilateral-teleoperation.md
      - SimpleFOC: guides/simplefoc.md

  - Support:
      - Getting help: support/index.md
      - Report a problem: support/report-a-problem.md
      - Contributing: support/contributing.md