Content filtering

Open Knowledge respects your .gitignore files and combines them with config-based patterns to determine which files belong in the document system. Exclusion always supersedes inclusion.

How it works

Symlinks inside the content directory are followed transparently -- they participate in the document system like regular files. Cyclic symlinks are detected and skipped; symlinks that resolve outside the content directory are excluded.

Two sources of exclusion are combined:

• .gitignore files -- root and nested, auto-discovered via a two-pass bootstrap
• content.exclude patterns from config

These are gated by content.include patterns (default: ["**/*.md"]) -- only files matching the include globs are considered, then exclusion rules remove files from that set.

Include patterns

Set content.include in .open-knowledge/config.yml to control which files enter the document system. The default is ["**/*.md"] -- only markdown files.

content:
  include:
    - "**/*.md"
    - "**/*.mdx"

A file must match at least one include pattern to be considered.

Exclude patterns

Exclusion rules come from two sources, and both are applied together.

.gitignore rules

Open Knowledge loads the root .gitignore at the project directory, then walks subdirectories to discover nested .gitignore files. The walk skips directories already excluded by the root .gitignore, so it never traverses node_modules/ or similar trees.

Config excludes

content.exclude in .open-knowledge/config.yml adds patterns on top of gitignore rules. These patterns are relative to the content directory.

content:
  exclude:
    - "drafts/**"
    - "archive/**"

Resolution rules

1. A file must match at least one content.include pattern
2. Gitignore rules (root + nested) and content.exclude patterns are checked
3. If any exclusion rule matches, the file is excluded -- exclusion always wins
4. Directories are checked against exclusion rules only (not include patterns) for traversal decisions

Example

Given a project with:

.gitignore contains: node_modules/, dist/, *.log

content:
  include:
    - "**/*.md"
  exclude:
    - "drafts/**"

The results:

Previewing content scope

To see exactly which files match your current include/exclude rules:

npx @inkeep/open-knowledge preview

This is read-only -- it doesn't write anything or start a server. It uses the same ContentFilter as the file watcher, so the output matches what the editor sidebar will show.

Works before init (uses schema defaults) and after config edits.

Performance