mkdocs.yml

# SPDX-FileCopyrightText: Copyright (C) 2022 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
#
# SPDX-License-Identifier: MIT

# Project information
#
site_name: Opal Documentation
site_url: https://docs.opalmedapps.com
site_author: Opal Health Informatics Group (O-HIG)

# Repository
# https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/
repo_name: opalmedapps/docs
repo_url: https://github.com/opalmedapps/docs
edit_uri: edit/main/docs/

# Copyright
copyright: Copyright &copy; Opal Health Informatics Group (O-HIG)

# Content
nav:
  - Home: index.md
  - User Guide:
    - user/index.md
    - Opal:
      - user/opal/index.md
      - Opal Admin:
        - user/opal/opaladmin/index.md
    - OpenEMR:
      - Adding a document: user/openemr/document/add_document.md
      - Adding a diagnosis: user/openemr/diagnosis/add_diagnosis.md
      - Adding and updating patients: user/openemr/patient/add_update_patient.md
      - Adding a provider: user/openemr/provider/add_provider.md
      - Scheduling appointments: user/openemr/appointment/schedule_appointment.md
  - Contribute:
    - development/index.md
    - Architecture:
      - development/architecture/index.md
      - Decisions: development/architecture/decisions/
      - development/architecture/migration.md
      - Registration Process: development/architecture/registration.md
      - development/architecture/checkin_process.md
    - Set up a Local Development Environment: development/local-dev-setup.md
    - Best Practices:
      - Overview: development/best_practices/best_practices.md
      - Code Review: development/best_practices/code_review.md
      - Diagrams: development/best_practices/diagrams.md
    - Guides:
      - Languages and Tools:
          - Docker: development/guides/docker.md
          - Python: development/guides/python.md
          - JavaScript: development/guides/javascript.md
      - Sequence Diagrams: development/guides/sequence_diagrams.md
      - Generate Self Signed Certificates: development/guides/self_signed_certificates.md
  - Install:
    - Deploying the Opal Solution: install/index.md
    - Firebase project setup: install/firebase-project-setup.md
    - Hospital Integration: install/integration.md

# Configuration
theme:
  name: material
  # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#system-preference
  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: black
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

  font:
    text: Roboto
    code: Roboto Mono
  language: en
  icon:
    logo: material/book-open-page-variant
  # https://squidfunk.github.io/mkdocs-material/setup/
  features:
    - content.action.edit
    - content.action.view
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.indexes
    - toc.follow
    - search.highlight
    - content.code.copy

extra_css:
  - assets/stylesheets/extra.css

# Plugins
# https://squidfunk.github.io/mkdocs-material/plugins/
plugins:
  - search
  # show last updated date at the bottom of each page
  # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#document-dates
  - git-revision-date-localized:
      enable_creation_date: true
      # https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/
      type: timeago
      # only enable when building in CI to speed up local builds
      # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#+git-revision-date-localized.enabled
      enabled: !ENV [CI, false]
  # https://squidfunk.github.io/mkdocs-material/reference/images/?h=image#lightbox
  - glightbox
  - macros:
      on_error_fail: true
      on_undefined: strict
      modules:
        # https://github.com/febus982/mkdocs-macros-adr-summary
        - mkdocs_macros_adr_summary
  - gen-files:
      scripts:
        - docs/gen_adrs_nav.py
  - literate-nav:
      nav_file: SUMMARY.md
  # keep assets private
  # https://squidfunk.github.io/mkdocs-material/plugins/privacy/
  - privacy:
      enabled: !ENV [CI, false]
  # https://github.com/manuzhang/mkdocs-htmlproofer-plugin#configuring
  - htmlproofer:
      # check all URLs before raising an error
      raise_error_after_finish: True
      raise_error_excludes:
        # some URLs sporadically return a 504 (Gateway Timeout)
        504: ["*"]
        # sometimes URLs return a 429 (Too Many Requests)
        429: ["*"]
      skip_downloads: True
      ignore_urls:
        # PlantUML diagrams are included as data
        - "data:*"
        # Keeps failing for some reason
        - https://app.opalmedapps.ca
        # Twitter URL sometimes returns a 404
        - https://x.com/i_a_r_n_a/status/623922369376202758
        # all below use Cloudflare which returns a captcha first with a 403
        - https://towardsdatascience.com/type-hints-in-python-everything-you-need-to-know-in-5-minutes-24e0bad06d0b
        - https://www.npmjs.com/package/*
        - https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511
      # only enable when building in CI to speed up local builds
      enabled: !ENV [CI, false]

# Extensions
markdown_extensions:
  # Python Markdown
  # https://python-markdown.github.io/extensions/
  #
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#abbreviations
  - abbr
  - admonition
  - def_list
  - footnotes
  # enable HTML in Markdown for image captions
  # https://squidfunk.github.io/mkdocs-material/reference/images/
  # https://squidfunk.github.io/mkdocs-material/reference/images/#image-captions
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html
  - md_in_html
  - attr_list
  - tables
  - toc:
      permalink: true

  # PyMdown Extensions
  # https://facelessuser.github.io/pymdown-extensions/
  #
  - pymdownx.betterem
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  # Code Blocks
  # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.keys
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
  # https://github.com/mikitex70/plantuml-markdown
  - plantuml_markdown:
      servers:
        # use Kroki server due to CloudFlare errors in CI with PlantUML.com
        - url: https://kroki.io/plantuml
          kroki: true
      # don't generate image maps due to issues with Kroki and PlantUML
      image_maps: false
      # use caching to speed up live-reloading
      cachedir: .cache/.plantuml/


# https://www.mkdocs.org/user-guide/configuration/#validation
validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

strict: true

watch:
  - overrides