Skip to content
Codex
Documentation GitHub
Editor

Wiki-Links & Backlinks

Wiki-Links & Backlinks

Validates the full wiki-link lifecycle in Inklings: creating [[wiki-links]] via the autocomplete trigger, clicking a link to navigate, ghost-link styling for links pointing at non-existent pages, backlink and outgoing-link visibility in the page detail panel, circular link navigation, special characters in page names, and rename-driven link propagation. Wiki-links are a core power-user feature that connects pages into a knowledge graph; correctness here is critical for navigation integrity and reference tracking.

Preconditions

  • Vite dev server running on http://localhost:1420
  • A workspace exists and is open

Scenarios

Seed: seed.spec.ts

1. Create a wiki-link via [[ trigger

Verify that typing [[ in the editor opens the wiki-link autocomplete popup.

Steps:

  1. Open a page (or create one titled “Source Page”).
  2. Click into the editor body.
  3. Type [[.

Expected: An autocomplete dropdown appears listing existing pages. The dropdown is dismissible by pressing Escape.

2. Select a page from the autocomplete and insert the link

Verify that selecting a page from the wiki-link autocomplete inserts a rendered link node.

Steps:

  1. Ensure a second page titled “Target Page” already exists in the sidebar.
  2. On “Source Page”, click into the editor body and type [[ to open the autocomplete.
  3. Continue typing “Target” to filter the list.
  4. Press Enter or click “Target Page” in the dropdown.

Expected: A wiki-link pill labeled “Target Page” is inserted inline in the editor at the cursor position. The autocomplete dropdown closes. The pill is visually styled differently from plain text.

3. Click a wiki-link to navigate to the target page

Verify that clicking a rendered wiki-link pill navigates to the linked page.

Steps:

  1. On “Source Page”, insert a wiki-link to “Target Page” as in scenario 2.
  2. Wait for the save indicator to show “Saved”.
  3. Click the “Target Page” link pill in the editor.

Expected: The app navigates to “Target Page”. The sidebar selection updates to highlight “Target Page”. The editor body shows the content of “Target Page”.

Verify that wiki-links pointing to pages that do not exist receive ghost (unresolved) visual styling.

Steps:

  1. Open any page and click into the editor body.
  2. Type [[ to open the autocomplete, then type a name that does not match any existing page (for example “Phantom Page”) and press Enter to insert it, or dismiss the dropdown and manually type a wiki-link referencing a non-existent page.
  3. Wait a moment for link resolution to complete (approximately 500–700 ms after the last keystroke).

Expected: The link pill for the non-existent page is rendered with ghost styling — visually dimmed, dashed border, or otherwise visually distinct from a resolved link. No navigation error or app crash occurs.

5. Ghost link resolves when the target page is created

Verify that a ghost link transitions to normal link styling after the missing target page is created.

Steps:

  1. Insert a wiki-link to “Future Page” on an existing page and observe the ghost styling.
  2. Create a new page titled “Future Page” via the sidebar (click the new page button, enter the title).
  3. Navigate away from the current page, then navigate back to the page containing the link.

Expected: After the round-trip, the “Future Page” link pill renders without ghost styling, indicating the link is now resolved to a real page.

6. Backlinks for a page are visible in the page detail panel

Verify that the page detail panel lists pages that contain wiki-links pointing to the current page.

Steps:

  1. Ensure “Source Page” contains a wiki-link to “Target Page” (as established in scenario 2). Wait for “Saved”.
  2. Navigate to “Target Page”.
  3. Open the page detail panel (side panel showing metadata, backlinks, outgoing links).

Expected: The backlinks section of the detail panel lists “Source Page” as a page that links to “Target Page”.

7. Page with no backlinks shows an empty backlinks list

Verify that the page detail panel shows an empty backlinks section for a page that no other page links to.

Steps:

  1. Create a new page titled “Isolated Page” with plain text body containing no wiki-links to or from other pages.
  2. Wait for “Saved”.
  3. Open the page detail panel for “Isolated Page”.

Expected: The backlinks section of the detail panel is empty or displays a “no backlinks” message. No error is shown.

8. Outgoing links from a page are visible in the page detail panel

Verify that the page detail panel lists all wiki-links that exist within the current page’s content.

Steps:

  1. On “Source Page”, insert wiki-links to both “Target Page” and a second existing page “Another Target”.
  2. Wait for the save indicator to show “Saved”.
  3. Open the page detail panel for “Source Page”.

Expected: The outgoing links section of the detail panel lists both “Target Page” and “Another Target”.

9. Page with no outgoing links shows an empty outgoing links list

Verify that the page detail panel shows an empty outgoing links section for a page with no wiki-links in its body.

Steps:

  1. Create a new page titled “No Links Page” and type plain text body without any [[ wiki-links.
  2. Wait for “Saved”.
  3. Open the page detail panel for “No Links Page”.

Expected: The outgoing links section of the detail panel is empty or shows a “no outgoing links” message. No error is shown.

10. Circular links — A links to B, B links to A

Verify that mutually-linking pages do not cause infinite loops, crashes, or incorrect backlink display.

Steps:

  1. Create a page titled “Node A”. In its editor body, type [[ and insert a wiki-link to “Node B” (you may need to create “Node B” first, then return to “Node A” to insert the link).
  2. Create a page titled “Node B”. In its editor body, type [[ and insert a wiki-link to “Node A”.
  3. Wait for both pages to show “Saved”.
  4. Open the page detail panel for “Node A” and observe the backlinks section.
  5. Click the “Node B” wiki-link pill in “Node A” to navigate to “Node B”.
  6. Click the “Node A” wiki-link pill in “Node B” to navigate back to “Node A”.

Expected:

  • The page detail panel for “Node A” shows “Node B” as a backlink, and vice versa.
  • Navigation between both pages completes without error. No crash, infinite loop, or redirect cycle occurs.

Verify that a link referencing a heading anchor scrolls the target page to that heading.

Steps:

  1. Create a page titled “Long Page” with at least two H2 headings: “First Section” and “Second Section”, with enough body text between them that the second heading is not visible without scrolling.
  2. On another page, type [[ and insert a wiki-link targeting “Second Section” in “Long Page” (if the autocomplete supports fragment selection, choose it; otherwise the link pill may need to be inserted referencing the heading anchor).
  3. Wait for “Saved”.
  4. Click the wiki-link pill.

Expected: The app navigates to “Long Page” and the view scrolls so that the “Second Section” heading is visible near the top of the editor content area.

12. Wiki-link with special characters in the page name

Verify that page names containing apostrophes, hyphens, or parentheses are handled correctly.

Steps:

  1. Create a page titled “Hero’s Journey (Revised)”.
  2. On another page, click into the editor body and type [[, then type “Hero’s Journey” to filter the autocomplete.
  3. Select “Hero’s Journey (Revised)” from the dropdown.

Expected: A wiki-link pill labeled “Hero’s Journey (Revised)” is inserted. Clicking the pill navigates to the correct page.

13. Wiki-link display text can differ from the page title

Verify that the display text of a link can be different from the target page’s actual title.

Steps:

  1. On a page, type [[ and insert a link to “Target Page” so the pill appears with the default label “Target Page”.
  2. Navigate away and back to confirm the default label.
  3. If the editor supports inline editing of the display text (by clicking the pill to edit it), change the display label to “Custom Display” while keeping the target as “Target Page”.

Expected: The wiki-link pill displays “Custom Display” as its label but clicking it still navigates to “Target Page”. If inline editing of display text is not supported via the UI, this scenario documents the expectation only.

14. Rename page updates all linking pages

Verify that renaming a page propagates the new name to wiki-link pills in all pages that linked to it.

Steps:

  1. Ensure “Source Page” contains a wiki-link to “Target Page”. Wait for “Saved”.
  2. In the sidebar, click on “Target Page” to open it.
  3. Click on the page title field at the top of the editor.
  4. Edit the title from “Target Page” to “Renamed Target” and press Enter or click away to confirm.
  5. Wait for the rename to complete (the sidebar should reflect the new name).
  6. Navigate to “Source Page”.

Expected: The wiki-link pill in “Source Page” that previously pointed to “Target Page” now displays “Renamed Target” (or its label has been updated to reflect the new name). Clicking the pill still navigates correctly.

15. Rename dialog shows the impact count before confirming

Verify that the rename confirmation dialog or preview shows how many pages contain links that will be updated.

Steps:

  1. Ensure at least two pages (“Page One” and “Page Two”) both contain wiki-links to “Target Page”. Wait for both to show “Saved”.
  2. Navigate to “Target Page” and click on its title field to begin renaming.
  3. Type a new title “New Target Name” — observe whether a preview or confirmation dialog appears showing how many links will be updated.

Expected: Before the rename is committed, a dialog, tooltip, or inline preview shows that 2 pages contain links that will be updated. The rename can be confirmed or cancelled from this dialog.

16. Rename a page with no backlinks succeeds cleanly

Verify that renaming a page that no other page links to completes without error.

Steps:

  1. Create a page titled “Solo Page” with body text but no incoming wiki-links from other pages.
  2. Click on the title field and rename it to “Renamed Solo Page”. Confirm the rename.

Expected: The rename completes without error. The sidebar shows the new title “Renamed Solo Page”. No dialog indicates any link updates were needed (0 links affected).

17. Rename to a title with special characters

Verify that renaming a page to a title containing apostrophes or special characters produces a valid slug and the page remains accessible.

Steps:

  1. Create a page titled “Plain Name”.
  2. Click on the title field and rename it to “O’Brien & Associates”. Confirm the rename.

Expected: The rename completes without error. The page is accessible in the sidebar under its new title “O’Brien & Associates”. Clicking it opens the page correctly.

18. Rename to an already-existing title shows a conflict error

Verify that attempting to rename a page to the title of another existing page shows an appropriate error and does not proceed.

Steps:

  1. Ensure pages “Alpha” and “Beta” both exist in the workspace.
  2. Navigate to “Beta” and click on its title field to rename it.
  3. Type “Alpha” as the new title and press Enter or click away to confirm.

Expected: An error message or inline validation warning appears indicating that a page named “Alpha” already exists. The rename is not applied — “Beta” retains its original title.

19. Metadata updates after rename are reflected in the page detail panel

Verify that after a rename, the page detail panel and sidebar show the new title.

Steps:

  1. Rename “Target Page” to “Updated Target” by clicking its title field and editing it. Confirm the rename.
  2. Open the page detail panel for the renamed page.

Expected: The detail panel shows the new title “Updated Target”. The sidebar reflects the new name. The old title “Target Page” no longer appears anywhere in the UI for this page.

Test Data

KeyValueNotes
source_page_titleSource PagePage that contains outgoing links
target_page_titleTarget PagePrimary link target in most scenarios
ghost_page_namePhantom PageDoes not exist — tests ghost link styling
heading_page_titleLong PagePage with multiple H2 headings for scenario 11
special_char_titleHero’s Journey (Revised)Tests special character handling in scenario 12
circular_a_titleNode ACircular link participant A
circular_b_titleNode BCircular link participant B
conflict_title_aAlphaExisting page for conflict rename test
conflict_title_bBetaPage to be renamed to conflict in scenario 18

Notes

  • The wiki-link format used by Inklings is [[Display Text|target-slug]] (pipe-separated). The [[ trigger in the editor opens the autocomplete; selecting a result inserts the full wiki-link node.
  • Ghost link resolution is debounced at 500 ms in InklingsEditor.tsx (resolutionTimerRef). Steps checking ghost state should wait at least 700 ms after any content change.
  • The WikiLink TipTap extension renders as <span class="wiki-link-pill">. Ghost state adds the wiki-link-pill--ghost CSS class, which produces the distinct visual styling.
  • Heading fragment links store the full slug including # (e.g., long-page#second-section). The click handler splits on # to extract the page slug and heading anchor for scroll-to behavior.
  • Rename propagation updates wiki-link display text and slugs in all linking pages. The rename dialog shows the count of affected links before confirming.

Was this page helpful?