Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

80 Commits

Folders and files

Repository files navigation

Structured Context for Obsidian

Keep your content clean and your thinking clear.

This plugin brings inline validation to your structured markdown content — knowledge wikis, product/strategy frameworks (like Opportunity Solution Trees), and any schema-governed knowledge graph you maintain in Obsidian.

When you open or edit a file, the plugin checks it against your schema and highlights problems directly in the editor: missing required fields, invalid values, broken relationships, and rule violations — without leaving your notes.

Note: This plugin is desktop-only (requires Electron/Node APIs).

Installation

To install manually, download main.js, manifest.json and styles.css from the latest release into your vault's .obsidian/plugins/structured-context/ folder, or install it with BRAT.

Setup

  1. Enable the plugin in Obsidian settings.
  2. If your vault already has a .sctx.json at its root, or you use structured-context on the command line or in Claude Code, you're done: the plugin finds the same config.
  3. Otherwise open the plugin's settings and, under Spaces, add a space: a name, the vault folder that holds your content, and optionally a schema: a bundled or plugin schema, or a JSON file in your vault. Without a schema, the bundled strategy_general.json is used. This creates a .sctx.json at the vault root, which the command line and Claude Code read too.
  4. Open a markdown file in that folder.

Files outside every space are ignored. The settings page shows which config is in use and the spaces it defines.

What you'll see

  • Highlighted frontmatter lines for property-level issues (wrong value, missing required field, etc.), with an inline message showing what's wrong
  • A block panel below the frontmatter for document-level issues: broken links, hierarchy violations, rule violations, and duplicate titles

Issues are shown by severity, each with its own colour and symbol:

Severity Symbol Meaning
Error ✖ red The file fails validation
Warning ⚠ orange Worth fixing; the file still passes
Info ⓘ blue A suggestion

Validation runs when you open a file and after you edit it. Semantic (AI-judged) rules never run in the editor.

Map views

The Open map view command opens a pane that shows a space visually laid out based on its structure and a map view definition. Map views come from the map views library: the ones bundled with it, defined in a plugin, or your your own map-views/ folder alongside your config file.

Some map views can overlay validation results matching those shown in individual files.

Settings

Setting Description
Spaces The spaces of the config the command line finds; those outside this vault are dimmed. Add space (a name, a vault folder and an optional schema) saves to that config, or creates a .sctx.json at the vault root when there is none. When the config is elsewhere, such as your global one, Save to new vault-level config creates the vault's own .sctx.json instead, which then takes over from it. To rename, change or remove a space, edit the config file.
Validation debounce (ms) How long to wait after you stop editing before re-validating (default 1500). Increase it if validation feels slow on large content sets.

The config is the nearest .sctx.json from the vault folder upward, otherwise ~/.config/structured-context/config.json. Paths in a .sctx.json are relative to the folder that holds it, so "path": "." is the whole vault.

Files outside your vault

The plugin reads a config from outside the vault only when it finds one there: the nearest .sctx.json above the vault folder, or the global ~/.config/structured-context/config.json. It does this so the same spaces apply here, on the command line and in Claude Code. By default Add space creates a .sctx.json in your vault rather than touching those files. It writes to a config outside the vault only when that config is the one in use and you add a space without choosing Save to new vault-level config. Only notes in your vault are validated, but a config can also define spaces, or reference schema files, outside the vault. Those are read to validate a note (for example when a space folder contains your vault) and to draw the map view of such a space, which you pick by name. The plugin writes outside the vault only to that config.

Security

Only use configs and schemas you trust. Opening a vault validates its notes against whatever config the plugin finds (see above). Schema rules are JSONata expressions, and a crafted schema can run arbitrary code. A config can also declare plugins, which structured-context loads as JavaScript from a plugins/ folder next to the config file. Both run inside Obsidian with your user's permissions, so treat a shared or downloaded vault's .sctx.json, schemas and plugins/ folder like code. See structured-context's security notice.

Development

npm install              # install dependencies
npm run build            # build to dist/
npm run dev              # watch mode, rebuilds on change
npm run install-to-vault # copy dist/ to configured vault (requires install.json)
npm test                 # unit tests
npm run test:smoke       # after a build: install into a throwaway vault and validate fixture notes

To test your changes locally:

  1. Copy install.json.example to install.json and set your vault path
  2. Run npm run build && npm run install-to-vault
  3. Reload the Obsidian plugin

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages