| Name | mkdocs-obsidian-bridge JSON |
| Version |
1.3.1
JSON |
| download |
| home_page | None |
| Summary | An MkDocs plugin that helps exporting your Obsidian vault as an MkDocs site. |
| upload_time | 2025-08-13 13:30:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--
SPDX-FileCopyrightText: © 2022 Serhii “GooRoo” Olendarenko
SPDX-License-Identifier: BSD-3-Clause
-->
# [Obsidian][obsidian] ➡️ [MkDocs][mkdocs] Bridge
[](https://savelife.in.ua/en/donate-en/#donate-army-card-once)
[](LICENSE)
An MkDocs plugin that helps exporting your [Obsidian](https://obsidian.md) vault as an MkDocs site.
## What it does
I began writing this plugin to simplify exporting my Obsidian vault to GitHub Pages using MkDocs. The plugin is still in development since there are a lot more features that could possibly be implemented, however, currently it has the following features:
- Auto-expand incomplete [Markdown links](https://help.obsidian.md/How+to/Format+your+notes#Links)
- Auto-expand incomplete [Obsidian's internal links](https://help.obsidian.md/How+to/Internal+link)
- Detect and mark invalid links (to style them differently)
### Auto-expanding incomplete links
By auto-expanding I mean that you don't need to write a full path to the page you are linking to (exactly like in [Obsidian][obsidian]). Consider the following folder structure:
```
docs/
├── 2021/
│ ├── Books.md
│ └── Games.md
└── 2022/
└── Sport.md
```
If you are editing `Sport.md`, you could write:
```md
[Books](../2021/Books.md)
```
but with this plugin you can just drop the path:
```md
[Books](Books.md)
```
or even write the [Obsidian][obsidian] way:
```md
[[Books]]
```
#### Name clashes
What if you have `Books.md` in both 2021 and 2022?
```
docs/
├── 2021/
│ ├── Books.md
│ └── Games.md
└── 2022/
├── Books.md
└── Sport.md
```
By default, the plugin tried to find the shortest relative path (again, like [Obsidian][obsidian]), e.g.
```md
[[Books]]
```
is translated into:
```md
[Books](./Books.md)
```
But you can also give the resolver _a hint_ by specifying the path **partially:**
```md
[[2021/Books]]
```
or
```md
[Books](2021/Books.md)
```
Both variants work equivalently.
## How to enable
Install the plugin with:
```sh
pip install mkdocs-obsidian-bridge
```
The plugin depends on some features of Python 3.10, so this is the minimum required version.
Then you can enable it in your `mkdocs.yml` config:
```yaml
plugins:
- obsidian-bridge
```
### Embedding of media files
If you want to have Obsidian-like embedding of audio and video files or even YouTube videos, enable it in your `mkdocs.yml` like this:
```yaml
markdown_extensions:
- obsidian_media_mkdocs
```
More information on this feature can be found here: [**GooRoo/obsidian-media**](https://github.com/GooRoo/obsidian-media).
### Using callouts
Looking for Obsidian-style callouts? Enable them in your `mkdocs.yml` like this:
```yaml
markdown_extensions:
- obsidian_callouts
```
More information on this feature can be found here: [**GooRoo/obsidian-callouts**](https://github.com/GooRoo/obsidian-callouts).
## Why one more plugin?
I wouldn't ever write this one if I could achieve what I need with other ones. Maybe, I just couldn't find the solution, but here we are.
<details>
<summary>Comparison to others (possibly, outdated)</summary>
### Differences to [Autolinks Plugin](https://github.com/zachhannum/mkdocs-autolinks-plugin)
1. **Autolinks Plugin** doesn't try to resolve the shortest path out of the list of potential candidates.
2. It also doesn't support incomplete relative paths. In other words, it works only with file names.
### Differences to [Roamlinks Plugin](https://github.com/Jackiexiao/mkdocs-roamlinks-plugin)
This one, actually, was the reason why I started developing my own plugin in the first place. However, it had the following drawbacks for my use-case:
1. As well as **Autolinks Plugin**, the **Roamlinks Plugin** does not try to match the best path if there several of those, does it?
2. Also, in case it can't resolve the `[[Roam link]]`, it leaves it as a text, while [**Obsidian Bridge**](https://github.com/GooRoo/mkdocs-obsidian-bridge) still transforms it into the Markdown link although invalid one.
### Differences to [EZLinks Plugin](https://github.com/orbikm/mkdocs-ezlinks-plugin)
This one looked like a perfect choice for my needs, however:
1. I didn't spent much time playing with it, but **EZLinks Plugin** generated incorrect links for me. Probably because it doesn't resolve any incomplete paths as well as two previous plugins.
2. At the same time, it **does** convert the `[[internal links]]` into actual links.
3. It has no ability to distinguish between valid and invalid `[[internal links]]`. Maybe it could be solved by another plugin, but I haven't searched for it.
### Differences to [WikiLinks](https://python-markdown.github.io/extensions/wikilinks/) extension for [Python-Markdown](https://github.com/Python-Markdown/markdown/)
1. I haven't tried this one, but it looks like **WikiLinks** is unable to automatically resolve paths at all without an additional (and a bit cumbersome) config.
2. Also, not sure if it supports all the [Obsidian][obsidian]'s features.
</details>
---
## Advanced topics
### Warnings for invalid links
Optionally, you can ask plugin to warn you when the resulting link still leads to an invalid target. This will prevent your site from building in “strict” mode.
<details>
<summary>Enable it like this</summary>
```yaml
plugins:
- obsidian-bridge:
warn_on_invalid_links: true
```
</details>
### Styling of invalid links
<details>
<summary>See for yourself!</summary>
The plugin translates [Obsidian][obsidian]-style `[[internal links]]` to markdown `[internal links](internal%20links)` even if the resulting link is invalid. If you want to distinguish such links from the rest, you can assign them a custom CSS style.
In order to do that, you should add an `invalid_link_attributes` config option to your `mkdocs.yml` **AND** enable the `attr_list` Markdown extension:
```yaml
markdown_extensions:
- attr_list
plugins:
- obsidian-bridge:
invalid_link_attributes:
- '.invalid'
extra_css:
- stylesheets/extra.css
```
The `.invalid` in this example translates to `class="invalid"` HTML attribute accordingly to the rules of [**Attribute Lists**](https://python-markdown.github.io/extensions/attr_list/) extension.
After that, you can extend `extra.css` with some style (just don't forget to add `extra_css` property to your `mkdocs.yml` too as above):
```css
a.invalid {
color: red;
}
```
Alternatively, if your style is going to be simple, you can just write it in the attribute itself as following:
```yaml
markdown_extensions:
- attr_list
plugins:
- obsidian-bridge:
invalid_link_attributes:
- 'style="color: red"'
```
</details>
---
## What's next
My current preliminary roadmap is the following:
- [x] [**Embedding of audio/video**](https://help.obsidian.md/Linking+notes+and+files/Embed+files)
- [x] Obsidian's [**callouts**](https://help.obsidian.md/Editing+and+formatting/Callouts)
- [ ] Support for Obsidian's [**nested tags**](https://help.obsidian.md/Editing+and+formatting/Tags#Nested+tags)
- [ ] Obsidian's [**comments**](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Comments) `%% ... %%` ➡️ HTML comments `<!-- ... -->`
I give no guarantees about the deadlines or whether I implement anything at all. I do it for myself and currently I do see a need, so probably I'll continue.
### Feedback
I do appreciate any kind of constructive feedback.
* If you found a bug, please, [report it](https://github.com/GooRoo/mkdocs-obsidian-bridge/issues/new).
* If you want to request a feature, please, [post an idea](https://github.com/GooRoo/mkdocs-obsidian-bridge/discussions/new?category=Ideas).
* In all other cases, don't hesitate to [start a discussion](https://github.com/GooRoo/mkdocs-obsidian-bridge/discussions/new).
[mkdocs]: https://www.mkdocs.org
[obsidian]: https://obsidian.md
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-obsidian-bridge",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "GooRoo <sergey.olendarenko@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ee/93/d0dda71bacfcbdeb522a16e895311669a75eda3e7872e6182a5957520877/mkdocs_obsidian_bridge-1.3.1.tar.gz",
"platform": null,
"description": "<!--\nSPDX-FileCopyrightText: \u00a9 2022 Serhii \u201cGooRoo\u201d Olendarenko\n\nSPDX-License-Identifier: BSD-3-Clause\n-->\n\n# [Obsidian][obsidian] \u27a1\ufe0f [MkDocs][mkdocs] Bridge\n\n[](https://savelife.in.ua/en/donate-en/#donate-army-card-once)\n[](LICENSE)\n\n\n\nAn MkDocs plugin that helps exporting your [Obsidian](https://obsidian.md) vault as an MkDocs site.\n\n## What it does\n\nI began writing this plugin to simplify exporting my Obsidian vault to GitHub Pages using MkDocs. The plugin is still in development since there are a lot more features that could possibly be implemented, however, currently it has the following features:\n\n- Auto-expand incomplete [Markdown links](https://help.obsidian.md/How+to/Format+your+notes#Links)\n- Auto-expand incomplete [Obsidian's internal links](https://help.obsidian.md/How+to/Internal+link)\n- Detect and mark invalid links (to style them differently)\n\n### Auto-expanding incomplete links\n\nBy auto-expanding I mean that you don't need to write a full path to the page you are linking to (exactly like in [Obsidian][obsidian]). Consider the following folder structure:\n\n```\ndocs/\n\u251c\u2500\u2500 2021/\n\u2502 \u251c\u2500\u2500 Books.md\n\u2502 \u2514\u2500\u2500 Games.md\n\u2514\u2500\u2500 2022/\n \u2514\u2500\u2500 Sport.md\n```\n\nIf you are editing `Sport.md`, you could write:\n```md\n[Books](../2021/Books.md)\n```\nbut with this plugin you can just drop the path:\n```md\n[Books](Books.md)\n```\nor even write the [Obsidian][obsidian] way:\n```md\n[[Books]]\n```\n\n#### Name clashes\n\nWhat if you have `Books.md` in both 2021 and 2022?\n\n```\ndocs/\n\u251c\u2500\u2500 2021/\n\u2502 \u251c\u2500\u2500 Books.md\n\u2502 \u2514\u2500\u2500 Games.md\n\u2514\u2500\u2500 2022/\n \u251c\u2500\u2500 Books.md\n \u2514\u2500\u2500 Sport.md\n```\n\nBy default, the plugin tried to find the shortest relative path (again, like [Obsidian][obsidian]), e.g.\n```md\n[[Books]]\n```\nis translated into:\n```md\n[Books](./Books.md)\n```\n\nBut you can also give the resolver _a hint_ by specifying the path **partially:**\n```md\n[[2021/Books]]\n```\nor\n```md\n[Books](2021/Books.md)\n```\n\nBoth variants work equivalently.\n\n## How to enable\n\nInstall the plugin with:\n\n```sh\npip install mkdocs-obsidian-bridge\n```\n\nThe plugin depends on some features of Python 3.10, so this is the minimum required version.\n\nThen you can enable it in your `mkdocs.yml` config:\n\n```yaml\nplugins:\n - obsidian-bridge\n```\n\n### Embedding of media files\n\nIf you want to have Obsidian-like embedding of audio and video files or even YouTube videos, enable it in your `mkdocs.yml` like this:\n\n```yaml\nmarkdown_extensions:\n - obsidian_media_mkdocs\n```\n\nMore information on this feature can be found here: [**GooRoo/obsidian-media**](https://github.com/GooRoo/obsidian-media).\n\n### Using callouts\n\nLooking for Obsidian-style callouts? Enable them in your `mkdocs.yml` like this:\n\n```yaml\nmarkdown_extensions:\n - obsidian_callouts\n```\n\nMore information on this feature can be found here: [**GooRoo/obsidian-callouts**](https://github.com/GooRoo/obsidian-callouts).\n\n## Why one more plugin?\n\nI wouldn't ever write this one if I could achieve what I need with other ones. Maybe, I just couldn't find the solution, but here we are.\n\n<details>\n <summary>Comparison to others (possibly, outdated)</summary>\n\n### Differences to [Autolinks Plugin](https://github.com/zachhannum/mkdocs-autolinks-plugin)\n\n1. **Autolinks Plugin** doesn't try to resolve the shortest path out of the list of potential candidates.\n2. It also doesn't support incomplete relative paths. In other words, it works only with file names.\n\n### Differences to [Roamlinks Plugin](https://github.com/Jackiexiao/mkdocs-roamlinks-plugin)\n\nThis one, actually, was the reason why I started developing my own plugin in the first place. However, it had the following drawbacks for my use-case:\n\n1. As well as **Autolinks Plugin**, the **Roamlinks Plugin** does not try to match the best path if there several of those, does it?\n2. Also, in case it can't resolve the `[[Roam link]]`, it leaves it as a text, while [**Obsidian Bridge**](https://github.com/GooRoo/mkdocs-obsidian-bridge) still transforms it into the Markdown link although invalid one.\n\n### Differences to [EZLinks Plugin](https://github.com/orbikm/mkdocs-ezlinks-plugin)\n\nThis one looked like a perfect choice for my needs, however:\n\n1. I didn't spent much time playing with it, but **EZLinks Plugin** generated incorrect links for me. Probably because it doesn't resolve any incomplete paths as well as two previous plugins.\n2. At the same time, it **does** convert the `[[internal links]]` into actual links.\n3. It has no ability to distinguish between valid and invalid `[[internal links]]`. Maybe it could be solved by another plugin, but I haven't searched for it.\n\n### Differences to [WikiLinks](https://python-markdown.github.io/extensions/wikilinks/) extension for [Python-Markdown](https://github.com/Python-Markdown/markdown/)\n\n1. I haven't tried this one, but it looks like **WikiLinks** is unable to automatically resolve paths at all without an additional (and a bit cumbersome) config.\n2. Also, not sure if it supports all the [Obsidian][obsidian]'s features.\n\n</details>\n\n---\n\n## Advanced topics\n\n### Warnings for invalid links\n\nOptionally, you can ask plugin to warn you when the resulting link still leads to an invalid target. This will prevent your site from building in \u201cstrict\u201d mode.\n<details>\n <summary>Enable it like this</summary>\n\n```yaml\nplugins:\n - obsidian-bridge:\n warn_on_invalid_links: true\n```\n</details>\n\n### Styling of invalid links\n\n<details>\n <summary>See for yourself!</summary>\n\n\nThe plugin translates [Obsidian][obsidian]-style `[[internal links]]` to markdown `[internal links](internal%20links)` even if the resulting link is invalid. If you want to distinguish such links from the rest, you can assign them a custom CSS style.\n\nIn order to do that, you should add an `invalid_link_attributes` config option to your `mkdocs.yml` **AND** enable the `attr_list` Markdown extension:\n\n```yaml\nmarkdown_extensions:\n - attr_list\n\nplugins:\n - obsidian-bridge:\n invalid_link_attributes:\n - '.invalid'\n\nextra_css:\n - stylesheets/extra.css\n```\n\nThe `.invalid` in this example translates to `class=\"invalid\"` HTML attribute accordingly to the rules of [**Attribute Lists**](https://python-markdown.github.io/extensions/attr_list/) extension.\n\nAfter that, you can extend `extra.css` with some style (just don't forget to add `extra_css` property to your `mkdocs.yml` too as above):\n\n```css\na.invalid {\n color: red;\n}\n```\n\nAlternatively, if your style is going to be simple, you can just write it in the attribute itself as following:\n\n```yaml\nmarkdown_extensions:\n - attr_list\n\nplugins:\n - obsidian-bridge:\n invalid_link_attributes:\n - 'style=\"color: red\"'\n```\n</details>\n\n---\n\n## What's next\n\nMy current preliminary roadmap is the following:\n\n- [x] [**Embedding of audio/video**](https://help.obsidian.md/Linking+notes+and+files/Embed+files)\n- [x] Obsidian's [**callouts**](https://help.obsidian.md/Editing+and+formatting/Callouts)\n- [ ] Support for Obsidian's [**nested tags**](https://help.obsidian.md/Editing+and+formatting/Tags#Nested+tags)\n- [ ] Obsidian's [**comments**](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Comments) `%% ... %%` \u27a1\ufe0f HTML comments `<!-- ... -->`\n\nI give no guarantees about the deadlines or whether I implement anything at all. I do it for myself and currently I do see a need, so probably I'll continue.\n\n### Feedback\n\nI do appreciate any kind of constructive feedback.\n\n* If you found a bug, please, [report it](https://github.com/GooRoo/mkdocs-obsidian-bridge/issues/new).\n* If you want to request a feature, please, [post an idea](https://github.com/GooRoo/mkdocs-obsidian-bridge/discussions/new?category=Ideas).\n* In all other cases, don't hesitate to [start a discussion](https://github.com/GooRoo/mkdocs-obsidian-bridge/discussions/new).\n\n\n[mkdocs]: https://www.mkdocs.org\n[obsidian]: https://obsidian.md\n",
"bugtrack_url": null,
"license": null,
"summary": "An MkDocs plugin that helps exporting your Obsidian vault as an MkDocs site.",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/GooRoo/mkdocs-obsidian-bridge",
"Issues": "https://github.com/GooRoo/mkdocs-obsidian-bridge/issues",
"Repository": "https://github.com/GooRoo/mkdocs-obsidian-bridge.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "253fb250670f6a960186f556a49b6ab8714867065a0d03565cb678a3d0313216",
"md5": "d40fa7810d50d8d5e5491f6b5a2fc699",
"sha256": "8653c49f970ad1e6c08983e5c9d0cfc2be4af0d432e415a5e601b9be00696126"
},
"downloads": -1,
"filename": "mkdocs_obsidian_bridge-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d40fa7810d50d8d5e5491f6b5a2fc699",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 10129,
"upload_time": "2025-08-13T13:30:25",
"upload_time_iso_8601": "2025-08-13T13:30:25.553095Z",
"url": "https://files.pythonhosted.org/packages/25/3f/b250670f6a960186f556a49b6ab8714867065a0d03565cb678a3d0313216/mkdocs_obsidian_bridge-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ee93d0dda71bacfcbdeb522a16e895311669a75eda3e7872e6182a5957520877",
"md5": "36a5201a1a5c8b7e9dc23b5839776ef0",
"sha256": "92d7cee4dc857a45818b912c0091452a22976250513ee63fb4c1f64bb06d2ab8"
},
"downloads": -1,
"filename": "mkdocs_obsidian_bridge-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "36a5201a1a5c8b7e9dc23b5839776ef0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 65061,
"upload_time": "2025-08-13T13:30:26",
"upload_time_iso_8601": "2025-08-13T13:30:26.663231Z",
"url": "https://files.pythonhosted.org/packages/ee/93/d0dda71bacfcbdeb522a16e895311669a75eda3e7872e6182a5957520877/mkdocs_obsidian_bridge-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 13:30:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GooRoo",
"github_project": "mkdocs-obsidian-bridge",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-obsidian-bridge"
}
