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 apath: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.orgis read ashttps://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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.