Skip to main content

passageway-connector-mkdocs

A passageway connector that indexes a website built with MkDocs or Material for MkDocs: someone else's documentation, when you have the site but not its repository. It reads the site's search index, the file its search box uses, so it needs no crawling, and every hit opens the page at its heading.

What it does

  • Each section of the search index is one item. A built MkDocs site publishes search/search_index.json, with an entry for every page and every heading in it. Each entry with text becomes an item whose address is the page at that heading (https://docs.example.org/guide/setup/#linux), so a hit lands on the passage, not at the top of a long page. The text before a page's first heading is an item of its own at the page's address.
  • The page title is the item's title, the heading is its section, and the folders of the address are its breadcrumb (path), so a path: filter works.
  • The id is the address, the version a hash of the text, so an edit re-indexes only the sections it touched.
  • A site address means its search index. https://docs.example.org is read as https://docs.example.org/search/search_index.json; a site under a path (https://user.github.io/project) works the same, and the index's own address can be given too.
  • Both search plugins are understood. Material for MkDocs writes HTML into the index, which becomes text with code blocks and lists kept. MkDocs' own search plugin writes plain text and repeats the whole page in the page's entry; only the part before the first heading is kept there, so a passage is not indexed twice.
  • Any failure fails the whole listing. A site without a search index, an index that is not one, a server that is down: the sync stops with a message that names the address, so a half-read site never deletes what was indexed before.

When the site publishes an llms-full.txt (the mkdocs-llmstxt plugin writes one), the llms.txt connector reads the markdown itself; when you have the repository, the Markdown connector does. This connector is for the site as it is published.

Install

Add the connector to the environment that runs passageway (see Install):

uv tool install --python 3.14 "passageway[mkdocs]"

An example

A site https://docs.example.org whose search/search_index.json is:

{"docs": [
  {"location": "guide/setup/", "title": "Setup", "text": "<p>How to set it up.</p>"},
  {"location": "guide/setup/#linux", "title": "Linux", "text": "<p>Use the <code>apt</code> package.</p>"}
]}

gives, for the second entry, the item:

{
  "id": "https://docs.example.org/guide/setup/#linux",
  "title": "Setup",
  "url": "https://docs.example.org/guide/setup/#linux",
  "path": ["guide", "setup"],
  "sections": [
    {
      "heading": "Linux",
      "text": "Use the apt package."
    }
  ]
}

and is configured as:

[[connector]]
name = "vendor-docs"
command = ["/path/to/python", "-m", "passageway_connector_mkdocs"]
env = { URLS = "https://docs.example.org|https://user.github.io/project", WEIGHTS = "changelog=0.5" }

Settings

All settings are strings in the connector's env.

Setting Meaning Default
URLS Required. Site addresses, or the addresses of their search_index.json, separated by |.
MAX_BYTES The largest search index that is read, in bytes. A larger one fails the sync. 50000000
WEIGHTS Lowers or raises the weight of the sections whose path starts with a prefix: changelog=0.5,blog/=0.3 (comma-separated prefix=weight, the weight above 0, the first match wins). Release notes repeat the vocabulary of how-to pages and push them down the results; a weight below 1 ranks them lower. The path is the page's address without the site's own. all sections 1.0

Requests carry the user agent passageway-connector-mkdocs, follow redirects and verify HTTPS against the operating system's trust store.

Metadata

Release files for passageway-connector-mkdocs 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for passageway-connector-mkdocs 0.5.0
File Size Uploaded Provenance Actions
passageway_connector_mkdocs-0.5.0.tar.gz 7.7 kB Without provenance Details for passageway_connector_mkdocs-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for passageway-connector-mkdocs 0.5.0
File Interpreter ABI Platform Actions
passageway_connector_mkdocs-0.5.0-py3-none-any.whl Python 3 none any Details for passageway_connector_mkdocs-0.5.0-py3-none-any.whl

Total release size: 13.4 kB

Release files / passageway_connector_mkdocs-0.5.0.tar.gz

Download URL passageway_connector_mkdocs-0.5.0.tar.gz
Size 7.7 kB
Tags Source
SHA-256 checksum
How to use checksums
80fb8aabdfc31d72b4d81a2fd6cb7a4a6f4f0244677fe62c0c5b848b0e7698ce
BLAKE2b-256 checksum
How to use checksums
124604621086cd945ea3b7459388e9e2a0684502e16ebfeee35130f7342378d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / passageway_connector_mkdocs-0.5.0-py3-none-any.whl

Download URL passageway_connector_mkdocs-0.5.0-py3-none-any.whl
Size 5.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b55a0915607e1a8e8e12a98c9d4cbc9736c7a13415a1b311788c210575b5f210
BLAKE2b-256 checksum
How to use checksums
5093397f80c4b3ac8cdfe379e94b0e0dcff1ff71f088949ea441b5a400e3f245
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for passageway-connector-mkdocs 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page