Managing Knowledge Base Entries Using Wiki Layout with Markdown Frontmatter

The GoogleCloudPlatform/knowledge-catalog repository stores knowledge base entries as Markdown files with YAML frontmatter, combining structured metadata in the header with unstructured documentation in the body to create a version-controlled, wiki-style layout.

The Open Knowledge Format (OKF) defines this architecture for the Knowledge Catalog, automatically adopting the Documents layout when the scope is a knowledge-base (kb). This approach places each concept in a single file where machine-readable YAML frontmatter stores identifiers and taxonomy, while the Markdown body holds schemas, query examples, and descriptive text that humans edit directly.

How the Wiki Layout Structures Knowledge Base Entries

YAML Frontmatter Schema

Every knowledge base entry begins with a YAML block delimited by --- on its own line. According to okf/SPEC.md, the required keys are type, resource, title, description, tags, and timestamp. The frontmatter appears at the top of the file, followed by a second --- delimiter before the Markdown body begins.

In bundles/stackoverflow/tables/posts_tag_wiki.md, the frontmatter captures the resource identifier and categorization:

---
type: BigQuery Table
resource: https://bigquery.googleapis.com/v2/projects/bigquery-public-data/datasets/stackoverflow/tables/posts_tag_wiki
title: posts_tag_wiki
description: Tag wiki entries for Stack Overflow posts
tags: stackoverflow, tables, wiki
timestamp: '2026-07-14T12:00:00+00:00'
---

The specification allows additional keys to be added freely, as the parser treats unknown keys as opaque metadata, ensuring backward compatibility when extending the schema.

Markdown Body Content

The body of the file contains free-form Markdown that becomes the primary overview aspect (overview.content). This section typically includes a Schema definition, Common query patterns, and Citations. The content is rendered as HTML by the visualizer and ingested by LLM agents for context retrieval.

Following the frontmatter delimiter, the body in posts_tag_wiki.md (lines 10–71) contains technical documentation, SQL examples, and relationship descriptions that describe the table's usage patterns without affecting the structured metadata.

Directory Hierarchy and Index Files

Concepts are organized in logical bundles under bundles/<bundle>/. Each bundle contains a root index.md that serves as a navigation entry point. While concept files always contain frontmatter, index files are the only location where frontmatter may appear outside of concept files, and they require only the okf_version key.

The Stack Overflow bundle demonstrates this structure:

• bundles/stackoverflow/index.md – Bundle entry point with minimal frontmatter
• bundles/stackoverflow/tables/*.md – Individual table concepts
• bundles/stackoverflow/references/*.md – Minted reference documents from web enrichment

Creating Knowledge Base Entries

Manual Authoring

To create a new entry manually, create a .md file in the appropriate bundle subdirectory. The file must begin with the YAML frontmatter block followed by Markdown content:

---
type: BigQuery Table
resource: https://bigquery.googleapis.com/v2/projects/bigquery-public-data/datasets/stackoverflow/tables/example_table
title: Example Table
description: Demonstrates the wiki layout for knowledge base entries.
tags: stackoverflow, example, kb
timestamp: '2026-07-14T12:00:00+00:00'
---

# Schema

- `id`: INTEGER – Primary key.
- `name`: STRING – Human-readable name.

# Example query

```sql
SELECT id, name FROM `bigquery-public-data.stackoverflow.example_table`
WHERE name LIKE 'A%';

Save this as bundles/stackoverflow/tables/example_table.md. The OKF loader in okf/src/reference_agent/tools/bundle_tools.py automatically parses the frontmatter when indexing the bundle.

Automated Enrichment with the Reference Agent

The reference agent automates document creation and updates through the write_concept_doc(concept_id, frontmatter, body) function defined in okf/src/reference_agent/prompts/web_ingestion_instruction.md. When enriching existing entries, the agent:

1. Reads the current Markdown file
2. Preserves all existing frontmatter keys verbatim
3. Merges new metadata keys without overwriting existing values
4. Appends enriched content to the body

Run the enrichment process via CLI:

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset bigquery-public-data.stackoverflow \
    --concept tables/example_table \
    --web-seed-file seeds.txt \
    --out ./bundles/stackoverflow

This ensures that manual edits to the frontmatter survive automated updates, maintaining the integrity of custom tags and descriptions.

Loading and Parsing Concept Files

The repository provides implicit parsing logic that external tools can replicate. The standard approach splits the file on the --- delimiter to separate metadata from content:

import yaml
from pathlib import Path

def load_concept(path: Path):
    text = path.read_text()
    front, body = text.split('---', 2)[1:3]   # split into front-matter & body

    metadata = yaml.safe_load(front)
    return metadata, body.strip()

metadata, body = load_concept(Path('okf/bundles/stackoverflow/tables/posts_tag_wiki.md'))
print(metadata['title'])
print(body[:200])

The okf/src/reference_agent/visualizer/generator.py implementation uses this pattern to display frontmatter fields side-by-side with the rendered Markdown body in the interactive HTML viewer.

Summary

• The wiki layout in GoogleCloudPlatform/knowledge-catalog uses YAML frontmatter for structured metadata and Markdown for documentation, stored in bundles/<bundle>/*.md files.
• Required frontmatter keys include type, resource, title, description, tags, and timestamp, delimited by --- markers.
• The reference agent preserves existing frontmatter during automated updates via write_concept_doc, ensuring manual edits persist.
• Index files (index.md) serve as bundle entry points and are the only files besides concept documents that may contain frontmatter.
• The visualizer (generator.py) and ingestion tools parse these files by splitting on the --- delimiter and using yaml.safe_load for metadata extraction.

Frequently Asked Questions

What are the required YAML frontmatter keys for a knowledge base entry?

The OKF specification requires six keys: type (the resource category), resource (the canonical URI), title (display name), description (summary), tags (comma-separated labels), and timestamp (ISO 8601 datetime). These must appear between the --- delimiters at the top of the Markdown file.

How does the reference agent handle existing frontmatter when updating entries?

According to the prompt in web_ingestion_instruction.md, the agent calls write_concept_doc to read the existing file, copy the type field verbatim, and merge any new frontmatter keys while preserving all existing keys. This prevents automated processes from overwriting manual metadata edits.

Can I add custom metadata fields to the YAML frontmatter?

Yes. The OKF parser treats unknown keys as opaque metadata, allowing you to extend the schema with custom fields without breaking existing consumers. This extensibility is defined in okf/SPEC.md and supported by the parsing logic in bundle_tools.py.

What is the difference between index.md and concept files in the wiki layout?

Concept files (e.g., tables/posts_tag_wiki.md) contain full frontmatter with all required keys and represent individual data assets. Index files (index.md) serve as bundle entry points and are the only files permitted to contain frontmatter outside of concept files, requiring only the okf_version key to define the schema version.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}