mkdocs.yml

site_name: IASO
theme:
  name: material
  highlightjs: true
  logo: ./assets/iaso.png
  favicon: ./assets/iaso-favicon.png
  custom_dir: ./docs/overrides # here we need to specify /docs in the path. That's just how it is
  font:
    text: Inter
    code: JetBrains Mono
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-night
        name: Switch to light mode
  features:
    - content.action.edit
    - navigation.tabs # top-level nav (Home/Users/Developers/More about IASO) as tabs instead of one long sidebar
    - navigation.tabs.sticky # tabs stay visible while scrolling
    - navigation.top # "back to top" button
    - toc.integrate # page headings nest under the active page in the LEFT sidebar, no separate right-hand rail
hooks:
  - docs_redirect_hook.py # writes redirects for pages moved by the 2026 pages/ flatten
plugins:
  - i18n:
      languages:
        - locale: en
          name: English
          build: true
          default: true

        - locale: fr
          name: Français
          build: true
          # The nav tree itself lives once in the top-level `nav:` key below.
          # Only the section/link *titles* need a French label here - add an
          # entry whenever you add a new titled section or external link to `nav:`.
          nav_translations:
            Home: Accueil
            Users: Guide d'utilisateur
            Developers: Développeurs
            References: Références
            Models: Modèles
            How to: Guides
            Advanced configuration: Configuration avancée
            IASO and DHIS2: IASO et DHIS2
            More about IASO: En savoir plus sur IASO
            Overview: Aperçu
            IASO website: Demander une démo
            Bluesquare website: Bluesquare

        - locale: es
          name: Español
          build: true
          # Same idea as the French block above: titles only, nav tree is shared.
          nav_translations:
            Home: Inicio
            Users: Guía de usuario
            Developers: Desarrolladores
            References: Referencias
            Models: Modelos
            How to: Guías
            Advanced configuration: Configuración avanzada
            IASO and DHIS2: IASO y DHIS2
            More about IASO: Más sobre IASO
            Overview: Resumen
            IASO website: Sitio web de IASO
            Release notes: Notas de versión
            Bluesquare website: Sitio web de Bluesquare

  - search #built-in search input in the theme
  - mermaid2 #enables rendering mermaid diagrams
  - glightbox #click-to-zoom lightbox for images, so screenshots don't need pre-resizing
  - awesome-pages:
      collapse_single_pages: true # prevents all sub menus to be open by default
  - mkdocstrings:
      handlers:
        # See: https://mkdocstrings.gipip3 thub.io/python/usage/
        python:
          options:
            docstring_style: sphinx
markdown_extensions:
  - attr_list # size/align images: ![…](…){ width="400" } or { .doc-shot align=center }
  - markdown_include.include: # "import" bits of text in yout md file
      base_path: .
  - admonition  # add rst style admonitions to md. Useful when converting old rst docs
  - toc:
      permalink: "#" # adds a link to headers
repo_url: https://github.com/BLSQ/iaso
edit_uri: edit/main/docs # for the edit on github button
extra_css:
  - ./stylesheets/extra.css
extra_javascript:
  - ./extrajs/external_links.js
  - https://plausible.io/js/script.js
use_directory_urls: false # IMPORTANT: without this the paths to pictures will break on build
nav: # nav configures the side bar menu - this is the ONLY place the nav tree is defined.
  # French/Spanish titles for these same sections/links live in the `nav_translations`
  # blocks above - add a page here once, it appears in all 3 languages automatically
  # (mkdocs-static-i18n swaps in the .fr.md/.es.md version of each file for you).
  - Home: index.md
  - Users:
     - ./pages/users/how_to/get_started_with_iaso.md
     - ./pages/users/reference/iaso_concepts.md
     - ./pages/users/reference/iaso_modules.md
     - ./pages/users/reference/user_guide.md
     - ./pages/users/reference/iaso_mobile.md
     - Advanced configuration:
       - IASO and DHIS2:
         - ./pages/users/how_to/setup_dhis2_login_in_iaso.md
         - ./pages/users/how_to/deduce_form_from_another_form.md
       - FAQ: ./pages/users/FAQ/faq.md
  - Developers:
    - References:
      # - Data model glossary:
      - ./pages/dev/reference/data_model_glossary.md
      # - SQL dashboard :
      - ./pages/dev/reference/SQL_Dashboard_feature.md
      - ./pages/dev/reference/docker.md
      - ./pages/dev/reference/background_tasks.md
      - ./pages/dev/reference/env_variables.md
      - ./pages/dev/reference/fhir_api.md
      # - Entities:
      #   - ./pages/dev/reference/entities_in_iaso/entities_in_iaso.md
      # - Front-end:
      #   - ./pages/dev/reference/front-end_reference.md
      # - Audit:
      #   - ./pages/dev/reference/audit.md
      # - Vector control:
      #   - ./pages/dev/reference/vector_control.md
      - Models:
        - ./pages/dev/reference/API/entity.md
    - How to:
      # - Contribute:
      - ./pages/dev/how_to/contribute.md
      # - Set up a dev environment:
      - ./pages/dev/how_to/setup_dev_env.md
      # - Test Enketo public_create_url:
      #   - ./pages/dev/how_to/manually_test_enketo.md
      # - Deploy:
      #   - ./pages/dev/how_to/deploy.md
      # - Use the APIs:
      - ./pages/dev/how_to/use_iaso_apis.md
      # - Run docs locally:
      #   - ./pages/dev/how_to/run_docs_locally.md
      # - Write a visit on an NFC card:
      #   - ./pages/dev/how_to/write_visit_on_nfc.md
      - ./pages/dev/how_to/build_odk_preview.md

  - More about IASO:
    - Overview: ./pages/more_about_iaso.md
    - IASO website: https://www.openiaso.com/
    - Digital Public Goods Registry: https://www.digitalpublicgoods.net/r/iaso
    - Release notes: https://github.com/BLSQ/iaso/releases
    - Bluesquare website: https://www.bluesquarehub.com/