Generic OKF: links and backlinks¶

In this tutorial, you will connect two documents and let okf-schema generate the reverse relationship. This creates a two-document graph.

This optional exercise covers generic OKF mechanics. For Findings, knowledge roles, synthesis and agent maintenance, use the self-contained OKFKB tutorial; you do not need to complete this page first.

Time: about 10 minutes

Prerequisite: Complete Create and Validate Your First OKF Bundle. The commands below use the bundle created there.

Create a second document¶

The existing api/health-check.md document describes an endpoint. Add a runbook that explains what to do when that endpoint reports a problem:

okf-schema new --path my-knowledge-base/bundle \
    --name runbooks/service-unavailable \
    --type Runbook \
    --title "Service Unavailable"

Open my-knowledge-base/bundle/runbooks/service-unavailable.md and add:

# Service Unavailable

Check the [health endpoint](../api/health-check.md) before restarting the
service.

The ordinary Markdown link is the authored relationship. Its surrounding sentence explains why the documents are related.

Instead of editing manually, tell your coding agent:

Use the okf-schema skill to create a Service Unavailable runbook in the current bundle. Link it to api/health-check.md, explain why the operator follows that link, then lint and validate the bundle.

The prompt states the relationship’s meaning; the skill handles valid paths, frontmatter, and generated link metadata.

Generate graph metadata¶

Run the linter:

okf-schema lint --path my-knowledge-base/bundle

The linter resolves internal links and updates two generated frontmatter fields:

links lists documents referenced by the current document.
backlinks lists documents that reference the current document.

The runbook now has an outgoing link similar to:

links: [api/health-check.md]
backlinks: []

The health-check document receives the reverse edge:

links: []
backlinks: [runbooks/service-unavailable.md]

Do not edit these generated lists by hand. Edit Markdown links in document bodies and run lint again.

Follow the relationship¶

Ask which documents depend on the health-check document:

okf-schema backlinks --path my-knowledge-base/bundle api/health-check

This is useful before renaming, deleting, or substantially changing a document. It shows which other knowledge may need review.

Inspect the runbook to see its outgoing links:

okf-schema show --path my-knowledge-base/bundle runbooks/service-unavailable

Check the result¶

Refresh indexes and validate the bundle:

okf-schema index --path my-knowledge-base/bundle
okf-schema validate --path my-knowledge-base/bundle --strict

You now have a two-document graph with an authored link and a generated backlink.

If a link is unresolved¶

Check the path from the file containing the link. The runbook is one directory below the bundle root, so it uses ../api/health-check.md, not api/health-check.md. Keep the .md suffix in Markdown body links.

Run lint after correcting the path, then validate again.

Next steps¶

Lint Before Commit keeps graph metadata in sync automatically.
Python API Reference covers custom graph analysis.
Design Principles explains the graph model and guidance for document size and linking.
Build and maintain an evidence-based knowledge base introduces the distinct OKFKB lifecycle in one walkthrough.