GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: Make cross-linking less brittle by allowing for permalinks

Open
#115 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Motivation
The current cross-linking design, as defined in §5 is very brittle. Links will be prone to breaking, and the OKF will need to be regularly maintained to repair broken links. This will require either a lot of work from human review, or burning a lot of agent tokens to repair broken links and find missing resources. Either way, the value of the OKF will diminish because we will lose confidence in the knowledge base. We will not know if something is unlinked because two concepts are unrelated, or the linked file hasn't been created yet, or the link actually does exist but the link is now broken.

```md
[My Other Concept](path/to/concept.md)
If the above file is ever moved to say `my/other/concept.md` then now the above link is broken and it is difficult to repair the broken link because there may be many files with the same name.
```

Admittedly the SPEC does mention: _"Consumers MUST tolerate broken links – a link whose target does not exist in the bundle is not malformed; it may simply represent not-yet-written knowledge."_ I think this stance is correct. 1. I often write a link to a concept that I MIGHT explore in depth later. 2. When an agent is in the process of writing to a file, they will often need to mention a file that they have not yet created.

But this quote only tackles one part of the broken links problem: links to files that do not exist yet. What it does not cover is links to files that STILL exist and yet the link is broken. We need to provide solutions that enable **link resiliency**[^1].

[^1]: enable, not guarantee

As of OKF v0.1, links are only path based (relative or absolute). The problem is that once the file needs to be moved or renamed then every single link needs to be updated. Obsidian, and some other tools handle this by monitoring every file, and once a file is renamed, it will find every link and update them. This solution works well enough when you have one human user, but this solution is especially problematic when you have agents.

Agents will happily move or rename files without knowing that it broke all the links. An automated tool could repair broken links, just like Obsidian does, but then the agent doesn't know that these changes happened under its nose. This problem increases exponentially as users parallelize with multiple agents and subagents. Even if we used a tool like an MCP to dynamically notify an agent when a file path has changed, the agent still has the incorrect path earlier in its context, increasing the likelihood that it will use the old incorrect path.

## "Permalinks"
OKF should reserve a top level YAML property `permalink` which holds a slug for a particular concept file. Relative and absolute links will still behave just as before (§5.1 and 5.2), but now there will be a new option.

```md
File: /Books/The Lion, The Witch, and The Wardrobe
---
title: The Lion, The Witch, and The Wardrobe
type: Books
permalink: the-lion-the-witch-and-the-wardrobe
---
```

Now we can link to this file like this: `[The Lion, The Witch, and The Wardrobe](the-lion-the-witch-and-the-wardrobe)`. Now this link is resilient. It will still work even if the name is changed[^2] or if the path is changed[^3].

[^2]: Like, say for example, when we realize that the oxford comma is not in the original book title and the file should be named `The Lion, the Witch and the Wardrobe.md`.
[^3]: Like, say for example, if we decided to move the /Books/ folder into /Media/ so that the path is now `/Media/Books/The Lion, The Witch, and The Wardrobe.md`, then the link would not break because we used the permalink.

Users may use a permalink slug and it will link to a file whose `permalink` YAML property matches that string value. This way even if the file name changes or any of the ancestor directories change, the link will not break.

For reference, here is how Obsidian implemented permalinks: [[Permalinks - Obsidian Help](https://obsidian.md/help/publish/permalinks)](https://obsidian.md/help/publish/permalinks).

Contributor guide

Open the contributing guide

Research direction

Start by reading the cross-linking rules in §5 and compare them with the linked Obsidian permalinks reference. Define how the proposed permalink YAML property and slug-based links should interact with existing relative and absolute links, including unresolved and renamed targets. Done means the specification behavior and edge cases are agreed and documented.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.