@14ch/svelte-md-outliner 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +190 -0
- package/README.md +190 -0
- package/dist/assets/styles/editor.css +1459 -0
- package/dist/assets/styles/theme.css +486 -0
- package/dist/components/ContextMenu.svelte +279 -0
- package/dist/components/ContextMenu.svelte.d.ts +9 -0
- package/dist/components/EditorSurface.svelte +99 -0
- package/dist/components/EditorSurface.svelte.d.ts +16 -0
- package/dist/components/FocusBreadcrumb.svelte +138 -0
- package/dist/components/FocusBreadcrumb.svelte.d.ts +16 -0
- package/dist/components/MarkdownEditor.svelte +393 -0
- package/dist/components/MarkdownEditor.svelte.d.ts +119 -0
- package/dist/components/ShortcutHelpDialog.svelte +155 -0
- package/dist/components/ShortcutHelpDialog.svelte.d.ts +12 -0
- package/dist/components/internal/Dialog.svelte +157 -0
- package/dist/components/internal/Dialog.svelte.d.ts +23 -0
- package/dist/components/internal/Modal.svelte +181 -0
- package/dist/components/internal/Modal.svelte.d.ts +18 -0
- package/dist/components/internal/Popup.svelte +248 -0
- package/dist/components/internal/Popup.svelte.d.ts +26 -0
- package/dist/index.d.ts +32 -0
- package/dist/index.js +28 -0
- package/dist/markdown.d.ts +13 -0
- package/dist/markdown.js +10 -0
- package/dist/messages/en.d.ts +2 -0
- package/dist/messages/en.js +107 -0
- package/dist/messages/index.d.ts +13 -0
- package/dist/messages/index.js +31 -0
- package/dist/messages/ja.d.ts +2 -0
- package/dist/messages/ja.js +112 -0
- package/dist/messages/messages.types.d.ts +59 -0
- package/dist/messages/messages.types.js +1 -0
- package/dist/models/document/bodySelection.d.ts +32 -0
- package/dist/models/document/bodySelection.js +43 -0
- package/dist/models/document/document.types.d.ts +27 -0
- package/dist/models/document/document.types.js +8 -0
- package/dist/models/document/foldable.d.ts +18 -0
- package/dist/models/document/foldable.js +21 -0
- package/dist/models/document/schema.d.ts +2 -0
- package/dist/models/document/schema.js +428 -0
- package/dist/models/document/sectionTree.d.ts +15 -0
- package/dist/models/document/sectionTree.js +123 -0
- package/dist/models/markdown/blockOutline.d.ts +9 -0
- package/dist/models/markdown/blockOutline.js +82 -0
- package/dist/models/markdown/frontMatter.d.ts +98 -0
- package/dist/models/markdown/frontMatter.js +300 -0
- package/dist/models/markdown/markdown.types.d.ts +60 -0
- package/dist/models/markdown/markdown.types.js +1 -0
- package/dist/models/markdown/markdownIt.d.ts +1 -0
- package/dist/models/markdown/markdownIt.js +92 -0
- package/dist/models/markdown/parser.d.ts +4 -0
- package/dist/models/markdown/parser.js +505 -0
- package/dist/models/markdown/plainText.d.ts +1 -0
- package/dist/models/markdown/plainText.js +25 -0
- package/dist/models/markdown/serializer.d.ts +17 -0
- package/dist/models/markdown/serializer.js +453 -0
- package/dist/models/viewState/viewState.types.d.ts +38 -0
- package/dist/models/viewState/viewState.types.js +17 -0
- package/dist/models/viewState/viewStateCodec.d.ts +31 -0
- package/dist/models/viewState/viewStateCodec.js +173 -0
- package/dist/operations/autoformat.d.ts +9 -0
- package/dist/operations/autoformat.js +86 -0
- package/dist/operations/commands/block.d.ts +24 -0
- package/dist/operations/commands/block.js +139 -0
- package/dist/operations/commands/codeBlock.d.ts +7 -0
- package/dist/operations/commands/codeBlock.js +26 -0
- package/dist/operations/commands/element.d.ts +67 -0
- package/dist/operations/commands/element.js +269 -0
- package/dist/operations/commands/frontMatter.d.ts +35 -0
- package/dist/operations/commands/frontMatter.js +120 -0
- package/dist/operations/commands/lineBreak.d.ts +9 -0
- package/dist/operations/commands/lineBreak.js +16 -0
- package/dist/operations/commands/link.d.ts +7 -0
- package/dist/operations/commands/link.js +21 -0
- package/dist/operations/commands/list.d.ts +126 -0
- package/dist/operations/commands/list.js +652 -0
- package/dist/operations/commands/mermaidBlock.d.ts +9 -0
- package/dist/operations/commands/mermaidBlock.js +28 -0
- package/dist/operations/commands/section.d.ts +217 -0
- package/dist/operations/commands/section.js +865 -0
- package/dist/operations/commands/sectionFold.d.ts +36 -0
- package/dist/operations/commands/sectionFold.js +219 -0
- package/dist/operations/commands/sectionJump.d.ts +8 -0
- package/dist/operations/commands/sectionJump.js +144 -0
- package/dist/operations/commands/selectedBlock.d.ts +37 -0
- package/dist/operations/commands/selectedBlock.js +170 -0
- package/dist/operations/commands/table.d.ts +64 -0
- package/dist/operations/commands/table.js +437 -0
- package/dist/operations/keymap/assemble.d.ts +22 -0
- package/dist/operations/keymap/assemble.js +165 -0
- package/dist/operations/keymap/coreActions.d.ts +2 -0
- package/dist/operations/keymap/coreActions.js +711 -0
- package/dist/operations/keymap/menuItems.d.ts +52 -0
- package/dist/operations/keymap/menuItems.js +114 -0
- package/dist/operations/keymap/shortcutKeys.d.ts +42 -0
- package/dist/operations/keymap/shortcutKeys.js +114 -0
- package/dist/operations/keymap/viewActions.d.ts +30 -0
- package/dist/operations/keymap/viewActions.js +182 -0
- package/dist/operations/operations.types.d.ts +121 -0
- package/dist/operations/operations.types.js +1 -0
- package/dist/operations/plugins/blockHandle.d.ts +25 -0
- package/dist/operations/plugins/blockHandle.js +112 -0
- package/dist/operations/plugins/contextMenu.d.ts +33 -0
- package/dist/operations/plugins/contextMenu.js +204 -0
- package/dist/operations/plugins/focus.d.ts +39 -0
- package/dist/operations/plugins/focus.js +350 -0
- package/dist/operations/plugins/foldClick.d.ts +11 -0
- package/dist/operations/plugins/foldClick.js +117 -0
- package/dist/operations/plugins/foldGuard.d.ts +15 -0
- package/dist/operations/plugins/foldGuard.js +31 -0
- package/dist/operations/plugins/frontMatterGuard.d.ts +21 -0
- package/dist/operations/plugins/frontMatterGuard.js +150 -0
- package/dist/operations/plugins/frontMatterView.d.ts +34 -0
- package/dist/operations/plugins/frontMatterView.js +137 -0
- package/dist/operations/plugins/linkPaste.d.ts +3 -0
- package/dist/operations/plugins/linkPaste.js +20 -0
- package/dist/operations/plugins/listStructure.d.ts +13 -0
- package/dist/operations/plugins/listStructure.js +18 -0
- package/dist/operations/plugins/markdownClipboard.d.ts +8 -0
- package/dist/operations/plugins/markdownClipboard.js +208 -0
- package/dist/operations/plugins/mermaidView.d.ts +20 -0
- package/dist/operations/plugins/mermaidView.js +206 -0
- package/dist/operations/plugins/requiredSelectionEntry.d.ts +10 -0
- package/dist/operations/plugins/requiredSelectionEntry.js +124 -0
- package/dist/operations/plugins/sectionView.d.ts +12 -0
- package/dist/operations/plugins/sectionView.js +44 -0
- package/dist/operations/plugins/tabEscape.d.ts +21 -0
- package/dist/operations/plugins/tabEscape.js +41 -0
- package/dist/operations/plugins/tableHandles.d.ts +24 -0
- package/dist/operations/plugins/tableHandles.js +89 -0
- package/dist/operations/transaction.d.ts +26 -0
- package/dist/operations/transaction.js +51 -0
- package/dist/operations/transactionOrigin.d.ts +17 -0
- package/dist/operations/transactionOrigin.js +9 -0
- package/dist/states/contextMenuController.svelte.d.ts +57 -0
- package/dist/states/contextMenuController.svelte.js +206 -0
- package/dist/states/editorSession.d.ts +12 -0
- package/dist/states/editorSession.js +268 -0
- package/dist/states/editorSession.types.d.ts +57 -0
- package/dist/states/editorSession.types.js +1 -0
- package/dist/states/outlineViewController.svelte.d.ts +52 -0
- package/dist/states/outlineViewController.svelte.js +134 -0
- package/dist/utils/dateText.d.ts +25 -0
- package/dist/utils/dateText.js +71 -0
- package/dist/utils/geometry.types.d.ts +13 -0
- package/dist/utils/geometry.types.js +1 -0
- package/dist/utils/json.types.d.ts +4 -0
- package/dist/utils/json.types.js +1 -0
- package/dist/utils/platform.d.ts +8 -0
- package/dist/utils/platform.js +10 -0
- package/dist/utils/result.types.d.ts +7 -0
- package/dist/utils/result.types.js +1 -0
- package/package.json +109 -0
package/README.ja.md
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# @14ch/svelte-md-outliner
|
|
2
|
+
|
|
3
|
+
Svelte 5 用の、**マークダウンエディタをベースにしたアウトラインエディタ**。見出しがそのまま入れ子の階層になり、折りたたみ・フォーカス表示・`Tab` での組み替えができる。画面に出ているものがそのまま文書で、別途プレビューを持たない。
|
|
4
|
+
|
|
5
|
+
English: [README.md](README.md)
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script lang="ts">
|
|
9
|
+
import { MarkdownEditor } from '@14ch/svelte-md-outliner';
|
|
10
|
+
import '@14ch/svelte-md-outliner/styles/editor.css';
|
|
11
|
+
|
|
12
|
+
let value = $state('# はじめに\n\n本文\n');
|
|
13
|
+
</script>
|
|
14
|
+
|
|
15
|
+
<MarkdownEditor bind:value />
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## できること
|
|
19
|
+
|
|
20
|
+
- **見出しで文書を組み立てる** — `Tab` / `Shift-Tab` で見出しと配下ごと階層を組み替え、`Mod-↑` / `Mod-↓` で兄弟と入れ替える
|
|
21
|
+
- **畳んで見渡す** — 見出し単位の折りたたみと、レベルを指定した一括表示(`Mod-Alt-1`〜`6`)
|
|
22
|
+
- **1 つのセクションだけに集中する** — フォーカス表示と、パンくずでの行き来
|
|
23
|
+
- **打った瞬間に変換される** — `# ` `- ` `1. ` `[ ] ` `> ` などのマークダウン記法と、`**強調**` `` `コード` `` のインライン記法
|
|
24
|
+
- **テーブル・Mermaid の図・チェックリスト・フロントマター**を扱う
|
|
25
|
+
- **コンテキストメニューとショートカット一覧**を内蔵(切ることもできる)
|
|
26
|
+
- **文言とテーマを差し替えられる** — 英語と日本語を同梱、色と寸法は CSS カスタムプロパティ
|
|
27
|
+
|
|
28
|
+
## 通常のマークダウンエディタと違うところ
|
|
29
|
+
|
|
30
|
+
アウトラインエディタなので、見出しの階層が飾りではなく**文書の構造そのもの**になっている。そこから次の動きが出る。
|
|
31
|
+
|
|
32
|
+
- 見出しの上で `Tab` を押すと、**その見出しと配下がまるごと** 1 段深くなる(文字の字下げではない)
|
|
33
|
+
- 見出しのレベルは構造上の深さから決まる。`# A` の次に `### B` と書いた文書は `## B` として保存される(親子関係は残り、飛ばした段は残らない)
|
|
34
|
+
- 折りたたみ・フォーカス表示・パンくずは、すべてこの階層に対して働く
|
|
35
|
+
|
|
36
|
+
## 入れる
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npm install @14ch/svelte-md-outliner
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`svelte@^5` が peer dependency。スタイルは自分で読み込む(既定のテーマは中で読み込まれる)。
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import '@14ch/svelte-md-outliner/styles/editor.css';
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## props
|
|
49
|
+
|
|
50
|
+
```svelte
|
|
51
|
+
<MarkdownEditor bind:value bind:viewState label="議事録" maxWidth="42rem" />
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
| | 型 | 既定 | |
|
|
55
|
+
| ------------------- | -------------------------------- | ---------- | ------------------------------------------------------ |
|
|
56
|
+
| `value` | `string` | `''` | 本文のマークダウン(`bind:` 可) |
|
|
57
|
+
| `onChange` | `(markdown: string) => void` | — | `bind:value` を使うなら不要 |
|
|
58
|
+
| `viewState` | `ViewState` | — | どの見出しを畳んでいるか、どこをフォーカスしているか |
|
|
59
|
+
| `onViewStateChange` | `(viewState: ViewState) => void` | — | `bind:viewState` を使うなら不要 |
|
|
60
|
+
| `label` | `string` | 内蔵の文言 | 編集エリアのアクセシブルネーム |
|
|
61
|
+
| `readonly` | `boolean` | `false` | 入力・編集コマンド・貼り付けを受け付けない |
|
|
62
|
+
| `autofocus` | `boolean` | `false` | マウント時にフォーカスする |
|
|
63
|
+
| `class` | `string` | `''` | 追加のクラス名 |
|
|
64
|
+
| `padding` | `string` | トークン | CSS の `padding` と同じ書き方 |
|
|
65
|
+
| `maxWidth` | `string` | トークン | 行の長さ。**クリックできる範囲は元の幅のまま** |
|
|
66
|
+
| `lang` | `'en' \| 'ja'` | `'en'` | 同梱の言語 |
|
|
67
|
+
| `messages` | `EditorMessagesOverride` | — | 文字列の差し替え。同梱しない言語は一式を渡す |
|
|
68
|
+
| `shortcutHelp` | `boolean` | `true` | 組み込みのショートカット一覧(`Mod-Alt-/`) |
|
|
69
|
+
| `contextMenu` | `boolean` | `true` | 組み込みのコンテキストメニュー(右クリック / `Mod-/`) |
|
|
70
|
+
|
|
71
|
+
`viewState` は**今どう見ているか**であって、文書の内容ではない。このモジュールは何も保存しないので、保存先は利用側が決める(保存しなくてもよい)。
|
|
72
|
+
|
|
73
|
+
同梱していない言語は、同梱の一式を土台にする。
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { en, type EditorMessages } from '@14ch/svelte-md-outliner';
|
|
77
|
+
|
|
78
|
+
const fr: EditorMessages = { ...en, editorLabel: 'Éditeur' /* … */ };
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
修飾キーの表記(`⌘` など)は言語ではなく実行環境で決まる。
|
|
82
|
+
|
|
83
|
+
## コンポーネントの API
|
|
84
|
+
|
|
85
|
+
```svelte
|
|
86
|
+
<MarkdownEditor bind:this={editor} />
|
|
87
|
+
<button onclick={() => editor?.resetDocument('# 別の文書\n')}>開き直す</button>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
| | |
|
|
91
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
92
|
+
| `getMarkdown()` | 現在のマークダウン |
|
|
93
|
+
| `getViewState()` | 現在の表示状態 |
|
|
94
|
+
| `resetDocument(markdown)` | 文書を入れ替え、取り消し履歴を初期化する |
|
|
95
|
+
| `writeFrontMatterFields(fields)` | 取り消し履歴・カーソル・選択・本文に触れずに項目を書く。編集中の項目への書き込みは見送る |
|
|
96
|
+
| `focus()` | 編集エリアへフォーカスする |
|
|
97
|
+
|
|
98
|
+
## キーボード
|
|
99
|
+
|
|
100
|
+
`Mod` は macOS では `⌘`、それ以外では `Ctrl`。**一覧は `Mod-Alt-/`** で開く。
|
|
101
|
+
|
|
102
|
+
| | |
|
|
103
|
+
| ------------------------- | ---------------------------------------------------- |
|
|
104
|
+
| `Tab` / `Shift-Tab` | 対象を 1 段深く / 浅くする |
|
|
105
|
+
| `Mod-↑` / `Mod-↓` | 前後の兄弟と入れ替える |
|
|
106
|
+
| `Mod-Enter` | 見出し ⇄ リスト項目 |
|
|
107
|
+
| `Mod-Shift-D` | 複製する |
|
|
108
|
+
| `Mod-Shift-Backspace` | 削除する |
|
|
109
|
+
| `Mod-.` | 畳む / 開く |
|
|
110
|
+
| `Mod-Alt-1`〜`6` | その見出しレベルまで表示する |
|
|
111
|
+
| `Mod-Alt-↑` / `Mod-Alt-↓` | 前後の見出しへ移動する |
|
|
112
|
+
| `Mod-A` | 選択範囲を段階的に広げる(要素内 → ブロック → 全体) |
|
|
113
|
+
| `Mod-/` | コンテキストメニュー |
|
|
114
|
+
|
|
115
|
+
マークアップは入力した時点で変換される(`# ` `- ` `1. ` `[ ] ` `> ` ` ``` ` `---` `**強調**` `` `コード` ``)。**変換直後の `Backspace` で元に戻せる。**
|
|
116
|
+
|
|
117
|
+
## 扱える記法
|
|
118
|
+
|
|
119
|
+
見出し・段落・リスト(箇条書き / 番号付き / チェック)・引用・コードブロック・Mermaid の図・テーブル・水平線・段落内改行・フロントマターと、太字・斜体・打ち消し線・インラインコード・リンク。
|
|
120
|
+
|
|
121
|
+
**開いて保存しても、書いた記法の意味は変わらない。** 揃うのは書き方だけである(`*` の箇条書きは `-`、下線の見出しは `#`、表の区切りは `---`)。
|
|
122
|
+
|
|
123
|
+
画像・インラインの HTML・脚注は、書いた文字が 1 文字も変わらずに残る。**ただし画面上はそのようには表示されない。** 画像は表示されず `` というテキストのまま出る。脚注のマーカーは上付きで表示されるが、クリックしても注へジャンプしないし、注が文書末尾にまとめられることもない。**他のツールで開けばどちらも正しく解釈される**——このエディタが描画しないだけである。
|
|
124
|
+
|
|
125
|
+
## 見た目を変える
|
|
126
|
+
|
|
127
|
+
色・書体・見出しの倍率はすべて CSS カスタムプロパティで、**詳細度 0**(`:where()`)で置いてある。アプリ側の規則が必ず勝つ。同梱の `theme.css` を写して、変えたいトークンだけ残し、後から読み込む。
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
import '@14ch/svelte-md-outliner/styles/editor.css';
|
|
131
|
+
import './my-theme.css';
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```css
|
|
135
|
+
:where(:root) {
|
|
136
|
+
--markdown-editor-accent: #2563eb;
|
|
137
|
+
--markdown-editor-heading-scale-1: 1.75;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
:where([data-theme='dark']) {
|
|
141
|
+
--markdown-editor-surface: #16181d;
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`theme.css` にあるのは色とフォント関連。余白と最大幅は `editor.css` 側にあり、上書きの仕方は同じ。
|
|
146
|
+
|
|
147
|
+
## エディタを使わずに読む
|
|
148
|
+
|
|
149
|
+
一覧表示・マイグレーションスクリプト・サーバーサイドの処理のために、純関数だけのエントリポイントがある。`.svelte` を経由しないので Node から直接 import できる。
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
import { readBody, readBodyBlocks, readFrontMatterField } from '@14ch/svelte-md-outliner/markdown';
|
|
153
|
+
|
|
154
|
+
const title = readFrontMatterField(markdown, 'title');
|
|
155
|
+
// ブロックの位置は本文の先頭からの文字数なので、先にフロントマターを落とす
|
|
156
|
+
const blocks = readBodyBlocks(readBody(markdown));
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
| | |
|
|
160
|
+
| ------------------------------------------ | ---------------------------------------------------------------------- |
|
|
161
|
+
| `readFrontMatterField(markdown, key)` | フロントマターの 1 項目の値 |
|
|
162
|
+
| `readFrontMatterFields(markdown)` | フロントマターの全項目 |
|
|
163
|
+
| `readBody(markdown)` | フロントマターを除いた本文 |
|
|
164
|
+
| `readBodyBlocks(body)` | 本文のブロック一覧(種別・本文中の位置・見出しのパス) |
|
|
165
|
+
| `readPlainText(markdown)` | インライン記法を取り除いたテキスト |
|
|
166
|
+
| `writeFrontMatterFields(markdown, fields)` | フロントマターへの書き込み。区切り・クォート・挿入位置は内部で処理する |
|
|
167
|
+
|
|
168
|
+
**値は文字列のまま返し、型として解釈しない。** これが、このモジュールを YAML の解析器として使い始めないための境界である。
|
|
169
|
+
|
|
170
|
+
## 知っておく制約
|
|
171
|
+
|
|
172
|
+
- **シングルトンの状態を持たない。** 同じページに複数置いても互いに干渉しない
|
|
173
|
+
- **副作用のある import をしない**ので SSR のビルドでも壊れない。ただしエディタ本体はクライアント専用で、サーバー側でレンダリングすると警告を出してプレースホルダーを表示する
|
|
174
|
+
- **永続化を持たない。** 本文も表示状態も公開 API を通し、保存先は利用側が決める
|
|
175
|
+
- **公開 API を小さく保つ。** ProseMirror のスキーマ・プラグイン・コマンドは内部実装のまま
|
|
176
|
+
|
|
177
|
+
## 開発
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
npm run dev # デモ(src/routes/)
|
|
181
|
+
npm run test # 単体・コンポーネント・E2E
|
|
182
|
+
npm run check # 型
|
|
183
|
+
npm run lint # 整形と静的解析
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
仕様は `.kiro/specs/`、規約は `.kiro/steering/` にある。
|
|
187
|
+
|
|
188
|
+
## ライセンス
|
|
189
|
+
|
|
190
|
+
MIT
|
package/README.md
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# @14ch/svelte-md-outliner
|
|
2
|
+
|
|
3
|
+
An **outline editor built on Markdown**, for Svelte 5. Headings form a real nested hierarchy you can fold, focus, and rearrange with `Tab`. What you see is the document — there is no separate preview.
|
|
4
|
+
|
|
5
|
+
日本語版: [README.ja.md](README.ja.md)
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script lang="ts">
|
|
9
|
+
import { MarkdownEditor } from '@14ch/svelte-md-outliner';
|
|
10
|
+
import '@14ch/svelte-md-outliner/styles/editor.css';
|
|
11
|
+
|
|
12
|
+
let value = $state('# Getting started\n\nSome text\n');
|
|
13
|
+
</script>
|
|
14
|
+
|
|
15
|
+
<MarkdownEditor bind:value />
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## What it does
|
|
19
|
+
|
|
20
|
+
- **Build the document out of headings** — `Tab` / `Shift-Tab` re-nest a heading together with everything under it; `Mod-↑` / `Mod-↓` swap siblings
|
|
21
|
+
- **Fold to see the shape** — per-heading folding, or collapse to a chosen level (`Mod-Alt-1`…`6`)
|
|
22
|
+
- **Focus one section** — zoom into a single branch, with a breadcrumb to get back
|
|
23
|
+
- **Markup converts as you type** — `# `, `- `, `1. `, `[ ] `, `> `, `**bold**`, `` `code` ``
|
|
24
|
+
- **Tables, Mermaid diagrams, task lists and front matter**
|
|
25
|
+
- **Built-in context menu and shortcut sheet**, both of which you can turn off
|
|
26
|
+
- **Replaceable strings and theme** — English and Japanese bundled, colors and sizes as CSS custom properties
|
|
27
|
+
|
|
28
|
+
## How it differs from a plain Markdown editor
|
|
29
|
+
|
|
30
|
+
Being an outline editor, the heading hierarchy **is** the document structure rather than decoration. That produces three behaviours worth knowing:
|
|
31
|
+
|
|
32
|
+
- `Tab` on a heading moves it **and everything under it** one level deeper — it does not indent text.
|
|
33
|
+
- Heading levels come from structural depth. `# A` followed by `### B` saves as `## B`: the parent/child relationship survives, the skipped level does not.
|
|
34
|
+
- Folding, focus and the breadcrumb all operate on that hierarchy.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npm install @14ch/svelte-md-outliner
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`svelte@^5` is a peer dependency. Import the stylesheet yourself — it already pulls in the default theme:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import '@14ch/svelte-md-outliner/styles/editor.css';
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Props
|
|
49
|
+
|
|
50
|
+
```svelte
|
|
51
|
+
<MarkdownEditor bind:value bind:viewState label="Meeting notes" maxWidth="42rem" />
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
| | Type | Default | |
|
|
55
|
+
| ------------------- | -------------------------------- | -------- | ----------------------------------------------------------- |
|
|
56
|
+
| `value` | `string` | `''` | Markdown source (bindable) |
|
|
57
|
+
| `onChange` | `(markdown: string) => void` | — | Not needed when you use `bind:value` |
|
|
58
|
+
| `viewState` | `ViewState` | — | Which headings are folded, which section is zoomed |
|
|
59
|
+
| `onViewStateChange` | `(viewState: ViewState) => void` | — | Not needed when you use `bind:viewState` |
|
|
60
|
+
| `label` | `string` | built-in | Accessible name for the editing surface |
|
|
61
|
+
| `readonly` | `boolean` | `false` | Rejects typing, commands and pastes |
|
|
62
|
+
| `autofocus` | `boolean` | `false` | Focus on mount |
|
|
63
|
+
| `class` | `string` | `''` | Extra class names |
|
|
64
|
+
| `padding` | `string` | token | Written exactly like CSS `padding` |
|
|
65
|
+
| `maxWidth` | `string` | token | Line length. **The clickable surface keeps the full width** |
|
|
66
|
+
| `lang` | `'en' \| 'ja'` | `'en'` | Bundled UI language |
|
|
67
|
+
| `messages` | `EditorMessagesOverride` | — | Replace individual strings, or supply a whole language |
|
|
68
|
+
| `shortcutHelp` | `boolean` | `true` | Built-in shortcut sheet (`Mod-Alt-/`) |
|
|
69
|
+
| `contextMenu` | `boolean` | `true` | Built-in context menu (right click / `Mod-/`) |
|
|
70
|
+
|
|
71
|
+
`viewState` is **how you are looking at the document**, not its content. This module stores nothing, so persist it wherever you like — or not at all.
|
|
72
|
+
|
|
73
|
+
For a language that is not bundled, start from a bundled set:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { en, type EditorMessages } from '@14ch/svelte-md-outliner';
|
|
77
|
+
|
|
78
|
+
const fr: EditorMessages = { ...en, editorLabel: 'Éditeur' /* … */ };
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Modifier symbols (`⌘` and friends) follow the platform, not the language.
|
|
82
|
+
|
|
83
|
+
## Component API
|
|
84
|
+
|
|
85
|
+
```svelte
|
|
86
|
+
<MarkdownEditor bind:this={editor} />
|
|
87
|
+
<button onclick={() => editor?.resetDocument('# Another document\n')}>Open another</button>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
| | |
|
|
91
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
92
|
+
| `getMarkdown()` | Current Markdown |
|
|
93
|
+
| `getViewState()` | Current view state |
|
|
94
|
+
| `resetDocument(markdown)` | Replace the document and clear undo history |
|
|
95
|
+
| `writeFrontMatterFields(fields)` | Write front matter without touching undo history, cursor, selection or body. Skips while the user edits that entry |
|
|
96
|
+
| `focus()` | Focus the editing surface |
|
|
97
|
+
|
|
98
|
+
## Keyboard
|
|
99
|
+
|
|
100
|
+
`Mod` is `⌘` on macOS, `Ctrl` elsewhere. **`Mod-Alt-/` opens the full list.**
|
|
101
|
+
|
|
102
|
+
| | |
|
|
103
|
+
| ------------------------- | ----------------------------------------------------- |
|
|
104
|
+
| `Tab` / `Shift-Tab` | Move the target one level deeper / shallower |
|
|
105
|
+
| `Mod-↑` / `Mod-↓` | Swap with the previous / next sibling |
|
|
106
|
+
| `Mod-Enter` | Heading ⇄ list item |
|
|
107
|
+
| `Mod-Shift-D` | Duplicate |
|
|
108
|
+
| `Mod-Shift-Backspace` | Delete |
|
|
109
|
+
| `Mod-.` | Fold / unfold |
|
|
110
|
+
| `Mod-Alt-1`…`6` | Show down to that heading level |
|
|
111
|
+
| `Mod-Alt-↑` / `Mod-Alt-↓` | Previous / next heading |
|
|
112
|
+
| `Mod-A` | Grow the selection (content → block → whole document) |
|
|
113
|
+
| `Mod-/` | Context menu |
|
|
114
|
+
|
|
115
|
+
Markup converts as you type (`# `, `- `, `1. `, `[ ] `, `> `, ` ``` `, `---`, `**bold**`, `` `code` ``). `Backspace` right after a conversion undoes it.
|
|
116
|
+
|
|
117
|
+
## Markdown support
|
|
118
|
+
|
|
119
|
+
Headings, paragraphs, lists (bullet / ordered / task), block quotes, code blocks, Mermaid diagrams, tables, rules, hard breaks and front matter — plus bold, italic, strikethrough, inline code and links.
|
|
120
|
+
|
|
121
|
+
**Opening and saving never changes what your markup means.** Only spelling is normalized: `*` bullets become `-`, setext headings become `#`, table delimiters become `---`.
|
|
122
|
+
|
|
123
|
+
Images, inline HTML and footnotes keep their source text exactly, **but the editor does not display them as such**. An image stays on screen as `` rather than becoming a picture; a footnote marker is drawn as a superscript but does not link to its note, and notes are not collected at the end. Open the file in another tool and both read correctly — this editor simply does not render them.
|
|
124
|
+
|
|
125
|
+
## Theming
|
|
126
|
+
|
|
127
|
+
Every color, font and heading scale is a CSS custom property, declared at zero specificity (`:where()`) so your own rules always win. Copy the bundled `theme.css`, keep the tokens you want to change, and load it after:
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
import '@14ch/svelte-md-outliner/styles/editor.css';
|
|
131
|
+
import './my-theme.css';
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```css
|
|
135
|
+
:where(:root) {
|
|
136
|
+
--markdown-editor-accent: #2563eb;
|
|
137
|
+
--markdown-editor-heading-scale-1: 1.75;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
:where([data-theme='dark']) {
|
|
141
|
+
--markdown-editor-surface: #16181d;
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`theme.css` holds colors and typography. Spacing and line width live in `editor.css` and override the same way.
|
|
146
|
+
|
|
147
|
+
## Reading Markdown without an editor
|
|
148
|
+
|
|
149
|
+
For list views, migration scripts and server-side code, a separate entry point exports pure functions — it never reaches for `.svelte`, so plain Node can import it.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
import { readBody, readBodyBlocks, readFrontMatterField } from '@14ch/svelte-md-outliner/markdown';
|
|
153
|
+
|
|
154
|
+
const title = readFrontMatterField(markdown, 'title');
|
|
155
|
+
// Block offsets are relative to the body, so strip the front matter first
|
|
156
|
+
const blocks = readBodyBlocks(readBody(markdown));
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
| | |
|
|
160
|
+
| ------------------------------------------ | -------------------------------------------------------------------- |
|
|
161
|
+
| `readFrontMatterField(markdown, key)` | One front matter value |
|
|
162
|
+
| `readFrontMatterFields(markdown)` | Every front matter entry |
|
|
163
|
+
| `readBody(markdown)` | The body, front matter removed |
|
|
164
|
+
| `readBodyBlocks(body)` | Top-level blocks: kind, offsets within the body, heading path |
|
|
165
|
+
| `readPlainText(markdown)` | Readable text with inline markup stripped |
|
|
166
|
+
| `writeFrontMatterFields(markdown, fields)` | Write entries; delimiters, quoting and placement are handled for you |
|
|
167
|
+
|
|
168
|
+
Values come back as strings and are never coerced. That boundary keeps this module from turning into a YAML parser.
|
|
169
|
+
|
|
170
|
+
## Constraints worth knowing
|
|
171
|
+
|
|
172
|
+
- **No singleton state.** Several editors on one page never interfere.
|
|
173
|
+
- **No side effects on import**, so an SSR build is safe. The editor itself is client-side: rendering it on the server logs a warning and shows a placeholder.
|
|
174
|
+
- **No persistence.** Document and view state go through the public API; storage is yours.
|
|
175
|
+
- **Small public surface.** The ProseMirror schema, plugins and commands stay internal.
|
|
176
|
+
|
|
177
|
+
## Development
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
npm run dev # demo app (src/routes/)
|
|
181
|
+
npm run test # unit, component and end-to-end
|
|
182
|
+
npm run check # types
|
|
183
|
+
npm run lint # formatting and static analysis
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Specifications live in `.kiro/specs/`, conventions in `.kiro/steering/` (Japanese).
|
|
187
|
+
|
|
188
|
+
## License
|
|
189
|
+
|
|
190
|
+
MIT
|