Data surfaces on Katalyst Documentation

File metadata

Mon, 01 Jan 0001 00:00:00 +0000

File metadata#

File metadata is the data surface derived from an item’s filesystem reference. It does not parse item content; it reads names, extensions, parent directories, path segments, and path depth from where the item lives.

Terms#

Term	Meaning
File metadata	Attributes derived from an item’s path or filesystem reference.
Filename	The basename of the item path.
Extension	The suffix used to classify the file’s format, such as `.md` or `.txt`.
Parent directory	The directory immediately containing the item.
Path depth	The number of directory levels between the collection root and the item.

Model#

File metadata belongs to the item because the item’s reference can carry meaning: a file’s name may need to match a field, an extension may need to be allowed, or a collection may require one index file per directory.

Plain text

Mon, 01 Jan 0001 00:00:00 +0000

Plain text#

Plain text is the body content read as raw text. It ignores markdown structure and treats the selected span as text to match with regular expressions or literal denylist entries.

Terms#

Term	Meaning
Plain text	The body surface interpreted as raw text.
Body	The content being searched. For markdown files, this excludes frontmatter.
Span	The slice of body text a text check evaluates: the whole body, each line, the first line, or matched lines.
Target	The configured span selector for a text check.

Model#

Plain-text checks run against body text, not structured metadata and not markdown syntax trees. For markdown items, the body comes from the Markdown body text view after frontmatter has been separated. For plain-text items, the whole item body is the text surface.

Markdown body text

Mon, 01 Jan 0001 00:00:00 +0000

Markdown body text#

Markdown body text is the data surface produced from a markdown-like file with optional structured frontmatter. The codec lives in internal/codec/markdownbodytext; it turns bytes on disk into structured metadata plus body bytes that checks, inspectors, and fix can share.

Terms#

Term	Meaning
Markdown body text	The parsed markdown file-form exposed as a data surface: optional structured frontmatter, body bytes, source format, and source-line lookup.
Frontmatter	The structured metadata block at the top of a markdown file, in YAML, TOML, or JSON.
Body	Everything after the closing frontmatter fence. If there is no frontmatter, the whole file is the body.
Document	The in-memory representation returned by `markdownbodytext.Parse`.
Metadata	The parsed frontmatter shape, normalized to `map[string]any`.
Source line map	A JSON-pointer-path to 1-indexed source line lookup used for locatable violations.

Model#

The unit of work is a file on disk with two possible regions:

Structured object

Mon, 01 Jan 0001 00:00:00 +0000

Structured object#

Structured object is the data surface that exposes named fields and values. Today, for filesystem markdown collections, it comes from parsed frontmatter metadata. The domain-model term is broader on purpose: future bases may provide rows, documents, or API resources directly as structured objects.

Terms#

Term	Meaning
Structured object	A map-like representation of an item’s structured data.
Field	A key in the structured object. A field is an attribute; not every attribute is a field.
Metadata	The parsed markdown frontmatter shape used as the structured object today.
Schema directive	The inline `schema:` key that opts an item into a named schema before validation.

Model#

In the current filesystem backend, the structured-object surface is Document.Meta from Markdown body text. It is normalized to map[string]any no matter whether the source frontmatter was YAML, TOML, or JSON.