*Читайте на [русском](README.ru.md).*

# Natural link

An Obsidian plugin that lets you create links to notes using natural word forms. Type a word in any form and the plugin will find matching notes regardless of word order.

![Modal search example: typing "went walking" finds the note "Go for a walk" via suppletive dictionary, with the recommended hotkey highlighted](docs/demo/en/modal-search.png)

*Optional feature: replaces the standard inline link suggestions with the plugin's morphological search (can be enabled in the plugin settings):*
![Inline suggest: typing `"[[running mornings"` suggests "`Morning run`"](docs/demo/en/inline-link.png)

## Features

- **Morphological search**: Find notes by any word form. Searching for "wooden boxes" will match a note titled "Wooden box". Russian morphology is fully supported, including consonant alternations (`друг`/`дружить`, `ходить`/`хожу`) and suppletive forms (`люди`/`человек`). English morphology includes Snowball stemming and irregular dictionary mappings such as `children`/`child`, `went`/`go`, and `better`/`good`.
- **Prefix matching**: Results update as you type. Even incomplete words match — typing "wood" will find "Wooden box".
- **Alias support**: Searches across note titles, frontmatter aliases, and display texts from wikilinks. If any note in the vault links to another with explicit display text (`[[Note|custom text]]`), that display text is automatically treated as an alias for the target note.
- **Word order independence**: "box wooden" finds "Wooden box".
- **Multi-language**: Russian and English search work simultaneously. Russian morphological analysis is based on [OpenCorpora](https://opencorpora.org/) dictionary data, English — on [WordNet](https://wordnet.princeton.edu/) exception lists.
- **Heading and block links**: Use `#` to link to a specific heading (`note#heading`) or `^` to link to a block (`note^text`). The plugin searches for the note first, then shows matching headings or text blocks with previews. Use `|` to set explicit display text (`note|custom text`).
- **Tab for display-preserving completion**: Press **Tab** to accept the selected suggestion and insert a link with your typed text preserved (`[[Note|your text]]`, `[[Note#Heading|your text]]`, `[[Note#^blockId|your text]]`).
- **Insert link as typed**: Press **Shift+Enter** to insert a link with your exact input as both target and display text, bypassing search results.
- **Preserved display text**: Links are always created as `[[Note Title|your input]]`, so your original text is preserved even if the note is renamed.
- **Inline `[[` suggest** (opt-in): Replace Obsidian's native link autocomplete with the plugin's morphological search. Suggestions appear inline as you type `[[`, with hotkey hints shown at the bottom. Enable in Settings → Natural link → "Replace native [[ link suggest".
- **Localized UI**: Interface available in English and Russian. Language follows your Obsidian settings.

## Usage

1. Run the **Insert Natural link** command (or start typing `[[` if the inline suggest feature is enabled).
2. Type the word or phrase you want to link.
3. Select a matching note:
   - **Enter** inserts `[[Matched Note]]`.
   - **Tab** inserts `[[Matched Note|your typed text]]` (also works for `#` headings and `^` blocks).

**Tip**: Press **Shift+Enter** at any time to insert a link using your exact input as-is.

**Command palette commands**:
- **Insert natural link** (recommended hotkey: **Cmd/Ctrl+Shift+K**) — opens the natural link dialog.
- **Toggle "replace native [[ suggest with natural"**
- **Enable "replace native [[ suggest with natural"**
- **Disable "replace native [[ suggest with natural"**

The inline suggest commands let you control `[[` replacement without opening settings.

## Demo

**English demos**

**Modal search**
Type a natural phrase, open the modal, and accept the best match with `Tab` to preserve the typed wording.
![Modal search demo](docs/demo/en/modal-search.gif)

**Suppletive form search**
Type a completely different word form — "went walking" finds "Go for a walk" via the suppletive dictionary (`went` → `go`, `walking` → `walk`).
![Suppletive search demo](docs/demo/en/suppletive-search.gif)

**Inline `[[` suggest**
Start typing a wikilink directly in the editor and accept the suggestion with `Enter`.
![Inline suggest demo](docs/demo/en/inline-link.gif)

**Heading link**
Find a note first, then narrow it to a specific heading with `#heading`.
![Heading link demo](docs/demo/en/heading-link.gif)

**Block link**
Search inside a note with `^block`, insert the block link, and show the generated block ID in the target note.
![Block link demo](docs/demo/en/block-link.gif)

### Recommended hotkey

The plugin does not assign a hotkey by default. We recommend **Cmd/Ctrl+Shift+K** (next to Cmd+K which is "Insert link" in Obsidian). To set it up:

1. Go to **Settings → Hotkeys**
2. Search for "Natural link"
3. Assign your preferred shortcut

You can also open the hotkey settings directly from the plugin's settings tab.

## Examples

| You type | Note found | Link created |
|----------|-----------|--------------|
| wooden boxes | Wooden box | `[[Wooden box\|wooden boxes]]` |
| box wooden | Wooden box | `[[Wooden box\|box wooden]]` |
| wood | Wooden box | `[[Wooden box\|wood]]` |

## Installation

### From Obsidian Community Plugins

> **Status**: The plugin has been submitted to the official community plugin list and is awaiting review. Once approved, it will be available directly from Obsidian.

1. Open **Settings → Community plugins → Browse**.
2. Search for **Natural link**.
3. Click **Install**, then **Enable**.

### Via BRAT (recommended while awaiting official listing)

[BRAT](https://github.com/TfTHacker/obsidian42-brat) (Beta Reviewers Auto-update Tester) lets you install plugins directly from GitHub and keeps them up to date automatically.

1. Install the **BRAT** plugin from Obsidian Community Plugins if you haven't already.
2. Open **Settings → BRAT → Add Beta plugin**.
3. Enter the repository URL: `https://github.com/rekby/obsidian-natural-link`
4. Click **Add Plugin**.
5. Enable **Natural link** in **Settings → Community plugins**.

BRAT will automatically check for updates and keep the plugin current.

### Manual installation

1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/rekby/obsidian-natural-link/releases/latest).
2. Create a folder `<Vault>/.obsidian/plugins/obsidian-natural-link/`.
3. Copy the downloaded files into that folder.
4. Reload Obsidian and enable **Natural link** in **Settings → Community plugins**.

## Development

```bash
npm install          # Install dependencies
npm run dev          # Watch mode
npm run build        # Type check + production build
npm test             # Run tests
npm run test:watch   # Watch mode tests
npm run obsidian-tests # Build plugin and run real Obsidian UI tests
npm run demo:screenshots # Capture the static README PNG screenshots
npm run demo:capture # Capture localized demo frames in real Obsidian
npm run demo:render  # Render demo GIFs from captured frames via ffmpeg
npm run demo         # Refresh README PNG screenshots and localized demo GIFs
npm run lint         # Lint
npm run dict:ru:suffix # Extract Russian suffix rules from OpenCorpora
npm run dict:ru:build  # Rebuild Russian suppletive dictionary from OpenCorpora
npm run dict:en:build  # Rebuild English irregular forms dictionary from WordNet 3.1
npm run dict:build     # Run all dictionary build pipelines (suffix rules + dictionaries)
```

## Dictionary sources

Morphological dictionaries are generated from open data at build time:

- **Russian**: [OpenCorpora](https://opencorpora.org/) (license: [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/))
- **English**: [WordNet](https://wordnet.princeton.edu/)

Run `npm run dict:build` to regenerate all dictionary files. Raw downloaded archives are kept in `.cache/dictionaries/` and are not committed.

## Known limitations

- **No typo tolerance**: Currently matches are exact on word roots. Fuzzy matching is planned.

## License

[MIT](LICENSE)