From 30361c3155d559fcdefa4fae6782e525a5ee469b Mon Sep 17 00:00:00 2001 From: manumishra12 Date: Sat, 11 Jul 2026 14:25:08 -0700 Subject: [PATCH] okf: clarify URL encoding for cross-link targets (SPEC 5.4) Section 5 did not state whether link targets require URL/percent encoding. Adds a short subsection: targets are ordinary markdown/CommonMark destinations resolved as bundle paths; keep segments URL-safe so no encoding is needed, and when a segment must carry a URL-unsafe character it MAY be percent-encoded and consumers SHOULD percent-decode before matching. Additive and backward-compatible. Addresses #112. --- okf/SPEC.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/okf/SPEC.md b/okf/SPEC.md index 55d0a46c..44aa9623 100644 --- a/okf/SPEC.md +++ b/okf/SPEC.md @@ -266,6 +266,21 @@ 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. +### 5.4 Link target encoding + +Link targets are ordinary markdown/CommonMark link destinations resolved as +bundle paths, not pre-encoded URLs. Because concept IDs are file paths, +producers SHOULD keep path segments URL-safe (letters, digits, `_`, `-`, `.`) +so that no percent-encoding is needed and a link resolves identically whether +it is treated as a file path or as a URL. + +If a path segment must contain a character that is unsafe in a URL (for +example a space), producers MAY percent-encode it in the link target +(`[Q1 report](/reports/q1%20report.md)`), exactly as CommonMark requires for +rendering. Consumers that resolve links against the filesystem SHOULD +percent-decode a target before matching it to a concept path. Prefer segments +that need no encoding to avoid the ambiguity entirely. + --- ## 6. Index Files