Settings

An OKF bundle can keep OKForest settings in one optional file, .okforest/settings.yaml, inside the bundle’s root folder: the folder that holds the bundle’s root index.md. It names the bundle and says which markdown files are not concepts. It is an OKForest convention, not part of the Open Knowledge Format. It is YAML, not markdown, so OKF tools never mistake it for a concept.

okforest init creates the file, and the okforest/settings rule checks it whenever you validate the bundle.

Where the file goes

Each bundle has its own settings file, next to its root index.md. A repository can hold several bundles, as in the OKF specification’s bundles/finance/ example:

acme-knowledge/                   the repository
  README.md                       outside every bundle
  bundles/
    finance/                      an OKF bundle's root folder
      .okforest/settings.yaml     settings for the finance bundle
      index.md                    the bundle's root index
      metrics/income-statement.md
      computations/revenue.md
    sales/                        another bundle, with its own settings
      .okforest/settings.yaml
      index.md
      policies/discounts.md

Validate each bundle with its root folder as the path (okforest validate bundles/finance, or the GitHub Action’s path input). Validation reads only the settings file in that folder, never one above or below it.

When the whole repository is one bundle, its root folder is the repository’s root, so the file sits at the top, next to the root index.md. Repository files such as README.md are then inside the bundle, which is why ignore usually lists them.

Example

.okforest/settings.yaml

name: Sales knowledge
description: Pricing, discounts, and deal desk policies for the sales team.
ignore:
  - README.md
  - drafts/

Settings

Every setting is optional.

name

Text, at most 100 characters, such as Sales knowledge. The bundle’s display name: OKForest’s browser shows it as the title of the bundle’s home page. Without it, the browser uses the tree’s short name.

description

Text, at most 4,000 characters. What the bundle covers. The browser shows it under the name on the bundle’s home page.

ignore

A list of globs: markdown files that are not concepts (see below).

Other keys

OKForest ignores settings it doesn’t know, so a misspelled key would lose its setting. The okforest/settings-keys rule warns about them and suggests the likely key (nmae: did you mean name?), and so does your editor with the schema.

Files that are not concepts

In OKF, every markdown file in a bundle is a concept, except index.md and log.md. OKForest also leaves out files under .okforest/ and .git/, and nothing else, so repository files such as README.md and CONTRIBUTING.md, and markdown under .github/, are concepts until ignore lists them. A concept needs frontmatter with a type, so validation reports any of them that has none.

ignore globs are relative to the bundle’s root, where * matches within one folder name, ** across folders, and ? one character. A pattern ending in / matches everything under that folder.

ignore:
  - README.md           # one file at the root
  - drafts/             # everything under drafts/
  - "**/notes-*.md"     # notes-*.md in any folder

Ignored files stay in the repository, and links to them still work; validation, the browser, and the MCP server just don’t treat them as concepts.

File name and format

• The file must be named exactly .okforest/settings.yaml. The .yml spelling is not read, and validation reports a .okforest/settings.yml as an error so it doesn’t go unnoticed.
• It is YAML: one mapping of the settings above. Quote values that contain :, #, or start with *, as in the ignore example.
• Changes take effect at the next commit OKForest reads.

Editor support

A JSON Schema describes the file, so editors can complete setting names, explain each one (with a link to this page), and flag mistakes as you type. Editors that use the YAML language server, such as Visual Studio Code with Red Hat’s YAML extension, read it from a comment on the file’s first line, which okforest init writes:

# yaml-language-server: $schema=https://www.okforest.ai/schemas/settings.schema.json
name: Sales knowledge

The same schema ships in the @okforest/validate package (@okforest/validate/settings.schema.json), and the CLI’s tests keep it in step with validation, so the editor and okforest validate always agree.