references ¤

def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802 (casing: parent method's name)
    """Register the extension.

    Add an instance of our [`AutorefsInlineProcessor`][mkdocs_autorefs.references.AutorefsInlineProcessor] to the Markdown parser.
    Also optionally add an instance of our [`AnchorScannerTreeProcessor`][mkdocs_autorefs.references.AnchorScannerTreeProcessor]
    to the Markdown parser if a reference to the autorefs plugin was passed to this extension.

    Arguments:
        md: A `markdown.Markdown` instance.
    """
    md.inlinePatterns.register(
        AutorefsInlineProcessor(md),
        AutorefsInlineProcessor.name,
        priority=168,  # Right after markdown.inlinepatterns.ReferenceInlineProcessor
    )
    if self.plugin is not None and self.plugin.scan_toc and "attr_list" in md.treeprocessors:
        _log_enabling_markdown_anchors()
        md.treeprocessors.register(
            AnchorScannerTreeProcessor(self.plugin, md),
            AnchorScannerTreeProcessor.name,
            priority=0,
        )

@abstractmethod
def expand_identifier(self, identifier: str) -> str:
    """Expand an identifier in a given context.

    Parameters:
        identifier: The identifier to expand.

    Returns:
        The expanded identifier.
    """
    raise NotImplementedError

@abstractmethod
def get_context(self) -> AutorefsHookInterface.Context:
    """Get the current context.

    Returns:
        The current context.
    """
    raise NotImplementedError

def evalId(self, data: str, index: int, text: str) -> tuple[str | None, int, bool]:  # noqa: N802 (parent's casing)
    """Evaluate the id portion of `[ref][id]`.

    If `[ref][]` use `[ref]`.

    Arguments:
        data: The data to evaluate.
        index: The starting position.
        text: The text to use when no identifier.

    Returns:
        A tuple containing the identifier, its end position, and whether it matched.
    """
    m = self.RE_LINK.match(data, pos=index)
    if not m:
        return None, index, False

    identifier = m.group(1)
    if not identifier:
        identifier = text
        # Allow the entire content to be one placeholder, with the intent of catching things like [`Foo`][].
        # It doesn't catch [*Foo*][] though, just due to the priority order.
        # https://github.com/Python-Markdown/markdown/blob/1858c1b601ead62ed49646ae0d99298f41b1a271/markdown/inlinepatterns.py#L78
        if match := INLINE_PLACEHOLDER_RE.fullmatch(identifier):
            stashed_nodes: dict[str, Element | str] = self.md.treeprocessors["inline"].stashed_nodes  # type: ignore[attr-defined]
            el = stashed_nodes.get(match[1])
            if isinstance(el, Element) and el.tag == "code":
                identifier = "".join(el.itertext())
                # Special case: allow pymdownx.inlinehilite raw <code> snippets but strip them back to unhighlighted.
                if match := HTML_PLACEHOLDER_RE.fullmatch(identifier):
                    stash_index = int(match.group(1))
                    html = self.md.htmlStash.rawHtmlBlocks[stash_index]
                    identifier = markupsafe.Markup(html).striptags()
                    self.md.htmlStash.rawHtmlBlocks[stash_index] = escape(identifier)

    end = m.end(0)
    return identifier, end, True

def handleMatch(self, m: Match[str], data: str) -> tuple[Element | None, int | None, int | None]:  # type: ignore[override]  # noqa: N802
    """Handle an element that matched.

    Arguments:
        m: The match object.
        data: The matched data.

    Returns:
        A new element or a tuple.
    """
    text, index, handled = self.getText(data, m.end(0))
    if not handled:
        return None, None, None

    identifier, end, handled = self.evalId(data, index, text)
    if not handled or identifier is None:
        return None, None, None

    if re.search(r"[\x00-\x1f]", identifier):
        # Do nothing if the matched reference contains control characters (from 0 to 31 included).
        # Specifically `\x01` is used by Python-Markdown HTML stash when there's inline formatting,
        # but references with Markdown formatting are not possible anyway.
        return None, m.start(0), end

    return self._make_tag(identifier, text), m.start(0), end