Vault editor — toolbar, slash commands, links, tables and footnotes
The Vault's editor — its toolbar and slash commands, how links, tables, footnotes, lists, headings and code are written and rendered, how the view behaves while you type and save, and what happens to an imported note that is not perfectly formed.
On this page
What it is
This page covers writing in the vault: the editor's toolbar and its slash commands, the syntax for links, tables, footnotes and lists, how code and long content are rendered, and how the editor behaves around autosave and imported notes.
Where to find it
The Vault panel — open any note and the editor fills the pane. Every feature described here is reached from inside that editor rather than from a separate screen.
How it behaves
Editor toolbar (2026-06-06 layout)
The horizontal formatting strip above the editor (between the tabs strip and the document) is a single row, no flex-wrap. It was collapsed on 2026-05-22 from a 22-button five-group grid into inline primaries plus two dropdowns; on 2026-06-06 Undo, Redo, and Numbered list were promoted out of the ⋯ More menu onto the inline strip so the controls a user reaches for are always visible. The inline order:
- Undo / Redo — lead the strip (Docs/Word convention). They grey out when there's nothing to undo / redo (the buttons read the editor's
can()check, refreshed on each editor transaction). - Bold (
Ctrl+B) - Italic (
Ctrl+I) - Heading ▾ — opens a dropdown with seven rows: Normal · H1 · H2 · H3 · H4 · H5 · H6 (the full OneNote / Google-Docs heading ladder). The trigger lights up in accent colour whenever the caret sits inside any heading; the specific level (H1–H6) shows active inside the dropdown so you can see at a glance what's currently applied.
- Bullet list
- Numbered list
- Link
- ⋯ More — opens an overflow menu containing the remaining secondary commands, in this order: Underline, Strikethrough, Highlight, Blockquote, Code block, Task list (turns the selected lines into checkboxes, or back into plain lines, the same as the
/menu's Todo List andCtrl+1), Image (opens an OS file picker), Hidden block, Column block, Insert table, Decrease indent, Increase indent. (The two indent commands were added for mobile — where there's noTabkey — but the catalog-completeness contract requires every command occupy exactly one desktop list, so on desktop they land here in the overflow; the keyboardTab/Shift+Tabstays the primary desktop path.)
Both dropdowns follow the standard WAI-ARIA menu contract: ↓ / ↑ moves the highlight (with wraparound at the ends), Home / End jump to the first / last row, Enter or Space activates the highlighted row, Esc or Tab closes the menu and restores focus to the trigger. Mouse hover also moves the highlight; click-outside dismisses without picking.
The non-formatting View and Bookmark icons that live to the right of this strip (Toggle side panel, source-view, find/replace, bookmark current note) are rendered by KmsView itself — they're a separate strip and were not touched by the collapse.
When the editor is unmounted or destroyed (closing the last tab, switching away from the Vault panel mid-render), every button greys out and click-handlers short-circuit. This replaces the prior crash path where Undo / Redo's enable check called editor.can() against a torn-down editor and surfaced "Something went wrong" in the panel's error boundary — the mobile quick bar (below) adopts the same isDestroyed-guarded editor-state subscription, so promoting Undo/Redo onto it is crash-safe too.
Link popover — open, edit, or remove an existing link
Inserting a link (the toolbar Link button or Ctrl+K) opens a small edit form — a URL field plus an optional display-text field. Acting on a link that already exists surfaces a compact bubble with three actions — Open (launches the URL externally), Edit (switches to the edit form), Remove (unlinks) — alongside the URL and a close button.
How that bubble is revealed is surface-split:
- Desktop — it appears when you hover the mouse over a link, not when you place the text cursor on it. (Merely moving the caret onto a line that contains a link used to pop the bubble and cover the surrounding note content; it no longer does.) A short hover delay avoids flicker, and the bubble stays open while you move the pointer from the link into it, so its buttons stay clickable.
- Mobile / touch — there is no hover, so tapping into a link opens the bubble (unchanged — long-press
contextmenuis unreliable on iOS, so tap remains the phone's reliable path to link actions).
On every surface the same three actions also live on the editor's right-click / long-press context menu (Open link · Edit link · Remove link), and Ctrl+K edits the link under the caret. The bubble is positioned to never cover the link line it points at — it sits fully below the link (or above, when there's no room), and clips at the viewport edge rather than landing on the link.
Source: LinkPopover.tsx (the bubble), useEditorPopovers.ts (the hover / tap trigger + hover bridge), popover-positioning.ts (the avoidAnchor placement). Invariants: kms-link-hover-contract.md.
Slash commands
Typing / anywhere in the editor opens a command menu — a filtered list of block-level formatting commands grouped by category (Headings, Lists, Blocks, Insert). Continue typing to narrow results; the menu matches against title, description, category, and search-term aliases (e.g. /hr → Horizontal Rule, /todo → Todo List, /h1 → Heading 1). Arrow Up/Down to navigate (wraps), Enter or Tab to pick, Esc to dismiss.
Available commands: Heading 1–6, Bullet List, Numbered List, Todo List (GFM checkboxes), Blockquote, Code Block, Horizontal Rule, Image (opens file picker).
Source: SlashCommandExtension.ts (command definitions) + SlashCommandSuggestion.tsx (popup UI).
Pasting outlines and lists
Pasting a nested outline keeps its nesting. When you copy a multi-level list from Google Docs, Word, Notion, a web page, or plain-text notes — where the sub-levels are shown with letters (a. b.) or extra indentation — the sub-items paste as properly-indented nested list items instead of collapsing to flush-left plain text. The editor detects the outline (numeric / letter markers plus indentation), rebuilds it through the note's markdown pipeline so pasted nesting matches typed nesting, and it round-trips to disk. It stays conservative: ordinary prose, a flat single-level list, and a rich-HTML list that already carries its own nesting all paste unchanged.
Source: OutlinePasteHandler.ts + outline-paste.ts. Invariants: kms-outline-paste-contract.md.
Pasting formatted content
A paste keeps its formatting. Copy a page, a Google Doc, a Word document, a syntax-highlighted block out of VS Code, or an answer out of an AI chat, and it lands as real rich text: headings, bold and italic, inline code, links, code blocks (with their language), tables, quotes and lists — not a wall of raw symbols. The page's own fonts, colours, text sizes and classes are dropped, and so are scripts, event handlers and javascript: links, so a copy from somewhere hostile arrives as harmless text.
Pasted markdown is parsed as markdown. Copy the raw markdown of a note, or an AI answer that came back as markdown, and headings become headings, **bold** becomes bold, a markdown table becomes a real table, - [ ] becomes a checkbox and a fenced block becomes a code block with its language. Ordinary prose with no markdown in it stays exactly the prose you copied, and a copy that carries formatting (anything with HTML on the clipboard, including a copy you made inside the vault) is taken at its word and never re-read as markdown.
Ctrl+Shift+V ignores all of that. It pastes the clipboard's text and nothing else — markup shows on screen as the characters it is made of, with no formatting and no conversion. There is no way to paste without formatting if that key does nothing, so it is the escape hatch for every paste above.
Two cases are deliberately literal: markdown pasted while your caret is inside a code block stays text (code is never parsed as markdown), and a text-only copy of code — indented, with nothing but plain text on the clipboard — lands as the lines you copied instead of being re-read as markdown, so a shell comment starting with # is not turned into a heading. A single unindented line that is also valid markdown (# Title) is the one ambiguous case, and it formats.
Source: OutlinePasteHandler.ts + markdown-paste.ts + outline-paste-html.ts + shortcut-cascade.ts. Invariants: kms-editor-behaviour-safety-contract.md (ed-32 to ed-37, ed-44).
Editor keyboard shortcuts
Almost every formatting command has a keyboard shortcut, so you rarely have to reach for the toolbar. The defaults follow OneNote conventions, and many commands additionally accept the Google-Docs / Microsoft-Word shortcuts so muscle memory from either app works — the list toggles, the full heading ladder (H1–H6 plus "Normal text"), strikethrough, and clear-formatting each accept both apps' keys.
These keys are rebindable. Open Settings → Keyboard Shortcuts → Vault Shortcuts: the Panel commands group rebinds the command-palette keys (Bold, Italic, Underline, headings, Insert link, Find / Replace, Search vault, Toggle source, Command palette), and the Editor formatting group rebinds the formatting toggles (bulleted / numbered / task list, strikethrough, clear formatting, code block, blockquote, duplicate block). Press Rebind, then your combination; the X disables a key, Default restores it. (The structural editor keys — Tab/Shift+Tab indent, Ctrl+Delete delete-block, Alt+Shift+↑/↓ move-block — stay fixed.)
The file-list keys are in the same list. "Rename file-list item" (F2) renames the row under the cursor while the Vault file list has focus, and with the editor focused it renames the open note instead: either way the thing being renamed is the note in the file list, through the same inline field and the same link-rewriting rename service. "Delete file-list item" (Delete) and "Open file-list menu" (Shift+F10) still act only while the file list has focus, so Delete keeps deleting text in the editor. See Moving a note, and the file-list keys.
The Panel commands group also holds New note and Open Vault Overview.
The file-list keys are in the same list. "Rename file-list item" (F2), "Delete file-list item" (Delete) and "Open file-list menu" (Shift+F10) act only while the Vault file list has focus, never in the editor, so Delete still deletes text there. See Moving a note, and the file-list keys.
Vault keys beat the system-wide hotkeys while you are in the Vault. Ctrl+Shift+M (focus Omniscio) and Ctrl+Shift+P (Quick Launch's command tab) are system-wide hotkeys the operating system takes before any page sees them. While keyboard focus is inside the Vault panel of a desktop window, the Vault tells the app which chords it binds (for example Ctrl+Shift+P for the Vault command palette and Ctrl+Shift+M for source view), and the app hands a claimed chord to the Vault instead of running the system-wide action. Outside the Vault, or after you rebind the chord, the system-wide hotkey works as before. One press made in the instant focus leaves the Vault can be lost. Pinned as vault-focus-reclaims-the-chords-it-binds in the keyboard dispatch contract.
Formatting
| Action | Shortcut |
|---|---|
| Bold | Ctrl+B |
| Italic | Ctrl+I |
| Underline | Ctrl+U |
| Strikethrough | Alt+-, Ctrl+- (OneNote), or Alt+Shift+5 (Google Docs) |
| Bullet list | Ctrl+. (OneNote) or Ctrl+Shift+8 (Google Docs / Word) |
| Numbered list | Ctrl+Shift+7 (Google Docs / Word) — Ctrl+/ opens Ask Omniscio app-wide, so it never reaches the note |
| Task / checkbox list | Ctrl+Shift+9 (Google Docs). Ctrl+1 stays the app-wide jump to the inbox and never reaches the editor |
| Heading 1 – 6 | Ctrl+Alt+1 … Ctrl+Alt+6 (OneNote / Google Docs) |
| Normal text (clear heading) | Ctrl+Alt+0 (Google Docs) |
| Blockquote | Ctrl+Shift+. |
| Code block | ⋯ More → Code block, or /code in the slash menu — Ctrl+Shift+C copies a page link app-wide |
| Clear formatting | Ctrl+Shift+N or Ctrl+\ (Google Docs) |
Block editing
| Action | Shortcut |
|---|---|
| Indent / outdent a list line (needs a line above it to nest under) | Tab / Shift+Tab, or Alt+Shift+→ / Alt+Shift+← |
| Duplicate block | Ctrl+D |
| Delete block | Ctrl+Delete |
| Move block up / down | Alt+Shift+↑ / Alt+Shift+↓, or, inside a list item, Ctrl+Shift+↑ / Ctrl+Shift+↓ |
Insert & navigate
| Action | Shortcut |
|---|---|
| Insert / edit link | Ctrl+K |
| Find in note | Ctrl+F |
| Replace in note | Ctrl+H (Cmd+Option+F on a Mac) |
| Replace in note | Ctrl+H (Mac: Alt+Ctrl+F) |
| New note | Ctrl+N |
| Search the whole vault | Ctrl+P |
| Jump to top / bottom of note | Ctrl+Home / Ctrl+End |
| Toggle source (raw-markdown) view | Ctrl+Shift+M |
| Open Vault Overview | Ctrl+Shift+O |
| Image gallery | Ctrl+Shift+G |
| Command palette | Ctrl+Shift+P |
The list shortcuts are toggles: pressing the bullet shortcut again while the caret is already inside a bullet list lifts the line back out to a plain paragraph. The same goes for numbered lists, headings, blockquote, and code block.
Tables (GFM pipe tables)
The editor supports GitHub-Flavored Markdown pipe tables. Insert a table via the ⋯ More toolbar menu → Insert table (inserts a 3×3 table with a header row), or type /table in the editor to use the slash command.
Editing:
- Tab / Shift+Tab navigate between cells (forward / backward). These keys only intercept while the caret is inside a table — outside a table they still handle list indentation as normal.
- There is no table toolbar: to add or remove a row or column, edit the pipe syntax in source view (
Ctrl+Shift+M). An inserted table always arrives as 3×3 with a header row.
Column alignment: each column can be aligned left, center, or right by writing the markers into the separator row in source view (:--- left, :---: center, ---: right). The editor carries them as a per-column attribute on the table node and writes them back to that row unchanged.
Markdown roundtrip: tables serialize to standard GFM pipe syntax and parse back identically — alignment, inline formatting within cells (bold, italic, code, links), and empty cells all survive the roundtrip. The underlying parser (marked, used by @tiptap/markdown) handles the tokenization natively.
Tab tucks a line under the line above it, and its own children travel with it. Shift+Tab does the reverse: the line moves out one level and lands directly after the line it used to sit under, while the lines that followed it stay where they were (it never adopts them). On a first/only line, where there is nothing above it to nest under, Tab and Shift+Tab leave the note alone and the caret stays in the editor. A deeper per-item indent stored by an older note still displays, and Shift+Tab peels one level off it. (Outliner rules ol-07 and ol-08 in the KMS outliner behaviour contract; before 2026-10-20 Tab on a first line grew a visual indent and Shift+Tab adopted the lines below.)
Ctrl+Up folds a branch away and Ctrl+Down opens it again. Folding collapses everything indented under the line your caret is on, so a long outline reads as its top level; a small caret appears in the gutter beside any line that has children, and clicking it does the same thing. A folded line looks folded — its bullet takes the accent colour, its text mutes a step, the caret turns to point right, and a number beside it says how many lines it is hiding. Folded text is only hidden from view: the line is still in the note, still saved, and nothing about a fold ever reaches your .md file, so Obsidian and any other markdown editor see the note exactly as you wrote it. Folds are remembered per note, across tab closes and app restarts. Ctrl+Alt+F folds every branch in the note, and Ctrl+Alt+Shift+Up / Down collapse or open the branch under the caret all the way through. Opening every branch at once has no working chord — Ctrl+Alt+U belongs to the app-wide Writer passage lock — so use the command palette's Expand all items row. The command palette (Ctrl+Shift+P) adds Expand to level 1 / 2 / 3, which opens the outline down to that depth in one action. (Outliner rules ol-18, ol-19 and ol-20 in the KMS outliner behaviour contract; folding shipped 2026-10-21.)
Ctrl+Delete (delete block) deletes the current line. If that line has indented sub-items beneath it, the sub-items are lifted up one level to take its place — they are kept, not deleted (so deleting a parent bullet promotes its children rather than wiping them). A plain line with no sub-items is removed entirely, and a single Ctrl+Z undoes the whole thing. (Behavior pinned as invariant I7 in the editor contract; before 2026-05-30 it only cleared the line's text, stranding an empty line and its sub-items.)
Ctrl+Home / Ctrl+End jump to the top / bottom of the note. They move the caret to the very start / end of the document and scroll the note there in one keystroke — handy in a long note. (Fixed 2026-06-13 and pinned as invariant I16; before that the editor moved the caret but never scrolled, so the keys looked dead — the scroll container was looked up by a CSS marker the editor wrapper had lost in the port from the old Knowledge Management Tool.)
These are in-note editing keys. Ctrl+Alt+N is now the global hotkey that opens the standalone KMS window (shipped — see Standalone KMS window). It is unrelated to the deferred Phase 7 Quick-Compose capture window.
List markers, headings, and the focus border
The note editor renders into a plain contenteditable surface that inherits Omniscio's global stylesheet. Omniscio is built with Tailwind, whose "preflight" reset deliberately strips list markers (ul, ol { list-style: none }) and flattens the heading scale (h1–h6 all inherit the body size) so stray browser defaults never leak into the app's chrome. That reset also reached the note editor: toggling a bullet or numbered list created real list items, but they showed no bullet or number, and headings looked like ordinary body text. Separately, Omniscio paints a 2-pixel accent-coloured focus ring around any focused element — and because that accent is near-white in several themes, the editor box appeared to gain an ugly white border whenever you were typing in it.
Both are fixed by a small scoped stylesheet block that re-declares the list markers (disc → circle → square as lists nest; decimal → lower-alpha → lower-roman for numbered lists), resets the task-list marker so checkbox items render as a [checkbox] text row instead of inheriting a stray bullet, restores the H1–H3 size-and-weight scale, keeps nested bullet and numbered rows evenly spaced at every level (so the gaps no longer grow as lists nest deeper), and removes the focus outline. Every rule is namespaced under a .kms-prose wrapper class, so it applies only to the KMS note editor and can never leak into the other TipTap editing surfaces in the app (the agent chat composer, automation editors, and so on).
Numbered lists keep counting across an interrupting note. A paragraph, link, or image dropped between two numbered items splits the underlying markdown into two separate lists, and the editor normalizes every list to start at 1 — so an outline with a reference note in the middle used to render 1, 1, 2 instead of 1, 2, 3. The OrderedListContinuation extension fixes this at render time: it carries the count straight through the interruption so the list reads 1, 2, 3, …. It works per column and restarts at a heading (a new section is a new count), touches only the top level (nested a/i levels are unchanged), and is display-only — it never rewrites the numbers saved in your .md file. Pinned by invariant I18 of the styling contract.
Code syntax highlighting
Fenced code blocks (```python … ```) render with language-specific syntax coloring** — keywords, strings, comments, and other tokens are highlighted so code reads naturally inside a note. The editor uses CodeBlockLowlight with the same curated 29-language subset the rest of Omniscio uses (js, ts, python, rust, go, java, c#, c++, c, ruby, php, swift, kotlin, bash, shell, powershell, json, yaml, xml, markdown, ini, css, scss, sql, diff, makefile, dockerfile, graphql, plaintext). If you type a language fence the editor doesn't recognize (e.g. ```elixir), the block renders as plain monospace — no crash, no error. The language tag round-trips through markdown save/load, so highlighting reappears on reload. No new CSS was needed — the existing github-dark.css token classes and the scoped .kms-prose .ProseMirror pre container rules handle both light and dark themes. Pinned by invariant **code-blocks-syntax-highlighted in the editor styling contract.
Content always fits — no horizontal scroll
However wide a note's content gets — a two-column layout, a very long unbroken word or URL, a wide image — the page never scrolls sideways: the editor itself only ever scrolls up and down. (Before this, a wide two-column page could run off the right edge and get cut off — the original bug report showed exactly that.) On a roomy screen the columns shrink to share the pane, long words and links wrap, and images are capped to the pane width. The only things that get their own small internal sideways-scroll are blocks that genuinely can't shrink any further — a fenced code block scrolls inside its own frame instead of pushing the whole page over, and on a phone-width screen (≤767px) a multi-column block does the same: instead of crushing 2–5 columns into ~90px of character-by-character word-wrap (Export → Exp/ort), each column keeps a readable width and you swipe the block sideways to reach the rest — the page itself still never moves. This holds at every Editor width setting (below); it isn't the same control. The same scoped block also gives a multi-column layout visible borders — a thin rounded box around the block plus a divider line between columns (the first column has none, so you only ever see dividers between columns), matching the original KMS desktop app it was ported from. The border uses Omniscio's theme-aware divider tone (--color-surface-200, the same weight the KMS panels use) so it reads in every theme. (Restored 2026-06-19 — the port had dropped every border rule, so the columns floated with nothing between them.)
Resilient loading of imported / malformed notes
Notes imported from other tools (Google Docs especially) sometimes carry odd Markdown the editor must open without crashing. The load path is hardened two ways:
- The editor never crashes on a mark it can't place. The
LinkNormalizerextension auto-converts a raw[text](url)typed or pasted as plain text into a real link — but only where a link mark is schema-legal. Text inside a code block, or inside a malformed list item an import left holding bare text, can't hold a link mark, so the normalizer skips it (worst case the text stays literal) instead of attempting an invalid replace. Before this, such a replace threw ProseMirror'sCalled contentMatchAt on a node with invalid contentand blanked the whole KMS panel with the "Something went wrong" card (ref ecec4d3f, 2026-07-12). - Empty list markers with indented content are healed on open. A Google-Docs import can produce an empty bullet whose image + link sit on the indented lines beneath it (
-then![img]/[link]).@tiptap/markdownmis-parses that blank-first-line item, so on loadhealEmptyMarkerContinuation(markdown-io.ts, part ofpreflightMarkdown) pulls the first continuation line up onto the marker — the image + link then render and the bullet is preserved. Load-only; the healing never rewrites a note you didn't edit.
Full incident + the DO-NOT-RETRY list: kms-linknormalizer-invalid-content-crash postmortem.
Footnotes ([^label] references and [^label]: definitions)
The editor supports standard Markdown footnotes. Type [^label] inline to insert a footnote reference — it renders as a superscript accent-coloured link. At the bottom of the note (or anywhere a block starts), type [^label]: text to create the matching definition. The reference and definition are clickable cross-links: clicking a reference scrolls to its definition, and clicking a definition's label scrolls back to the reference.
Multi-line definitions are supported: indent continuation lines with 4 spaces or a tab. Blank lines within the continuation are preserved (multi-paragraph footnotes). The label grammar is [a-zA-Z0-9_-]+ — alphanumeric, hyphens, and underscores.
v1 is read-only in the rich editor. Definitions render as styled blocks (accent label + muted content) but are edited via the source-view toggle (Shift+Ctrl+M). The markdown round-trips losslessly — footnote syntax survives save → reload byte-for-byte. Rich inline editing of definitions is a future enhancement.
How it's wired (repo detail). Two TipTap nodes in FootnoteRef.ts and FootnoteDef.ts: footnoteRef (inline atom) and footnoteDef (block atom), both following the HiddenBlock/TasksBlock opaque-passthrough pattern. Each has a markdownTokenizer (inline-level for ref, block-level for def), parseMarkdown, and renderMarkdown on the extension's .config — integrated with @tiptap/markdown. NodeViews render the click-to-jump navigation via data-footnote-ref / data-footnote-def DOM attributes + scrollIntoView({ behavior: 'smooth', block: 'center' }). CSS lives in the scoped .kms-prose .ProseMirror .footnote-* block in globals.css. Invariants pinned in Footnote.test.ts (42 tests). Contract: kms-footnote-contract.md.
Related
Getting around the vault — the file tree, tabs and adding a note — is the KMS page; how the vault looks and how you find a note in it is appearance and search, and pictures and media are images and media.
Last verified 2026-11-13