ContextFlow

ContextFlow is a local-first Quick Insert menu for Obsidian. From any Markdown note, use the command palette, editor context menu, ribbon action, or a configurable hotkey to insert useful Markdown actions quickly.

Documentation website: contextflow documentation.

Getting started

ContextFlow is designed to be useful without a complicated setup:

1. Enable ContextFlow in Settings → Community plugins.
2. Open any Markdown note.
3. Place the cursor where you want the result.
4. Open Quick Insert from the command palette, the editor right-click menu, or the ribbon button.
5. Search for an action and press Enter.

You can also type / in a note to open the Slash Menu. Type a few letters, select an action with the arrow keys, and press Enter. If you press Escape, nothing is changed.

The three things to remember

• Actions do one thing, such as inserting a date or converting selected text.
• Workflows run several actions in sequence.
• Action packages are JSON files that let you share custom actions and workflows.

You do not need to understand templates, variables, JSON or frontmatter to use the built-in actions.

Common tasks

Insert a date or task

Open Quick Insert and choose Insert date, Insert time, Insert date and time, or Insert new task. These actions work at the cursor position.

Format existing text

First select the text, then open Quick Insert. Choose Highlight selection, Convert selection to task, Convert selection to callout, Create internal link, or Insert code block.

Actions that need selected text are hidden when there is no selection, so you do not have to guess which action is safe to use.

Create a custom action

Go to Settings → ContextFlow → Actions → Add custom action. Give the action a name and enter Markdown in the template field. You can use:

{{date}}       today's date
{{time}}       the current time
{{title}}      the current note name
{{selection}}  the selected text
{{input:name}} a value requested from you before execution

Start with one simple template. You can always edit or disable the action later.

Create a workflow

Go to Settings → ContextFlow → Action packages → Add workflow. Add steps, move them with the arrow buttons or drag-and-drop, then save. A workflow uses the same actions as Quick Insert; it does not create copies of them.

Import or export actions

Use Export to make a backup or share your custom actions. Use Import to load a JSON package. ContextFlow always shows a review screen first. Existing actions are not overwritten unless you explicitly choose the overwrite option.

Use the optional calendar

The local calendar is disabled by default. Enable it in Settings if you need it. It stores events locally, supports basic recurrence and ICS import/export, and does not connect to Google, Microsoft or another external service.

Language

ContextFlow starts in English. Change Settings → ContextFlow → General → Language to Dutch. The language setting is stored per vault.

If something does not work

• Nothing happens: make sure a Markdown note is open and the plugin is enabled.
• An action is missing: check that it is enabled and that its context requirement is met, such as selecting text first.
• Slash Menu does not open: check the Slash Menu setting and make sure / is not inside a URL, code block, inline code or YAML frontmatter.
• A custom action shows an error: check its template for misspelled variables and complete all required input fields.
• An import is rejected: the package may be malformed or use an unsupported schema version. Export a fresh package from ContextFlow to compare the format.

When reporting a problem, include the action name, the current note context and the exact error message. Do not include private note contents.

Features

• Searchable Quick Insert modal with keyboard navigation.
• Slash Menu with configurable trigger, live filtering and safe context exclusions.
• Editor context-menu, command-palette and ribbon access.
• Date, time, task, callout, table, code block, link and note actions.
• Selection-aware actions such as highlighting and converting text to a task.
• Local favorites/history settings foundation.
• Light/dark theme compatible and mobile-safe access paths.
• User-created Markdown actions with supported variables and selection behavior.
• Action/workflow validation and JSON action-package import/export.
• Basic workflow editor and safe sequential execution with failure reporting.
• Optional local calendar view, disabled by default and without external synchronization.

The calendar is intentionally a lightweight local extension point. External calendar synchronization, recurring appointments, drag-and-drop scheduling and .ics support are not included yet.

Installation guide

Choose the option that matches what you want to do. You only need one option.

Option A — Community Plugins (easiest)

Use this option after ContextFlow has been accepted into the official Obsidian Community Plugins directory.

1. Open Obsidian.
2. Click the Settings icon (the small gear) in the lower-left corner.
3. Select Community plugins.
4. If Safe mode is enabled, click Turn off Safe mode and confirm.
5. Click Browse.
6. Search for ContextFlow.
7. Click Install.
8. Click Enable.
9. Open a Markdown note and run Open Quick Insert from the command palette.

If ContextFlow does not appear in the search results, it has not been accepted or the Community Plugins list has not refreshed yet. Use Option B for now.

Option B — Manual installation from GitHub

Use this option when the plugin is not yet available in Community Plugins.

1. Open the ContextFlow GitHub repository.

2. Click Releases on the right side of the repository page.

3. Open the release that matches the version you want to install.

4. Download these three files:

   • main.js
   • manifest.json
   • styles.css

5. Find your Obsidian vault on your computer.

6. Open this folder inside the vault:

   .obsidian/plugins/contextflow/
   

   If plugins or contextflow does not exist, create the missing folders yourself. The folder name must be exactly contextflow in lowercase.

7. Copy the three downloaded files into that folder.

8. Restart Obsidian, or go to Settings → Community plugins and reload the plugin list.

9. Find ContextFlow and switch it on.

The final folder must look like this:

Your vault/
└── .obsidian/
    └── plugins/
        └── contextflow/
            ├── main.js
            ├── manifest.json
            └── styles.css

Do not put the files directly in .obsidian, in the vault root, or in a folder called ContextFlow with capital letters.

Option C — Install from source for development

Use this option only if you want to modify the plugin's source code.

Requirements:

• Node.js 20 or newer;
• npm;
• an Obsidian vault for testing.

1. Open Terminal.

2. Download the repository:

   git clone https://github.com/loopman90/contextflow.git
   cd contextflow
   

3. Install dependencies:

   npm install
   

4. Build the plugin:

   npm run build
   

5. Copy main.js, manifest.json and styles.css into your vault's .obsidian/plugins/contextflow/ folder as described in Option B.

6. Enable ContextFlow in Obsidian.

For active development, use npm run dev in the repository. After each source change, copy the newly generated main.js into the vault and reload the plugin.

First launch checklist

After installation, verify these simple things:

1. A Markdown note is open.
2. ContextFlow is enabled under Settings → Community plugins.
3. Open the command palette with Cmd/Ctrl+P.
4. Search for Open Quick Insert.
5. Choose Insert date.
6. Confirm that today's date appears at the cursor.
7. Type / in a note and confirm that the Slash Menu appears.

If these steps work, the installation is complete.

Installation troubleshooting

• ContextFlow is not listed: confirm that the folder is exactly .obsidian/plugins/contextflow/.
• Obsidian says the manifest is invalid: download manifest.json again and make sure it was not renamed to manifest (1).json.
• The plugin is listed but will not enable: confirm that main.js, manifest.json and styles.css are all in the same folder, then restart Obsidian.
• The command is missing: enable the plugin, close and reopen the vault, then search the command palette again.
• The Slash Menu does not open: check Settings → ContextFlow → Slash Menu and make sure it is enabled.
• You cannot see .obsidian: enable hidden files in your operating system's file browser. Obsidian's Open vault folder command can help you find the correct vault.

Privacy and data

ContextFlow is local-only. It has no account, server, analytics, telemetry, AI integration or external scripts. Settings and the small recent-action history are stored through Obsidian's plugin data API in the current vault. Note content is not copied into plugin data.

Development

npm install
npm run dev       # watch build
npm run typecheck
npm test
npm run build

License

MIT. See LICENSE.