# `scripts.mkdocs_hooks`

MkDocs hooks that publish machine-readable documentation artifacts.

[View the complete module source at #L1-L225](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L1-L225).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: scripts.mkdocs_hooks
    options:
      members:
        - SOURCE_BRANCH_URL
        - _source_revision
        - _pin_source_links
        - on_page_markdown
        - on_post_page
        - _markdown_documents
        - on_post_build
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-scripts.mkdocs_hooks._source_revision" markdown="1">
<summary><code>scripts.mkdocs_hooks._source_revision</code> · function</summary>

```python
scripts.mkdocs_hooks._source_revision() -> str
```

Return the immutable commit represented by this documentation build.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `str`
- Direct return expressions: `candidate.lower()`; `revision`

**Exceptions and behavior**

Function `_source_revision` calls `os.environ.get`, `re.fullmatch`, `candidate.lower`, `subprocess.run`; can raise `ValueError`; has 2 explicit return paths.
Directly raised exceptions: `ValueError`.

[View source #L27-L46](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L27-L46).

</details>

<details class="api-contract" id="contract-scripts.mkdocs_hooks._pin_source_links" markdown="1">
<summary><code>scripts.mkdocs_hooks._pin_source_links</code> · function</summary>

```python
scripts.mkdocs_hooks._pin_source_links(text: str, revision: str) -> str
```

Replace mutable gh-pages source links with one commit permalink.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Required positional or keyword input. |
| `revision` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `text.replace(SOURCE_BRANCH_URL, f'https://github.com/waybarrios/vllm-mlx/blob/{revision}/')`

**Exceptions and behavior**

Function `_pin_source_links` calls `text.replace`; returns `text.replace(SOURCE_BRANCH_URL, f'https://github.com/waybarrios/vllm-mlx/blob/{revision}/')`.
No direct `raise` statement appears in this definition.

[View source #L49-L55](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L49-L55).

</details>

<details class="api-contract" id="contract-scripts.mkdocs_hooks.on_page_markdown" markdown="1">
<summary><code>scripts.mkdocs_hooks.on_page_markdown</code> · function</summary>

```python
scripts.mkdocs_hooks.on_page_markdown(markdown: str, **kwargs) -> str
```

Pin every rendered GitHub source link to the build commit.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `markdown` | `str` | `yes` | `none` | Required positional or keyword input. |
| `**kwargs` | `not annotated` | `no` | `none` | Additional variadic keyword inputs accepted by this callable. |

**Returns**

- Type: `str`
- Direct return expressions: `_pin_source_links(markdown, _source_revision())`

**Exceptions and behavior**

Function `on_page_markdown` calls `_pin_source_links`, `_source_revision`; returns `_pin_source_links(markdown, _source_revision())`.
No direct `raise` statement appears in this definition.

[View source #L58-L62](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L58-L62).

</details>

<details class="api-contract" id="contract-scripts.mkdocs_hooks.on_post_page" markdown="1">
<summary><code>scripts.mkdocs_hooks.on_post_page</code> · function</summary>

```python
scripts.mkdocs_hooks.on_post_page(output: str, page = None, **kwargs) -> str
```

Normalize search alternates and localized homepage presentation.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `output` | `str` | `yes` | `none` | Required positional or keyword input. |
| `page` | `not annotated` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `**kwargs` | `not annotated` | `no` | `none` | Additional variadic keyword inputs accepted by this callable. |

**Returns**

- Type: `str`
- Direct return expressions: `output`; `re.sub('\\s*<a\\b(?=[^>]*\\brel=\\"edit\\")[^>]*>.*?</a>', '', output, count=1, flags=re.DOTALL)`

**Exceptions and behavior**

Function `on_post_page` calls `getattr`, `re.sub`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L65-L89](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L65-L89).

</details>

<details class="api-contract" id="contract-scripts.mkdocs_hooks._markdown_documents" markdown="1">
<summary><code>scripts.mkdocs_hooks._markdown_documents</code> · function</summary>

```python
scripts.mkdocs_hooks._markdown_documents() -> list[Path]
```

Return tracked hand-written documentation pages in stable order.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `list[Path]`
- Direct return expressions: `sorted((path for path in (REPOSITORY_ROOT / 'docs').rglob('*.md') if not path.read_text(encoding='utf-8').startswith('<…`

**Exceptions and behavior**

Function `_markdown_documents` calls `sorted`, `(REPOSITORY_ROOT / 'docs').rglob`, `path.read_text(encoding='utf-8').startswith`, `path.read_text`; returns `sorted((path for path in (REPOSITORY_ROOT / 'docs').rglob('*.md') if not path.read_text(encoding='utf-8').startswith('<…`.
No direct `raise` statement appears in this definition.

[View source #L92-L101](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L92-L101).

</details>

<details class="api-contract" id="contract-scripts.mkdocs_hooks.on_post_build" markdown="1">
<summary><code>scripts.mkdocs_hooks.on_post_build</code> · function</summary>

```python
scripts.mkdocs_hooks.on_post_build(config, **kwargs) -> None
```

Write Markdown mirrors, the API inventory, and the full LLM corpus.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `config` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `**kwargs` | `not annotated` | `no` | `none` | Additional variadic keyword inputs accepted by this callable. |

**Returns**

- Type: `None`

**Exceptions and behavior**

Function `on_post_build` calls `Path`, `build_inventory`, `build_repository_inventory`, `build_cli_inventory`.
No direct `raise` statement appears in this definition.

[View source #L104-L225](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L104-L225).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`_source_revision`](#contract-scripts.mkdocs_hooks._source_revision) | function | `_source_revision() -> str` | Return the immutable commit represented by this documentation build. | [#L27-L46](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L27-L46) |
| [`_pin_source_links`](#contract-scripts.mkdocs_hooks._pin_source_links) | function | `_pin_source_links(text: str, revision: str) -> str` | Replace mutable gh-pages source links with one commit permalink. | [#L49-L55](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L49-L55) |
| [`on_page_markdown`](#contract-scripts.mkdocs_hooks.on_page_markdown) | function | `on_page_markdown(markdown: str, **kwargs) -> str` | Pin every rendered GitHub source link to the build commit. | [#L58-L62](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L58-L62) |
| [`on_post_page`](#contract-scripts.mkdocs_hooks.on_post_page) | function | `on_post_page(output: str, page = None, **kwargs) -> str` | Normalize search alternates and localized homepage presentation. | [#L65-L89](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L65-L89) |
| [`_markdown_documents`](#contract-scripts.mkdocs_hooks._markdown_documents) | function | `_markdown_documents() -> list[Path]` | Return tracked hand-written documentation pages in stable order. | [#L92-L101](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L92-L101) |
| [`on_post_build`](#contract-scripts.mkdocs_hooks.on_post_build) | function | `on_post_build(config, **kwargs) -> None` | Write Markdown mirrors, the API inventory, and the full LLM corpus. | [#L104-L225](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/mkdocs_hooks.py#L104-L225) |