Wikilink syntax as an equivalent alternative to standard markdown links inside OKF bundles

[joern-schlingensiepen]

Proposal: Wikilink syntax as an equivalent alternative to standard markdown links inside OKF bundles

Framing

This proposal is written based on my current reading of the OKF v0.1
draft SPEC and is offered as a contribution to the discussion,
not as a finished specification. It is entirely possible that I am
identifying a problem where none exists — the OKF use case as the
maintainers see it may differ from mine, or the current wording may
already permit what I am proposing.

My reading of OKF: it is meant to be a self-contained format for
providing information to AI agents, which typically consume that
information from files on disk. The question below is whether the
current link-syntax choice serves that goal as well as it could.

If the maintainers' framing of OKF differs, I welcome that
redirection. The rest of this document assumes my reading is at
least plausible.

Related, but deliberately separate: a companion proposal (Issue #175)
discusses external-bundle references via a bundle-local registry.
The two topics are orthogonal.

Motivation

OKF v0.1 §5.1 and §5.2 specify standard markdown links only.
Wikilinks ([[Name]]) are not mentioned.

In practice, the majority of markdown-based knowledge bases used by
LLM agents adopt Wikilinks as their primary internal reference
syntax. Standard markdown links exist too, but Wikilinks are the
default convention in the tools and corpora most likely to become
OKF producers or consumers.

This proposal asks whether the exclusive use of standard markdown
links is intentional and, if not, proposes to admit Wikilinks as a
syntactically equivalent alternative for bundle-internal references.

Context

• Karpathy's "llm-wiki" the shaping reference for the entire
  LLM-based knowledge-base trend uses Wikilinks throughout.
• Obsidian is mentioned in OKF §10 as a related pattern and is
  the de-facto editor/viewer for markdown-based knowledge bases.
  Wikilinks are its native reference syntax.
• Foam and many other note-taking / knowledge-management tools
  built on markdown adopt the same convention.
• Existing corpora Obsidian vaults, Foam notebooks, hand-rolled
  llm-wiki repositories are wikilink-native. Requiring standard
  markdown links closes off an otherwise frictionless migration
  path.

Self-containment argument

Wikilinks are not just an ergonomic choice — they are
structurally better aligned with self-containment than standard
markdown links.

Standard markdown links have no syntactic distinction between
intra-bundle and extra-bundle references:

[A](/local.md)        valid, intra-bundle
[B](../outside.md)    valid, filesystem-escape
[C](https://...)      valid, external
[D](file:///...)      valid, filesystem-escape

A consumer must parse each URL to know whether a link leaves the
bundle; a reviewer cannot enforce "self-contained" by inspection
alone.

Wikilinks, by contrast, cannot leave the bundle. [[Name]] is
by construction a reference to a bundle-internal document by name.
There is no escape hatch.

Proposal

Admit Wikilinks [[Name]] as an optional, equivalent syntax for
bundle-absolute markdown links:

[[Ronal the Babarian]]  ≡  [Ronal the Babarian](/Ronal the Babarian.md)

The change is purely additive:

• Bundles that use only standard markdown links remain valid.
• Bundles that use Wikilinks are readable by wikilink-aware
  consumers (Obsidian, Foam, most LLM-wiki tooling) natively.
  Standard-only consumers see the raw text; OKF §5.3 (Consumers MUST tolerate broken links) explicitly covers that fallback.

Semantic split enabled by the change

Combined with the existing markdown-link mechanism, admitting
Wikilinks creates a clean, syntactically-visible distinction between
three kinds of references — visible to producers, consumers, and
reviewers at a glance:

Syntax	Meaning
[[Name]]	Bundle-internal knowledge-graph node. Part of the OKF content.
[X](/path.md)	Bundle-absolute reference. Still part of the OKF content.
[X](https://...)	External citation. A reference to material outside the OKF — deliberately not part of the bundle's content.

This distinction has no cost: producers who prefer to author with
standard markdown links only can continue to do so, and the current
SPEC's use of [X](https://...) for citations (§8) is unchanged.
What producers gain is the ability to make the intra-bundle / extra-
bundle boundary visible in the source itself.

Backwards compatibility

Fully backwards-compatible. Bundles that avoid Wikilinks behave
exactly as under the current SPEC. Consumers unaware of Wikilinks
fall back to the §5.3 broken-link tolerance rule.

Open questions

• Should Wikilinks also be supported inside index.md entries?
  (SPEC §6 currently uses standard markdown links.)
• RFC-2119 tightening: SHOULD Wikilinks be preferred for the
  knowledge graph, or is it left purely to the producer's choice?