# YAML Creator

YAML Creator is a local-first [Obsidian](https://obsidian.md) community plugin for creating, organizing, and reusing note properties without hand-editing frontmatter.

Open one focused popup to edit every property in the current Markdown note, add values discovered elsewhere in your vault, or merge a path-aware template. Nothing is written until you select **Apply**.

## Features

- Add, rename, edit, reorder, and delete any top-level YAML property.
- Edit text, numbers, booleans, dates, date-times, empty values, scalar lists, and nested YAML.
- Add, remove, and reorder individual list values such as tags and aliases.
- Reuse pinned, recently used, and vault-discovered categories and values.
- Pin a suggestion with its star button, right-click, or touch long-press.
- Create ordered templates and suggest them using vault-relative path patterns.
- Detect frontmatter changes made after the popup opened before writing.
- Use the same responsive interface on Obsidian desktop and mobile.
- Keep vault data private: no accounts, network requests, advertising, or telemetry.

## Terminology

- A **category** is a top-level property key such as `title`, `aliases`, or `tags`.
- A **value** is the content stored in a category. A list category can contain several values.
- In the `tags` category, YAML Creator accepts `#project` in the interface and stores the Obsidian-compatible value `project`.

## Usage

1. Open a Markdown note.
2. Select the braces icon in the ribbon, or run **YAML Creator: Open editor** from the command palette.
3. Edit the current categories, select a suggestion, or merge a matching template.
4. Select **Apply** to write the staged properties. Select **Cancel** to leave the note unchanged.

Each category has controls to pin, move, or delete it. List values have the same controls and can be dragged into order. **Advanced YAML** accepts nested maps and lists and reports syntax errors inline.

### Concurrent edits

The popup is locked to the note that was active when it opened. Before applying, YAML Creator compares that note's current frontmatter with the version originally loaded. If another editor or plugin changed it, the write stops and the popup offers **Reload file**.

## Templates

Templates are managed under **Settings → Community plugins → YAML Creator**. Every template has:

- A display name.
- One or more vault-relative path globs.
- An ordered YAML mapping of properties.

Supported glob tokens are `*` for characters within one path segment, `**` for any number of folders, and `?` for one character.

Example template:

```yaml
status: draft
tags:
  - project
aliases: []
priority: 2
```

Example patterns:

```text
Projects/**/*.md
Areas/Work/*.md
Daily/202?-*.md
```

Matching templates appear at the top of the editor, but they are never applied automatically. A merge adds missing properties, preserves existing scalar and nested values, and appends only unique list values.

## Suggestions and settings

YAML Creator builds suggestions from Obsidian's metadata cache. It does not read every note body to create the index.

Suggestion order is:

1. Pinned items.
2. Recently applied items.
3. Other vault items by frequency and name.

Existing categories and values are omitted. Only scalar values and scalar lists become value suggestions; nested structures remain editable through Advanced YAML.

Recent suggestions are enabled by default. Settings let you show 1–50 recent items, disable recent recording/display, clear history, clear pins, and manage templates. Disabling recents retains the existing history until it is explicitly cleared.

## Installation

### Community plugins

After YAML Creator is accepted into the Obsidian community directory:

1. Open **Settings → Community plugins**.
2. Select **Browse**, search for **YAML Creator**, and install it.
3. Enable the plugin.

### Manual installation

1. Download `main.js`, `manifest.json`, and `styles.css` from the release matching the version you want.
2. Create `<Vault>/.obsidian/plugins/yaml-creator/`.
3. Copy the three files into that folder.
4. Reload Obsidian and enable **YAML Creator** under **Community plugins**.

## Development

Requirements: a current Node.js LTS release and npm.

```bash
npm install
npm run dev
```

For local testing, place or clone the repository at `<Vault>/.obsidian/plugins/yaml-creator/`. The development process watches TypeScript sources and emits `main.js` at the repository root.

Run all automated checks:

```bash
npm run check
```

Individual commands are also available:

```bash
npm run typecheck
npm run lint
npm test
npm run build
```

`main.js` is generated and intentionally excluded from source control. The production build is minified. See [DEVELOPMENT.md](DEVELOPMENT.md) for the future roadmap and [GITHUB_PUBLISHING.md](GITHUB_PUBLISHING.md) for exact repository and release metadata.

## Releasing

1. Update `version` in `package.json` and `minAppVersion` in `manifest.json` if needed.
2. Run `npm version patch`, `npm version minor`, or `npm version major`. The version script synchronizes `manifest.json` and `versions.json`.
3. Push the commit and matching numeric tag, such as `1.0.1`.
4. The release workflow validates, builds, and uploads `main.js`, `manifest.json`, and `styles.css` to the GitHub release.

For a manual release, the locally ignored `releases/` folder contains fresh copies of those three files after packaging.

The release tag must exactly match the manifest version. For initial community submission, follow Obsidian's [plugin submission guide](https://docs.obsidian.md/Plugins/Releasing/Submit%20your%20plugin) and submit `https://github.com/NameIsKyro/yaml-creator`.

## Data integrity and YAML formatting

YAML Creator writes through Obsidian's `FileManager.processFrontMatter` API. It preserves property data, but Obsidian may normalize comments, quoting, anchors, aliases, and formatting when the frontmatter is saved. Back up important vaults and test new plugins in a separate vault first.

The plugin never edits multiple notes in version 1.0.0. Vault-wide and folder-wide operations are roadmap items only.

## Privacy

YAML Creator operates entirely inside the active vault. It has:

- No network access.
- No accounts or external services.
- No telemetry or analytics.
- No advertisements or payments.
- No access to files outside the vault.

Settings, template definitions, pins, and recent history are stored using Obsidian's plugin data API.

## License

[MIT](LICENSE) © 2026 NameIsKyro