# NOTE: This mkdocs.yml contains the minimum config required to run

# ehrQL's docs locally.  These docs do not run in isolation in production.

#

# In production, the ehrql docs are pulled into and built with the main docs at

# https://github.com/opensafely/documentation

#

# The contents of this mkdocs.yml are ignore in the production build.

#

site_name: OpenSAFELY ehrQL documentation

repo_url: https://github.com/opensafely-core/ehrql

docs_dir: docs

# Dotfiles/dotdirectories and the top-level templates directory

# are implicit entries for exclude_docs.

# https://www.mkdocs.org/user-guide/configuration/#exclude_docs

exclude_docs: |

  /includes/

not_in_nav: |

  /reference/schemas/

validation:

  links:

    unrecognized_links: warn

nav:

  - ehrQL: index.md

  - Tutorial:

    - Tutorial: tutorial/index.md

    - Setting up: tutorial/setting-up/index.md

    - Working with data with ehrQL: tutorial/working-with-data-with-ehrql/index.md

    - Simple transformations: tutorial/simple-transformations/index.md

    - More complex transformations: tutorial/more-complex-transformations/index.md

    - Building a dataset: tutorial/building-a-dataset/index.md

    - Using ehrQL as part of a study: tutorial/using-ehrql-as-part-of-a-study/index.md

    - Quiz: tutorial/quiz/index.md

  - How-to guides:

    - How-to guides: how-to/index.md

    - Using ehrQL to answer specific questions: how-to/examples.md

    - How to include and exclude patients from your study population: how-to/define-population.md

    - Resolving ehrQL errors: how-to/errors.md

    - How to use dummy data in an ehrQL dataset definition: how-to/dummy-data.md

    - How to use dummy data in an ehrQL measures definition: how-to/dummy-measures-data.md

    - How to assign multiple columns to a dataset programmatically: how-to/assign-multiple-columns.md

    - How to work with codelists: how-to/codelists.md

    - How to test your dataset definition: how-to/test-dataset-definition.md

  - Reference:

    - Reference: reference/index.md

    - Language reference: reference/language.md

    - Language features: reference/features.md

    - Backends: reference/backends.md

    - Table schemas: reference/schemas.md

    - Command line interface: reference/cli.md

    - Cheatsheet: reference/cheatsheet.md

    - Upgrading ehrQL from v0 to v1: reference/upgrading-ehrql-from-v0-to-v1.md

  - Explanations:

    - Explanations: explanation/index.md

    - ehrQL backend tables: explanation/backend-tables.md

    - ehrQL output formats: explanation/output-formats.md

    - Using ehrQL in OpenSAFELY projects: explanation/using-ehrql-in-opensafely-projects.md

    - Running ehrQL: explanation/running-ehrql.md

    - Using the measures framework: explanation/measures.md

    - Selecting populations for study: explanation/selecting-populations-for-study.md

    - The OpenSAFELY VS Code extension: explanation/vscode-extension.md

theme:

  name: material

  features:

    - content.action.edit

    - content.code.copy

    - navigation.footer

    - navigation.indexes

extra_css:

  - stylesheets/extra.css

watch:

  - docs

# WARNING!

# This markdown_extensions config (with the exception of the snippets base_path) is duplicated

# from the mkdocs.yml in the parent repo (https://github.com/opensafely/documentation) in order

# to build local docs with similar styling. If any changes/additions are needed, ensure they are

# made in the parent repo also.

markdown_extensions:

  - pymdownx.details

  - pymdownx.snippets:

      check_paths: true

      base_path: docs

  - pymdownx.superfences:

      custom_fences:

        - name: mermaid

          class: mermaid

          format: !!python/name:pymdownx.superfences.fence_code_format

  - toc:

      permalink: "🔗"

  - pymdownx.highlight:

      extend_pygments_lang:

        - name: ehrql

          lang: python

  - pymdownx.tabbed:

      alternate_style: true

  - pymdownx.keys

  - admonition

  - footnotes

  - abbr

  - md_in_html

  - attr_list

  - pymdownx.emoji:

      emoji_index: !!python/name:material.extensions.emoji.twemoji

      emoji_generator: !!python/name:material.extensions.emoji.to_svg

# This hook adds some clarifying studying around snippets that will be incorporated

# from the parent repo, and is relevant for local development only.

hooks:

  - hooks/parent_snippets.py