Skip to content

wiki-ingest: agents render citable URLs as backtick text instead of clickable markdown links #171

Description

@aiziumov-nb

Problem

Ingested wiki pages consistently render external URLs as backtick-wrapped
inline code or plain text (e.g. docs.acme.com/en/dev_journey)
instead of clickable markdown links ([label](url)). Across a real vault
audit, 14 files had backtick-wrapped bare domains vs. exactly 1 real
markdown link in the entire wiki.

This isn't a rendering bug — Obsidian renders standard CommonMark
[text](url) links as clickable in both edit and reading views, same as
GitHub markdown. It's an ingestion-agent habit with no technical cause:

  • SKILL.md (skills/wiki-ingest/SKILL.md) has no guidance on link formatting
    in page prose at all.
  • The core tool (lint_engine.py) already anticipates external markdown
    links — its link parser special-cases absolute URIs and excludes them
    from dead-link checking — so nothing here discourages the syntax either.
  • The only URL-related instruction in the skill's provenance contract
    (wiki/references/provenance.md) is about the origin.locator field in
    ledger JSON — a structured-provenance concern, not page-body prose. That
    distinction appears to have generalized into "always treat URLs as
    literal/code" as a converged habit across independent ingestion sessions.

Fix applied

Added one instruction to SKILL.md's "Analyze before drafting" step 6:
render a citable URL in page prose as [descriptive label](url); reserve
backticks for literal code/CLI flags/identifiers, not citable URLs;
ledger/manifest locator fields are unaffected and keep the raw string.

Patch (against skills/wiki-ingest/SKILL.md):

@@ -80,7 +80,11 @@ new immutable capture or an honest ledger update, not an overwrite.
    be read completely, label the result partial and record the missing range.
 6. Extract source metadata, falsifiable claims, entities, concepts,
    contradictions, and open questions. Separate source statements from your
-   synthesis.
+   synthesis. When citing a URL in page prose, render it as a markdown link
+   (`[descriptive label](url)`) so it stays clickable; reserve backtick
+   code-spans for literal code, CLI flags, and exact identifiers, not for
+   citable URLs. This is about narrative prose only — locator fields inside
+   ledger/manifest records keep the raw string as-is.
 7. Reuse existing canonical pages and stable addresses. Request new addresses
    through `address_requests`; never call a counter allocator from a worker.

Why this matters

Backtick-wrapped/plain-text URLs in a knowledge-graph vault lose their
whole value as navigable citations — a reader can't click through to the
source without manually copying the string out. This compounds across
every ingestion pass since the habit is self-reinforcing (agents pattern-match
on existing page style).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions