# Managing Knowledge Base Entries Using Wiki Layout with Markdown Frontmatter

> Learn to manage knowledge base entries with a wiki layout using Markdown frontmatter in the GoogleCloudPlatform/knowledge-catalog repository. Combine structured metadata and documentation.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/bundles/stackoverflow/tables/posts_tag_wiki.md), the frontmatter captures the resource identifier and categorization:

```yaml
---
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```markdown
---
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:

```bash
.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:

```python
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/index.md)) serve as bundle entry points and are the only files besides concept documents that may contain frontmatter.
- The **visualizer** ([`generator.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) and supported by the parsing logic in [`bundle_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/tables/posts_tag_wiki.md)) contain full frontmatter with all required keys and represent individual data assets. Index files ([`index.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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.