Obsidian ➡️ MkDocs Bridge

An MkDocs plugin that helps exporting your Obsidian 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
• Auto-expand incomplete Obsidian's internal links
• 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). Consider the following folder structure:

docs/
├── 2021/
│   ├── Books.md
│   └── Games.md
└── 2022/
    └── Sport.md

If you are editing Sport.md, you could write:

[Books](../2021/Books.md)

but with this plugin you can just drop the path:

[Books](Books.md)

or even write the Obsidian way:

[[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), e.g.

[[Books]]

is translated into:

[Books](./Books.md)

But you can also give the resolver a hint by specifying the path partially:

[[2021/Books]]

or

[Books](2021/Books.md)

Both variants work equivalently.

How to enable

Install the plugin with:

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:

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:

markdown_extensions:
  - obsidian_media_mkdocs

More information on this feature can be found here: GooRoo/obsidian-media.

Using callouts

Looking for Obsidian-style callouts? Enable them in your mkdocs.yml like this:

markdown_extensions:
  - obsidian_callouts

More information on this feature can be found here: 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.

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.

plugins:
  - obsidian-bridge:
      warn_on_invalid_links: true

Styling of invalid links

markdown_extensions:
  - attr_list

plugins:
  - obsidian-bridge:
      invalid_link_attributes:
        - '.invalid'

extra_css:
  - stylesheets/extra.css

a.invalid {
  color: red;
}

markdown_extensions:
  - attr_list

plugins:
  - obsidian-bridge:
      invalid_link_attributes:
        - 'style="color: red"'

What's next

My current preliminary roadmap is the following:

• Embedding of audio/video
• Obsidian's callouts
• Support for Obsidian's nested tags
• Obsidian's 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.
• If you want to request a feature, please, post an idea.
• In all other cases, don't hesitate to start a discussion.