import re


def on_page_markdown(markdown, page, **kwargs):
    """
    parent_snippet markers are snippets that are intended to be replaced in the parent
    site with appropriate snippet notation.  The snippets themselves do not live in
    this repo.

    on_page_* methods are called for each Page in a mkdocs site and can modify the
    markdown they are given as input.  We're using this method to look for the
    parent_includes markers and replace them with a note box that indicates in the
    built docs that this snippet will be replaced in the full docs build.

    For example:
        !!! parent_snippet:'includes/glossary.md'

    will be replaced with:
        !!! note "TO BE REPLACED IN FULL DOCS BUILD
            This snippet will be replaced in the main docs with the parent file 'includes/glossary.md'

    This allows docs imported from other repos (e.g. ehrql) to reference snippets
    in the parent docs, such as the glossary.
    """
    parent_snippets = set(re.findall(r"!!! parent_snippet:.+\n", markdown))
    for parent_snippet in parent_snippets:
        markdown = markdown.replace(
            parent_snippet,
            '\n\n!!! note "TO BE REPLACED IN FULL DOCS BUILD"\n\n\tThis snippet will be replaced in the main docs '
            f"with the parent file {parent_snippet.lstrip('!!! parent_snippet:')}",
        )
    return markdown