@mai/meditor (0.7.0)
Installation
@mai:registry=https://mgit.msbls.de/api/packages/mAi/npm/npm install @mai/meditor@0.7.0"@mai/meditor": "0.7.0"About this package
mEditor
A markdown editor as a Svelte package: a CodeMirror 6 editor and a preview pane, with wikilink and tag autocomplete, a formatting toolbar and keymap, indent guides, a marker table that draws - [c] as an icon, and a provider interface so the host supplies content resolution instead of the editor knowing about any one product's data.
Extracted from mBrian/src/lib/MarkdownEditor.svelte for m/mWiki#4. See
docs/provider-interface.md for what a consumer must supply.
Lives at packages/meditor/ in the m/mkit workspace (moved from the
standalone m/mEditor repo 2026-09-14, m/mkit#3), alongside packages/mkit
(@mai/mkit). The root bunfig.toml and .gitea/workflows/publish.yml are
shared across both packages; see the workspace root README.
Install
Published as @mai/meditor on this Gitea instance's own npm registry, not on
the public npm registry — under the mAi account's namespace, since that is
the account that cuts every release.
bun add @mai/meditor
Point the @mai scope at the registry in a .npmrc (project root or user
level):
@mai:registry=https://mgit.msbls.de/api/packages/mAi/npm/
The package is readable without a credential, so an install (a Dokploy build included) needs that line and no token. Never add an _authToken line to a consumer: with GITEA_NPM_TOKEN unset bun sends an empty bearer and Gitea answers 401. Publishing needs write:package and runs from this repo's workflow (root README § Publishing); a change here ships a CHANGELOG.d/<issue>-<slug>.md fragment and never a version, which is assigned on main after the merge (m/mkit#62). Gitea's package registry ties write access to the owning account and takes no collaborators, which is why the package lives under mAi, the account that mints every release.
Versioning
d-880df9d8, m's rule for this workspace, also in CHANGELOG.md's header: 0.x for now, a patch for every fix and every addition (a new optional prop, a new export, a new optional provider member — existing callers keep compiling unchanged), a minor only for a change a consumer must react to (a removed or renamed export, a new required provider member, a changed signature, a DOM a consumer's CSS or tests reached into), and 1.0 when m calls the package stable. The exported surface the rule is measured against is Editor and its props, EditorProviders, renderMarkdown and the pure helpers documented in docs/provider-interface.md. A branch never names the number; it writes a CHANGELOG.d/ fragment with bump: patch or bump: minor (root README § Publishing).
A release is followed by a sync commit in m/mWiki (m/mWiki#111, scripts/sync-meditor.ts), since mWiki vendors the built package rather than installing it from this registry.
Use
<script lang="ts">
import { Editor, type EditorProviders } from '@mai/meditor';
let value = $state('');
const providers: EditorProviders = {
async search(trigger) { /* … */ return []; },
resolveLink(kind, target, display) { /* … */ return undefined; }
};
</script>
<Editor bind:value {providers} onsave={() => save(value)} renderOptions={{ blockIds: true }} />
renderOptions (optional) is passed straight through to the same
renderMarkdown options a host's own server-side render uses, so the
editor's preview stamps data-block/data-lines the same way. Omitted,
the preview renders exactly as before.
The document's bytes are the host's: a string loaded and saved untouched is identical, and an edit leaves every other line as it was — CRLF or LF, trailing whitespace, tabs, the trailing newline (tests/document.test.ts). A document mixing both line endings keeps its first one from the first edit on.
Theming
The editor reads the host's custom properties and ships fallbacks for a dark surface: --color-bg, --color-bg-secondary, --color-text, --color-text-secondary, --color-border, --color-border-focus, --color-link, --color-selection, --color-indent-guide and --settings-editor-font-size. Set them on any ancestor of <Editor>. The task icons take the kit's --mk-task-* tokens when @mai/mkit/tokens.css is loaded and draw in the text colour otherwise.
wikilinks.ts's pure functions (parseWikilinks, extractWikilinkSlugs,
rewriteWikilinkTarget) are exported alongside Editor for a consumer's own
backlink and rename logic — see docs/provider-interface.md's "Renaming"
section for why the rename itself is not part of this package.
Formatting toolbar
A row of insert-action buttons above the editor, shown by default; pass toolbar={false} to hide it. Overflow beyond 320px collapses into a "More" menu.
| Action | Shortcut |
|---|---|
| Bold | Ctrl/Cmd+B |
| Italic | Ctrl/Cmd+I |
Heading (cycles ##→###→####→plain) |
Ctrl/Cmd+Shift+H |
| Link | Ctrl/Cmd+K |
Wikilink (opens the [[ search) |
Ctrl/Cmd+Shift+K |
| Inline code | Ctrl/Cmd+E |
| Code block | Ctrl/Cmd+Shift+E |
| Quote | Ctrl/Cmd+Shift+. |
| Bullet list | Ctrl/Cmd+Shift+8 |
| Numbered list | Ctrl/Cmd+Shift+7 |
| Table | — |
| Footnote | Ctrl/Cmd+Shift+F |
Task (cycles text→- →- [ ] →- [x] →plain) |
Ctrl/Cmd+Enter |
| Task state (steps the nine states) | Ctrl/Cmd+Shift+Enter |
Format the document (§ Formatter, formatRules prop) |
Ctrl/Cmd+L |
Every button and shortcut runs the same pure text transform, in toolbar-actions.ts — wrapBold, wrapItalic, wrapInlineCode, insertLink, insertWikilink, insertTable, toggleQuote, toggleBulletList, toggleNumberedList, toggleCodeBlock, cycleHeading, insertFootnote, cycleTask, cycleTaskState — each taking { text, selectionStart, selectionEnd } and returning the same shape, exported from both @mai/meditor and @mai/meditor/headless for a consumer that wants to drive them without the UI (a bulk-reformat script, a test). In the editor each is one CodeMirror transaction, so one undo step. Bold and italic unwrap when the marker already stands around the selection, and a * that belongs to a ** pair is not an italic marker.
Two keys are not on the toolbar. Enter on a list line continues the list — the same bullet, the next number for an ordered item, an open [ ] after a task in any state, the text right of the caret carried onto the new item — and on an item with nothing on it ends the list instead; off a list line it is a plain newline. Tab and Shift+Tab indent and outdent every line the selection touches by one step of two spaces (INDENT), blank lines left alone. Both are pure functions in list-keys.ts (continueList, indentLines, indentList, parseListLine), exported like the toolbar's.
Indent guides and the wrapped-line indent
A list item that wraps keeps every visual line under its own text, and an indented line carries one thin guide per indent step (two spaces, or one tab) down the full height of the line — a wrapped paragraph keeps its guides across every visual line. The guide colour is --color-indent-guide, falling back to --color-border.
A line action applies to every line the selection touches, decided once from the first of them, so a block moves together. A caret keeps its place in its line; a selection ends up around the changed block.
Task icons
A task reads as an icon while the markdown under it stays what the file holds (m/mkit#51): the editor draws the kit's .mk-task over each - [c] marker, and the preview renders the same icon through renderMarkdown. The states are Obsidian's nine — [ ], [x], [/], [?], [!], [-], [>], [<], [*] — defined in @mai/mkit/markdown and themed from the kit's --mk-task-* tokens (the kit's README, § Task states).
Ctrl/Cmd+Enter is the task key: text → - text → - [ ] text → - [x] text → text, with a line in any other state counting as an open task, so one press marks it done. Ctrl/Cmd+Shift+Enter steps the state through the nine and round again, and turns a line that is no task yet into one.
The icon is a CodeMirror decoration over the marker's three characters: the document keeps - [c], the caret steps over the icon as one unit, and Backspace behind it takes the whole marker. taskIcons={false} leaves the raw brackets visible, for a plain source view; the preview renders icons either way.
The marker table
Which text is drawn as which icon is a table, DEFAULT_MARKERS (exported), with one row per kit state; the markers prop replaces it, so a host extends the set by passing [...DEFAULT_MARKERS, row]. A row is a MarkerRule:
{
name: 'money', // data-task on the icon
match: /^[ \t]*[-*+][ \t]+(\[\$\])(?=\s|$)/, // per line; group 1 is what the icon covers
icon: '$', // the glyph; omitted → the kit's --mk-task-glyph-<name>
color: 'gold', // omitted → the kit's --mk-task-color-<name>
done: false, // true dims the line and strikes its text
label: 'Money' // the icon's aria-label
}
The default rows carry no icon or color, so they stay themed by the kit's --mk-task-* tokens; done and cancelled carry done: true. A rule needs no bracket at all — a letter that opens a bullet (- Q said) is a row like any other.
Adding an autocomplete trigger
[[ and # are the two rows of DEFAULT_TRIGGERS (exported); the triggers prop replaces the set the same way. A TriggerRule is a kind (what search receives as EditorTrigger.kind), a match run against the text from the line start to the caret with group 1 as the query, and insert(insertText), the text written over the trigger and the query when a suggestion is picked:
const mention: TriggerRule = { kind: 'mention', match: /(?<=^|\s)@([\w/.-]*)$/, insert: (t) => `@${t}` };
<Editor bind:value {providers} triggers={[...DEFAULT_TRIGGERS, mention]} />
providers.search then sees kind: 'mention' beside the two it knows. The preview's resolveLink is unchanged: it resolves wikilinks and tags, which are the two the renderer knows.
Formatter
formatMarkdown(text, rules?) rewrites a whole document to a rule set and returns it — the Ctrl+L formatter of m/mAi#408, headless (m/mkit#92). It runs only when a human invokes it, never on load, save or blur: the diff a pad's reader takes off the document is the human's own. Each rule is one switch on FormatRules; a key left undefined is off, and formatMarkdown(text, {}) returns the input byte for byte. Without a rules argument it applies defaultFormatRules: ATX headings, a blank line around top-level headings, lists and fences, blank-line runs cut to one, trailing whitespace removed (a hard break keeps its two spaces), exactly one trailing newline. The marker choices — bullet (-/*/+), orderedNumbering (increment/one), emphasis and strong (*/_) — are off until a configuration names them.
The remark stack parses (remark-parse, remark-gfm, unified) and nothing prints: a rule computes its edits from the nodes' positions and splices them into the original text, so a line ending, a tab, a wikilink, a #tag, a - [c] marker or a code block's content is never rewritten by a rule that is not about it. A round trip through remark-stringify was measured at 74 of 112 changed lines with every printer setting matched, which is why there is no printer. tests/format.test.ts holds the fixtures: a copy of a mai scratchpad and a CRLF one, byte-identical with every rule off, and each default rule render-neutral on the scratchpad through renderMarkdown.
import { formatMarkdown, defaultFormatRules } from '@mai/meditor/headless';
const formatted = formatMarkdown(text, { ...defaultFormatRules, bullet: '-' });
In the editor, Ctrl/Cmd+L runs it over the whole document as one transaction (one undo step) with the formatRules prop, defaultFormatRules unless the host passes its own; it is bound to the key alone and never runs on load, save or blur. Never the selection — a selection boundary inside a list or a fence hands the parser half a block.
Plain resolvers (no Svelte, no Vite)
The package root (@mai/meditor) resolves only through the svelte export
condition, because Editor is a Svelte component and no export condition
makes a .svelte file loadable by a plain resolver. A server-side consumer
that only needs renderMarkdown or the wikilinks helpers — bun test, a
plain Node ESM script, anything without a Svelte-aware bundler — imports
from the @mai/meditor/headless subpath instead, which never touches
Editor.svelte:
import { renderMarkdown } from '@mai/meditor/headless';
Develop
bun install
bun run test:unit # the pure modules incl. format.ts, the byte-stability round trip (tests/document.test.ts), the server render (tests/ssr.test.ts); packages/mkit must be built first, its exports point at dist/
bun run dev # src/routes is a standalone test consumer, no other repo needed
bun run build # builds the package into dist/
Dependencies
Dependencies
| ID | Version |
|---|---|
| @codemirror/commands | ^6.11.0 |
| @codemirror/state | ^6.7.4 |
| @codemirror/view | ^6.43.11 |
| @mai/mkit | ^0.1.70 |
| remark-gfm | ^4.0.1 |
| remark-parse | ^11.0.0 |
| unified | ^11.0.5 |
Development Dependencies
| ID | Version |
|---|---|
| @sveltejs/adapter-auto | ^4.0.0 |
| @sveltejs/kit | ^2.15.0 |
| @sveltejs/package | ^2.3.0 |
| @sveltejs/vite-plugin-svelte | ^5.0.0 |
| @types/bun | ^1.3.9 |
| @types/jsdom | ^30.0.0 |
| jsdom | ^30.0.1 |
| publint | ^0.2.0 |
| svelte | ^5.0.0 |
| svelte-check | ^4.0.0 |
| typescript | ^5.0.0 |
| vite | ^6.0.0 |
Peer Dependencies
| ID | Version |
|---|---|
| svelte | ^5.0.0 |