Configs on Katalyst Documentation

Discovery

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

Discovery#

Katalyst reads a .katalyst/ directory, found by walking upward from the current working directory to the nearest ancestor that contains one. That ancestor is the repo root; all relative paths resolve against it.

Discovery resolves symlinks on both the root and the input path, because on macOS $TMPDIR lives behind /var to /private/var and relative-path resolution would otherwise produce garbage.

Layout#

.katalyst/
 config.yaml # optional: listing defaults and discovery settings
 schemas/ # one JSON Schema file per named schema
 book.json
 bases/ # one file per base
 local.yaml # a base + the collections it declares
 local/ # optional: one file per collection (escape hatch)
 books.yaml

By default, schemas and bases are discovered by convention: every file under schemas/ is a schema whose name is its filename stem (book.json -> book), and every file under bases/ is a base named for its filename stem (local.yaml -> local). config.yaml is optional; it carries listing defaults and can switch a kind to explicit discovery, listing definitions inline instead of as files.

Schemas

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

Schemas#

Each file under .katalyst/schemas/ is a JSON Schema. Its name, the filename stem, is the stable public handle used by schema get <name>, by an inline schema: <name> key in a document’s frontmatter, and by a collection’s schema: shorthand. The path can move; the name should not.

Schemas are stored flat; the check library that compiles a schema is determined by the referencing check type’s kind (the object check uses JSON Schema).

Bases

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

Bases#

A base is one configured backend store, plus the collections it maps onto the domain model. Each file under .katalyst/bases/ is one base, named for its filename stem. There is no implicit base; katalyst init writes a default local one.

Key	Required	Default	Meaning
`type`	no	`filesystem`	Backend kind: `filesystem` or `sqlite`.
`root`	no	`.`	Base root directory, relative to the repo root. Collection paths resolve against it.
`path`	for `sqlite`	-	SQLite database path, relative to the repo root. Alias for `root` on SQLite bases.
`collections`	no	-	Map of collection name -> definition. See Collections.

# .katalyst/bases/local.yaml
type: filesystem
root: .
collections:
 books:
 path: notes/books
 schema: book
 checks:
 - kind: markdown_title_matches_h1

Collection names are unique across the whole project (selectors are <collection>/<item>, with no base qualifier).

Collections

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

Collections#

A collection is a directory of items plus the checks every item must pass. Collections are declared inside their base, under collections:.

Key	Required	Default	Meaning
`path`	no	the collection name	Directory, relative to the base `root`.
`pattern`	no	`*.md`	Filename glob selecting items in the directory.
`table`	for `sqlite`	-	SQLite table backing the collection.
`id`	for `sqlite`	-	SQLite column that provides item identity.
`attributes`	no	all scalar columns except `id` and `content.column`	SQLite column captures exposed as item attributes.
`content`	no	-	Optional SQLite content mapping, with `kind: text` or `kind: markdown` and `column: <name>`.
`schema`	no	-	Schema name; shorthand for a leading `object` check.
`checks`	no	-	List of checks. See Checks.
`listing`	no	-	`item list` listing defaults for this collection. See Listing.

A collection must configure at least one check: set schema, or provide a non-empty checks list, or both. Files in the directory that do not match pattern are reported as errors.

Checks

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

Checks#

Each entry in a collection’s checks: list has a kind and the keys that check type requires. Every check type is documented one per page in the check types reference:

checks:
 - kind: object
 schema: book
 - kind: object_field_type
 field: year
 type: integer
 - kind: markdown_title_matches_h1
 - kind: filesystem_name_matches_field

Text rules#

The text_* check types lint the item body as raw text, independent of markdown structure, and also apply to plain-text items (a .txt file or a markdown file with no frontmatter). Each is evaluated against a set of spans chosen by target:

Variants

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

Variants#

A collection runs its base schema/checks against every item. Variants let it run extra checks on a subset, chosen by the item’s metadata. Each entry in a collection’s variants: list has a when discriminator and its own schema/checks:

pages:
 path: docs/content
 pattern: "**/*.md"
 schema: page # base: every page needs a title
 variants:
 - when: "bookCollapseSection" # section landing pages have this flag
 schema: section_index
 - when: "!bookCollapseSection" # every other page is a content page
 schema: content_page
 checks:
 - kind: object_required_field
 field: weight
 - kind: markdown_requires_h1
 useExhaustiveVariants: false # default

when is a list of item list --filter predicates (field=value, field>=n, field=~regex, !field, …), evaluated against the item’s frontmatter. All entries must hold (AND). Three shapes are accepted, the first two desugaring to the third:

Listing

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

Listing#

Two item list behaviors have configurable defaults. A listing: block sets them project-wide in .katalyst/config.yaml, and a collection’s file can override either key for that collection.

Key	Values	Default	Meaning
`filterTypeMismatch`	`skip` / `error`	`skip`	A `--filter` comparison against an incompatible type either skips the item or exits 2.
`sortMissing`	`last` / `lowest`	`last`	Where items lacking the `--sort` key land: at the end (both directions), or below any present value.

# .katalyst/config.yaml - project default
listing:
 filterTypeMismatch: skip
 sortMissing: last

# under a base's collections: override for one collection
books:
 path: notes/books
 schema: book
 listing:
 filterTypeMismatch: error

Resolution is highest-precedence first: the --on-type-mismatch / --sort-missing flags, then the collection’s listing:, then the project listing:, then the built-in default. An unset key falls through to the next level.