✅ SEP 45: Transclusion of documents

def insertSubstitutions():
    if verbosity > 1:
        print("Performing substitutions")
    transclusion_count = 0
    transclusion_list = []
    for key, page in data.items():
        text = page["plaintext"]
        # Replace instances of {{ site.pagecount }} and {{ site.wordcount }}
        # accordingly. This is a bodge
        text = text.replace("{{ site.pagecount }}", str(site["pagecount"]))
        text = text.replace("{{ site.wordcount }}", "{:,}".format(site["wordcount"]))
        # Replace UUID document references in the source text
        # See "SEP: Address documents by their URN/UUID" for the rationale
        # Summary: Documents can be referenced from within other documents using
        #   their unique ID (UUIDv4), or an 8 digit prefix of that ID. The
        #   below code searches for markdown style links that contain a
        #   linktarget beginning with '!'. A lookup is performed to match that
        #   UID (or partial) UID with a document from which the slug and the
        #   title of that document can be discovered. This information is then
        #   used to replace the link with one that now points to the public URL
        #   of the document instead of the UID. This substitution is performed
        #   on plaintext so that both the plaintext and HTML documents reflect
        #   the authors intent.
        #
        #
        # Find all valid UUID reference links, eg:
        # UUID_REF_RE = re.compile(r"\[([^\]]*)\]\((![^)]+)\)")
        UUID_REF_RE = re.compile(r"\[([^\]]*?)\]\((.*?::)([^)]+)\)")
        inref_links = list(UUID_REF_RE.findall(text))
        # Process each match
        for linktext_match, inref_type, inref_match in inref_links:
            match = f"[{linktext_match}]({inref_type}{inref_match})"
            if inref_type in ["/2024/07/25/11-22-45_E.jpg", "in::"]:
                inref_uuid = ""
                for k in data:
                    if k.startswith(inref_match):
                        inref_uuid = k
            else:
                raise Exception(
                    f"Unexpected Internal Reference type '{inref_type}' in document:\
                                {key}\n    match: {match}"
                )

            # If no matching UUID found for reference, raise Exception
            if inref_uuid == "":
                raise Exception(
                    f"\nUnmatched UUID reference:\n"
                    f"  document: {key}\n"
                    f"  {inref_match} does not reference an existing document"
                )

            # If linktext is blank OR begins with a ':' lookup the title of
            # the linked document. If linktext is not blank AND does NOT begin
            # with a ':' leave it as is.
            if linktext_match.startswith("::") or linktext_match == "":
                linktext = data[inref_uuid]["title"]
            else:
                linktext = linktext_match
            # Lookup slug of linked document
            linktarget = f"/{data[inref_uuid]['slug']}"
            if inref_type == "/2024/07/25/11-22-45_E.jpg":
                # Assemble payload
                replacement = f"[{linktext}]({linktarget})"
                # Find and replace the original link with the updated one
                text = text.replace(match, replacement)

            elif inref_type == "in::":
                transclude_data = {
                    "insrc_uuid": key,
                    "insrc_match": match,
                    "inref_uuid": inref_uuid,
                    "inref_linktext": linktext,
                    "inref_linktarget": linktarget,
                }
                transclusion_list.append(transclude_data)

        # Write modified plaintext back to document variable once all
        # substitutions have been carried out.
        page["plaintext"] = text

        # Carry out transclusions (these must occur after all other link references to ensure such links are present in transcludes elements)
        for transclude in transclusion_list:
            insrc_uuid = transclude["insrc_uuid"]
            insrc_match = transclude["insrc_match"]
            inref_uuid = transclude["inref_uuid"]
            inref_transclude = markdown(data[inref_uuid]["plaintext"])
            linktext = transclude["inref_linktext"]
            linktarget = transclude["inref_linktarget"]
            # Assemble payload
            replacement = f'<figure class="transclusion"><p>{inref_transclude}</p><figcaption> <em>from</em> <a href="{linktarget}">{linktext}</a></figcaption></figure>'
            # Find and replace the original link with the assembled transclusion
            data[insrc_uuid]["plaintext"] = data[insrc_uuid]["plaintext"].replace(
                insrc_match, replacement
            )