| Name | mkdocs-obsidian-bridge JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | None |
| Summary | An MkDocs plugin that helps exporting your Obsidian vault as an MkDocs site. |
| upload_time | 2024-09-23 22:06:50 |
| 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).
## 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
### 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)
- [ ] Obsidian's [**callouts**](https://help.obsidian.md/Editing+and+formatting/Callouts) ➡️ MkDocs's [**admonitions**](https://python-markdown.github.io/extensions/admonition/)
- [ ] 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/3e/49/19e5dddea68b1383a60df206d38a852e275ddae92959721662a0c134411e/mkdocs_obsidian_bridge-1.1.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\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## 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### 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- [ ] Obsidian's [**callouts**](https://help.obsidian.md/Editing+and+formatting/Callouts) \u27a1\ufe0f MkDocs's [**admonitions**](https://python-markdown.github.io/extensions/admonition/)\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.1.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": "",
"digests": {
"blake2b_256": "51c545b9d09745196cf394ea5ce79e84e9c6f518c9a0687be7c47cf49fe56b20",
"md5": "37725ae37359be75bb88d68534212b30",
"sha256": "1c16e45a266e54ae969d5d4dc5457742c991aeafc529878a2598b5a13eb513eb"
},
"downloads": -1,
"filename": "mkdocs_obsidian_bridge-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37725ae37359be75bb88d68534212b30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 9727,
"upload_time": "2024-09-23T22:06:48",
"upload_time_iso_8601": "2024-09-23T22:06:48.957701Z",
"url": "https://files.pythonhosted.org/packages/51/c5/45b9d09745196cf394ea5ce79e84e9c6f518c9a0687be7c47cf49fe56b20/mkdocs_obsidian_bridge-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3e4919e5dddea68b1383a60df206d38a852e275ddae92959721662a0c134411e",
"md5": "1c29d3344605051c14c5e3ea9e230177",
"sha256": "9ee0b89c881982a908a18dfc3108d4a8e225c1fc22776052ce4ad2efd17b14f2"
},
"downloads": -1,
"filename": "mkdocs_obsidian_bridge-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1c29d3344605051c14c5e3ea9e230177",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 49201,
"upload_time": "2024-09-23T22:06:50",
"upload_time_iso_8601": "2024-09-23T22:06:50.740286Z",
"url": "https://files.pythonhosted.org/packages/3e/49/19e5dddea68b1383a60df206d38a852e275ddae92959721662a0c134411e/mkdocs_obsidian_bridge-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 22:06:50",
"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"
}
