Frontmatter and metadata

Metadata describes a fragment without being part of its main explanation. Usable stores important metadata as platform fields, and fragment authors can also place structured values in YAML frontmatter at the beginning of Markdown content.

Those two forms look similar in a UI or API response, but they serve different purposes. Understanding the difference prevents integrations from relying on fields that Usable itself does not interpret.

Platform-managed metadata

Usable manages fields that are part of the fragment resource. These commonly include:

• fragment ID and workspace ID;
• title and summary;
• fragment type;
• tags and collection memberships;
• author and timestamps;
• lifecycle status;
• optional workspace-scoped key;
• file relationships and symlink information where applicable.

These fields are used by Usable’s interfaces, permissions, filters, and APIs. Update them through the dashboard, MCP tools, or supported API operations rather than by writing similarly named values into the Markdown body.

YAML frontmatter

Frontmatter is a YAML block at the very beginning of Markdown, enclosed by --- lines. It lets authors and publishing integrations store structured, content-specific values.

---
audience: developers
productArea: authentication
reviewedAt: 2026-07-13
---

The Markdown body follows after the closing delimiter.

Usable extracts frontmatter so supported search and integration workflows can inspect it. However, a frontmatter key only has behavior when a specific tool or application is designed to use it.

For example, this documentation site reads fields such as:

---
slug: core-concepts/frontmatter-and-metadata
section: Core Concepts
order: 4
status: published
description: "A short description shown by documentation tooling."
---

Those fields control this docs publishing workflow. They are not universal instructions for every Usable workspace.

Do not duplicate platform fields

Writing tags, fragmentType, or workspaceId in frontmatter does not necessarily change the corresponding platform field. It may simply create custom frontmatter with the same name, leaving two conflicting values.

Prefer the native platform fields whenever Usable already models the information. Use frontmatter for domain-specific attributes or for a known integration contract.

For example:

• Use the native tags field for shared discovery labels.
• Use the native fragment type for the fragment’s role.
• Use frontmatter for audience, difficulty, or a publishing slug when your workflow recognizes those values.

Choose stable field names

Frontmatter becomes most useful when a workspace agrees on a small schema. Decide whether names use camel case or another convention, define expected value types, and document which system reads each key.

Avoid adding multiple aliases such as lastUpdated, last_updated, and updatedDate. They make queries and automation harder to maintain.

Dates should use an unambiguous ISO format:

reviewedAt: 2026-07-13

For values with a fixed vocabulary, document the accepted options rather than relying on free-form spelling.

Metadata and search

Structured list and query tools can filter platform metadata such as status, type, tags, and timestamps. Frontmatter can also be queried by supported interfaces when you need a custom field.

Semantic search works primarily from the meaning expressed by the fragment. Do not hide important facts only in frontmatter: explain them in the title, summary, or body when readers and AI need to understand them.

Example: an API guide

An API authentication guide might use:

• native type: Knowledge;
• native tags: api, authentication;
• native summary: what the guide explains;
• frontmatter: audience: developers, difficulty: intermediate;
• docs-specific frontmatter: slug, section, order, and publication status.

Each field has one clear owner and purpose.

Good practices

• Use native fields before inventing frontmatter equivalents.
• Add frontmatter only when a reader, query, or integration uses it.
• Keep a documented schema for repeated custom keys.
• Use consistent names and value types.
• Keep essential meaning in readable prose, not metadata alone.
• Never put secrets, tokens, or private credentials in frontmatter.

Related concepts

• Memory fragments explains the complete fragment anatomy.
• Tags and summaries covers two important native metadata fields.
• Search and retrieval explains semantic discovery and exact metadata filtering.