# links

URL: /patitas/api/parsing/inline/links/
Section: inline
Description: Link and image parsing for Patitas parser.

Handles inline links, reference links, images, and footnote references.

CommonMark 0.31.2 compliance:
- Link destinations can be angle-bracket delimited or raw
- Angle-bracket destinations: no newlines, can have spaces
- Raw destinations: no spaces, no control chars, balanced parens
- Backslash escapes work in destinations and titles

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/parsing/inline/links/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Finline%2Flinks%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Finline%2Flinks%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Finline%2Flinks%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Finline%2Flinks%2Findex.txt)

Module

#
`parsing.inline.links`

Link and image parsing for Patitas parser.

Handles inline links, reference links, images, and footnote references.

CommonMark 0.31.2 compliance:

- Link destinations can be angle-bracket delimited or raw

- Angle-bracket destinations: no newlines, can have spaces

- Raw destinations: no spaces, no control chars, balanced parens

- Backslash escapes work in destinations and titles

1Class10Functions

## Classes

`LinkParsingMixin`

5

▼

Mixin for link and image parsing.

Required Host Attributes:
- _link_refs: dict[str, tuple[str,…

Mixin for link and image parsing.

Required Host Attributes:

- _link_refs: dict[str, tuple[str, str]]

Required Host Methods:

- _parse_inline(text, location) -> tuple[Inline, ...]

#### Attributes

Name
Type
Description

`_link_refs`

`dict[str, tuple[str, str]]`

—

#### Methods

Internal Methods
4

▼

`_parse_inline`

2

`tuple[Inline, ...]`

▼

Parse inline content. Implemented by InlineParsingCoreMixin.

`def _parse_inline(self, text: str, location: SourceLocation) -> tuple[Inline, ...]`

##### Parameters

Name
Type
Description

`text`
`—`

`location`
`—`

##### Returns

`tuple[Inline, ...]`

`_try_parse_footnote_ref`

3

`tuple[FootnoteRef (/patitas/api/nodes/#FootnoteRef), int] …`

▼

Try to parse a footnote reference at position.

Format: [^identifier]
Returns (…

`def _try_parse_footnote_ref(self, text: str, pos: int, location: SourceLocation) -> tuple[FootnoteRef, int] | None`

Try to parse a footnote reference at position.

Format: [^identifier]
Returns (FootnoteRef, new_position) or None if not a footnote ref.

##### Parameters

Name
Type
Description

`text`
`—`

`pos`
`—`

`location`
`—`

##### Returns

`tuple[FootnoteRef (/patitas/api/nodes/#FootnoteRef), int] | None`

`_try_parse_link`

4

`tuple[Link (/patitas/api/nodes/#Link), int] | None`

▼

Try to parse a link at position.

Handles:
- [text](url) - inline link
- [text]…

`def _try_parse_link(self, text: str, pos: int, location: SourceLocation, last_bracket: int | None = None) -> tuple[Link, int] | None`

Try to parse a link at position.

Handles:

- text (url) - inline link

- [text][ref] - full reference link

- [text][] - collapsed reference link

- [ref] - shortcut reference link

Returns (Link, new_position) or None if not a link.

##### Parameters

Name
Type
Description

`text`
`—`

`pos`
`—`

`location`
`—`

`last_bracket`
`—`

Default:`None`

##### Returns

`tuple[Link (/patitas/api/nodes/#Link), int] | None`

`_try_parse_image`

4

`tuple[Image (/patitas/api/nodes/#Image), int] | None`

▼

Try to parse an image at position.

Handles:
- ![alt](url) - inline image
- ![a…

`def _try_parse_image(self, text: str, pos: int, location: SourceLocation, last_bracket: int | None = None) -> tuple[Image, int] | None`

Try to parse an image at position.

Handles:

- - inline image

- ![alt][ref] - full reference image

- ![alt][] - collapsed reference image

- ![alt] - shortcut reference image

Returns (Image, new_position) or None if not an image.

##### Parameters

Name
Type
Description

`text`
`—`

`pos`
`—`

`location`
`—`

`last_bracket`
`—`

Default:`None`

##### Returns

`tuple[Image (/patitas/api/nodes/#Image), int] | None`

## Functions

`_process_escapes`

1

`str`

▼

Process backslash escapes in link URLs and titles.

CommonMark: Backslash escap…

`def _process_escapes(text: str) -> str`

Process backslash escapes in link URLs and titles.

CommonMark: Backslash escapes work in link destinations and titles.
A backslash followed by ASCII punctuation is replaced with the literal char.

##### Parameters

Name
Type
Description

`text`
`str`

Raw text that may contain backslash escapes

##### Returns

`str`

`_unescape_label`

1

`str`

▼

Unescape label-specific escapes (backslash, [, ]).

CommonMark: Backslash escap…

`def _unescape_label(label: str) -> str`

Unescape label-specific escapes (backslash, [, ]).

CommonMark: Backslash escapes are allowed in labels but only matter for
backslash and bracket characters. Other escapes remain literal so that
labels like`[foo\!]` do not match `[foo!]`(spec example 545).

##### Parameters

Name
Type
Description

`label`
`str`

##### Returns

`str`

`_normalize_label`

1

`str`

▼

Normalize a link reference label for matching.

CommonMark 4.7: "Label matching…

`def _normalize_label(label: str) -> str`

Normalize a link reference label for matching.

CommonMark 4.7: "Label matching is case-insensitive and Unicode case fold
equivalent. Spaces, tabs, and line endings are normalized to single space."

##### Parameters

Name
Type
Description

`label`
`str`

Raw label text

##### Returns

`str`

`_parse_link_destination`

2

`tuple[str, int] | None`

▼

Parse a link destination starting at pos.

CommonMark 6.5: Link destination is …

`def _parse_link_destination(text: str, pos: int) -> tuple[str, int] | None`

Parse a link destination starting at pos.

CommonMark 6.5: Link destination is either:

- Angle-bracket delimited: (can contain spaces, no newlines or unescaped </>)

- Raw URL: sequence of non-space chars with balanced parens

##### Parameters

Name
Type
Description

`text`
`str`

The full text being parsed

`pos`
`int`

Position after the opening (

##### Returns

`tuple[str, int] | None`

`_parse_link_title`

2

`tuple[str | None, int]`

▼

Parse an optional link title starting at pos.

CommonMark: Title is enclosed in…

`def _parse_link_title(text: str, pos: int) -> tuple[str | None, int]`

Parse an optional link title starting at pos.

CommonMark: Title is enclosed in ", ', or ()
Can span lines but opening/closing delimiters must match.

##### Parameters

Name
Type
Description

`text`
`str`

The full text being parsed

`pos`
`int`

Position to start looking for title

##### Returns

`tuple[str | None, int]`

`_parse_inline_link`

2

`tuple[str, str | None, i…`

▼

Parse an inline link destination and optional title.

Format: (url) or (url "ti…

`def _parse_inline_link(text: str, pos: int) -> tuple[str, str | None, int] | None`

Parse an inline link destination and optional title.

Format: (url) or (url "title") or ( 'title')

##### Parameters

Name
Type
Description

`text`
`str`

Full text being parsed

`pos`
`int`

Position at the opening (

##### Returns

`tuple[str, str | None, int] | None`

`_skip_html_tag`

2

`int`

▼

Skip over an HTML tag starting at pos.

Handles open tags, close tags, and self…

`def _skip_html_tag(text: str, pos: int) -> int`

Skip over an HTML tag starting at pos.

Handles open tags, close tags, and self-closing tags.
Properly handles quoted attribute values that may contain special chars.

##### Parameters

Name
Type
Description

`text`
`str`

Full text to search

`pos`
`int`

Position at the opening <

##### Returns

`int`

`_find_closing_bracket`

3

`int`

▼

Find closing bracket ] while respecting code spans, HTML tags, and nested brack…

`def _find_closing_bracket(text: str, start: int, last_bracket: int | None = None) -> int`

Find closing bracket ] while respecting code spans, HTML tags, and nested brackets.

CommonMark: Code spans have higher precedence than link text brackets.
A code span inside link text means the ] inside the code span doesn't count.
HTML tags protect their contents - ] inside HTML attribute values doesn't count.
Nested brackets [ ] are allowed inside link text.

##### Parameters

Name
Type
Description

`text`
`str`

Full text to search

`start`
`int`

Position to start searching (should be after opening [)

`last_bracket`
`int | None`

Precomputed index of the last`]` in `text` (`text.rfind("]")`), or `None` if unknown. The presence of any `]` at/after a position is monotonic, so when `start` is past the last `]` there cannot be a closing bracket and we return `-1`in O(1). Passing this in (computed once per inline text) keeps the overall closing-bracket search amortized O(n) instead of O(n^2).

Default:`None`

##### Returns

`int`

`_extract_plain_text`

1

`str`

▼

Extract plain text from inline content for image alt text.

CommonMark: Image a…

`def _extract_plain_text(text: str) -> str`

Extract plain text from inline content for image alt text.

CommonMark: Image alt text is the plain text content with formatting stripped.
E.g., "foo bar" becomes "foo bar".

##### Parameters

Name
Type
Description

`text`
`str`

Raw inline content that may contain formatting

##### Returns

`str`

`_contains_link`

1

`bool`

▼

Check if children contain a Link node at any nesting level.

CommonMark: Links …

`def _contains_link(children: tuple[object, ...]) -> bool`

Check if children contain a Link node at any nesting level.

CommonMark: Links may not contain other links, at any level of nesting.
If parsing link text produces a link, the outer link is invalid.

##### Parameters

Name
Type
Description

`children`
`tuple[object, ...]`

Tuple of inline nodes

##### Returns

`bool`