{"id":22492487,"url":"https://github.com/six-two/mkdocs-crosslink-plugin","last_synced_at":"2026-02-25T08:41:31.713Z","repository":{"id":186078267,"uuid":"672515030","full_name":"six-two/mkdocs-crosslink-plugin","owner":"six-two","description":"Simplify links between different MkDocs sites","archived":false,"fork":false,"pushed_at":"2025-03-12T17:28:32.000Z","size":99,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-16T21:52:57.306Z","etag":null,"topics":["links","mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"https://mkdocs-crosslink-plugin.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/six-two.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-07-30T10:54:29.000Z","updated_at":"2025-03-12T17:28:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"60cf250e-c8ad-42ae-bbe9-4c32ca6d530c","html_url":"https://github.com/six-two/mkdocs-crosslink-plugin","commit_stats":null,"previous_names":["six-two/mkdocs-crosslink-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/six-two/mkdocs-crosslink-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-crosslink-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-crosslink-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-crosslink-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-crosslink-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/six-two","download_url":"https://codeload.github.com/six-two/mkdocs-crosslink-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-crosslink-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29815025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T05:36:42.804Z","status":"ssl_error","status_checked_at":"2026-02-25T05:36:31.934Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["links","mkdocs","mkdocs-plugin"],"created_at":"2024-12-06T18:18:03.898Z","updated_at":"2026-02-25T08:41:31.686Z","avatar_url":"https://github.com/six-two.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-crosslink-plugin\n[![PyPI version](https://img.shields.io/pypi/v/mkdocs-crosslink-plugin)](https://pypi.org/project/mkdocs-crosslink-plugin/)\n![License](https://img.shields.io/pypi/l/mkdocs-crosslink-plugin)\n![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-crosslink-plugin)\n\nThis package allows you to add links to other MkDocs sites (or sites created with similar page generator).\n\n## Usage\n\nFirst install the PyPI package:\n```bash\npip install mkdocs-crosslink-plugin\n```\n\nAdd something like the following to your `mkdocs.yml`:\n```yaml\nplugins:\n- search\n- crosslink:\n    crosslinks:\n    - name: alpha\n      source_dir: site_a/docs\n      target_url: http://localhost:8000/site_a/\n      use_directory_urls: False\n    - name: \"example\"\n      source_dir: /var/www/html/example.com/\n      target_url: https://example.com/\n      use_directory_urls: True\n```\n\nEach crosslink has the following attributes:\n\n- `name`: How you reference the site.\n    By default the schema is `x-NAME:FILE_NAME` (so for example `x-alpha:my-image.png`).\n- `source_dir` is the directory containing the Markdown files.\n- `target_url` is the path, where the site corresponding to the `source_dir` files are hosted.\n- `use_directory_urls` should correspond to the target site's `use_directory_urls` settings.\n    - If enabled `path/index.md` will be mapped to `path/` and `path/test.md` will be mapped to `path/test/`.\n    - If disabled `path/index.md` will be mapped to `path/index.html` and `path/test.md` will be mapped to `path/test.html`.\n\nStarting with version 0.0.2 you can also define multiple crosslinks at once, by using a glob-like syntax.\nInject a `*` character in the `name`, `source_dir`, and `target_url`.\nThe plugin will then look for directories matching the `source_dir` glob, create a crosslink for each one that was not defined before, and replace the `*` in the `name` and `target_url` with the same value that it matched in the `source_dir` value.\n\nStarting with version 0.0.2 there is also a builtin `local` crosslink, which can be used to reference files in the current site, similar to other autolink tools.\n\nOn your pages you can reference links and images to other sites with the `x-SITE_NAME:FILE_NAME` syntax.\nFor example to load the image `my-image.png` somewhere from the `https://example.com/` (crosslink `example`) you would use the syntax:\n```markdown\n![My Image](x-example:my-image.png)\n```\n\nIf multiple files with the exact same name exist, there is currently now way to reference the correct one.\nIn the future I plan to let you specify a part of the path to select the correct file.\nFrom 0.0.2 on: For index files (`index.md` or `index.html`) you can reference them by the name of the parent's directory followed by a slash.\nSo `/path/to/some/index.md` can be referenced as `some/`.\n\n## Compatibility with other autolink plugins\n\nIn theory, this plugin should work side by side with other autolink plugins.\nThis is because the default schema `x-NAME:` is basically a fake URL schema that any other plugins should not touch.\nAt the same time this plugin ignores normal links, which are processed by other autolink plugins.\n\nKnown problems exist with [mkdocs-ezlinks-plugin](https://github.com/orbikm/mkdocs-ezlinks-plugin/) because it expects custom URL schemas to be followed by `//` (like `x-NAME://`) as can be seen by the [`mailto:` issue](https://github.com/orbikm/mkdocs-ezlinks-plugin/issues/48).\nYou can work around this, by using links followed by a double slash and setting the correct suffix in the plugin settings:\n```yaml\nplugins:\n  - search\n  - crosslink:\n      suffix: \"://\"\n      crosslinks:\n      - name: \"site_a\"\n        ...\n```\n\n\n## Testing\n\nSome very basic tests are in `docs` (main site), `site_a` (crosslink alpha), and `site_b` (crosslink bravo).\nYou can build and serve the test site by running `./build.sh`.\n\n## Notable changes\n\n### Version 0.0.3\n\n- Just some bug fixes\n\n### Version 0.0.2\n\n- Added builtin `local` crosslink\n- Reference `index.md` as `\u003cPARENT_DIR_NAME\u003e/`\n- Added glob support for crosslinks\n- Added profiling option (`show_profiling_results: True`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsix-two%2Fmkdocs-crosslink-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsix-two%2Fmkdocs-crosslink-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsix-two%2Fmkdocs-crosslink-plugin/lists"}