# mkdocs-crosslink-plugin
[](https://pypi.org/project/mkdocs-crosslink-plugin/)
This package allows you to add links to other MkDocs sites (or sites created with similar page generator).
## Usage
First install the PyPI package:
```bash
pip install mkdocs-crosslink-plugin
```
Add something like the following to your `mkdocs.yml`:
```yaml
plugins:
- search
- crosslink:
crosslinks:
- name: alpha
source_dir: site_a/docs
target_url: http://localhost:8000/site_a/
use_directory_urls: False
- name: "example"
source_dir: /var/www/html/example.com/
target_url: https://example.com/
use_directory_urls: True
```
Each crosslink has the following attributes:
- `name`: How you reference the site.
By default the schema is `x-NAME:FILE_NAME` (so for example `x-alpha:my-image.png`).
- `source_dir` is the directory containing the Markdown files.
- `target_url` is the path, where the site corresponding to the `source_dir` files are hosted.
- `use_directory_urls` should correspond to the target site's `use_directory_urls` settings.
- If enabled `path/index.md` will be mapped to `path/` and `path/test.md` will be mapped to `path/test/`.
- If disabled `path/index.md` will be mapped to `path/index.html` and `path/test.md` will be mapped to `path/test.html`.
Starting with version 0.0.2 you can also define multiple crosslinks at once, by using a glob-like syntax.
Inject a `*` character in the `name`, `source_dir`, and `target_url`.
The 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.
Starting 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.
On your pages you can reference links and images to other sites with the `x-SITE_NAME:FILE_NAME` syntax.
For example to load the image `my-image.png` somewhere from the `https://example.com/` (crosslink `example`) you would use the syntax:
```markdown
```
If multiple files with the exact same name exist, there is currently now way to reference the correct one.
In the future I plan to let you specify a part of the path to select the correct file.
From 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.
So `/path/to/some/index.md` can be referenced as `some/`.
## Compatibility with other autolink plugins
In theory, this plugin should work side by side with other autolink plugins.
This is because the default schema `x-NAME:` is basically a fake URL schema that any other plugins should not touch.
At the same time this plugin ignores normal links, which are processed by other autolink plugins.
Known 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).
You can work around this, by using links followed by a double slash and setting the correct suffix in the plugin settings:
```yaml
plugins:
- search
- crosslink:
suffix: "://"
crosslinks:
- name: "site_a"
...
```
## Testing
Some very basic tests are in `docs` (main site), `site_a` (crosslink alpha), and `site_b` (crosslink bravo).
You can build and serve the test site by running `./build.sh`.
## Notable changes
### Version 0.0.3
- Just some bug fixes
### Version 0.0.2
- Added builtin `local` crosslink
- Reference `index.md` as `<PARENT_DIR_NAME>/`
- Added glob support for crosslinks
- Added profiling option (`show_profiling_results: True`)
Raw data
{
"_id": null,
"home_page": "https://github.com/six-two/mkdocs-crosslink-plugin",
"name": "mkdocs-crosslink-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "six-two",
"author_email": "pip@six-two.dev",
"download_url": "https://files.pythonhosted.org/packages/9d/bb/8a9730485ec0f7c9c5b4c17b1d01887fdc9bce944a64e761b4eb928e3af5/mkdocs-crosslink-plugin-0.0.3.tar.gz",
"platform": null,
"description": "# mkdocs-crosslink-plugin\n[](https://pypi.org/project/mkdocs-crosslink-plugin/)\n\n\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\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 `<PARENT_DIR_NAME>/`\n- Added glob support for crosslinks\n- Added profiling option (`show_profiling_results: True`)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Simplify linking between different MkDocs sites",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/six-two/mkdocs-crosslink-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0385e3c6c3e126598d28663aefd8f76633c7aa177f379f9e8424dc4f7347bde4",
"md5": "e4af815f0506bd4c80e03405818210f6",
"sha256": "574602408806d89604874fd6d2603f4f01f57278ba0647e1d3863e4e4f53c548"
},
"downloads": -1,
"filename": "mkdocs_crosslink_plugin-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4af815f0506bd4c80e03405818210f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14252,
"upload_time": "2023-08-06T18:35:57",
"upload_time_iso_8601": "2023-08-06T18:35:57.444015Z",
"url": "https://files.pythonhosted.org/packages/03/85/e3c6c3e126598d28663aefd8f76633c7aa177f379f9e8424dc4f7347bde4/mkdocs_crosslink_plugin-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9dbb8a9730485ec0f7c9c5b4c17b1d01887fdc9bce944a64e761b4eb928e3af5",
"md5": "047a5cf00b1485d7a3495e8428d1f96a",
"sha256": "c64241ad9290432b36827b2f07da4e2151f064302abe0141751a46b950623350"
},
"downloads": -1,
"filename": "mkdocs-crosslink-plugin-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "047a5cf00b1485d7a3495e8428d1f96a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13882,
"upload_time": "2023-08-06T18:35:59",
"upload_time_iso_8601": "2023-08-06T18:35:59.202493Z",
"url": "https://files.pythonhosted.org/packages/9d/bb/8a9730485ec0f7c9c5b4c17b1d01887fdc9bce944a64e761b4eb928e3af5/mkdocs-crosslink-plugin-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-06 18:35:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "six-two",
"github_project": "mkdocs-crosslink-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mkdocs-crosslink-plugin"
}
JSON
