Obsidian OKF Links

Dependency-free tooling and conventions for making Obsidian vaults easier to share with Open Knowledge Format (OKF) consumers without giving up wikilinks as the authoring format.

Why This Exists

Obsidian users often prefer wikilinks:

[[Inventory - Car Care]]
[[decisions/Decision Log - Car Care|decision log]]
[[#Winter Salt Rinse]]

Many OKF and Markdown consumers prefer standard Markdown links:

[Inventory - Car Care](Inventory%20-%20Car%20Care.md)
[decision log](decisions/Decision%20Log%20-%20Car%20Care.md)
[Winter Salt Rinse](#winter-salt-rinse)

This project supports both:

• keep wikilinks in the Obsidian authoring vault;
• convert a copy or branch to Markdown links for strict OKF consumers;
• convert Markdown links back to wikilinks when useful;
• propose a small OKF revision that accepts constrained relative wikilinks directly.

Contents

scripts/obsidian_okf_links.py
tests/test_obsidian_okf_links.py
docs/obsidian-okf-wikilink-convention.md
docs/okf-proposals/0001-relative-wikilinks.md

Install

Copy the script into the root of an Obsidian vault:

mkdir -p scripts
cp scripts/obsidian_okf_links.py /path/to/vault/scripts/

The script uses only the Python standard library. Python 3.9+ is supported.

Usage

From the vault root:

scripts/obsidian_okf_links.py scan

Dry-run conversion to standard Markdown links:

scripts/obsidian_okf_links.py to-markdown

Write conversion to standard Markdown links:

scripts/obsidian_okf_links.py to-markdown --write

Write conversion back to Obsidian wikilinks:

scripts/obsidian_okf_links.py to-wikilinks --write

Use a different vault root:

scripts/obsidian_okf_links.py to-markdown --root /path/to/vault

Recommended Workflow

1. Author normally in Obsidian with wikilinks.
2. Before publishing to a strict OKF consumer, create a branch or copy.
3. Run scripts/obsidian_okf_links.py to-markdown --write.
4. Run your OKF validator or publishing workflow.
5. Keep the authoring vault in wikilink form, or run scripts/obsidian_okf_links.py to-wikilinks --write if conversion happened in place.

Behavior

The converter handles:

• note wikilinks;
• aliased wikilinks;
• same-file heading wikilinks;
• note-heading wikilinks;
• relative paths from nested folders;
• conversion back from internal Markdown links to wikilinks.

The converter skips:

• .git;
• .obsidian;
• .trash;
• fenced code blocks;
• inline code;
• embeds like ![[image.png]].

Tests

python3 -m unittest tests/test_obsidian_okf_links.py

OKF Proposal

See OKF Proposal 0001 - Relative Wikilinks.

The proposal is intentionally narrow: OKF consumers should accept relative wikilinks as graph edges, but do not need to implement every Obsidian-specific extension.

License

MIT. See LICENSE.