MarkKit

【EN】Manipulate, visualize, navigate and organize text/code structure: list markers ⇄ ASCII Tree ⇄ Mermaid flowchart, File Outline navigation & edit & drag move, Tab Groups working context 【like Edge/Google tag groups】 — all without learning Mermaid. 【CN】操作、可视化、导航与治理文本/代码结构：列表标记 ⇄ ASCII 树 ⇄ Mermaid 流程图， File Outline 大纲导航&拖拽移动， Tab Groups 工作上下文分组标签【像Edge/Google标签页分组功能】 —— 无需学 Mermaid 语言。

• 🌟 Turn Markdown into well-structured content in seconds — Marker + Structure + Outline + Context.

  • 1. Marker Tools: add / toggle / strip list markers (ordered, unordered, quote, custom prefix) on any selection — even in SQL / JS / TXT.
  • 2. Structure Tools: convert Markdown structure ⇄ ASCII tree ⇄ Mermaid flowchart — visualize hierarchy and relationships at a glance.
  • 3. File Outline: turn any text/code file (SQL / Python / JS / CSS / TXT…) into a navigable and editable Markdown-style outline — -- # Section, // ## Sub.
  • 4. Context / Tab Groups: organize the files you're working on into named groups — close a tab without losing the group, drag & drop to reorder.
  • 5. Context Snapshot: save & restore your whole working context — groups, file order, and workspace roots — as a portable .markkit-context.json. Survives closing VS Code and even moving the project to a new path.
  • 6. Markdown Icons: click-to-copy symbol palette (emoji, kaomoji 颜表情, arrows, math, …) inside the sidebar.

• 💡 Workflow: Write → Select → Mark → Chain the structure ↔ back to cleaner Markdown.

• 💡 Example: You can customize the prefix "- [ ]" for to‑do items. To express a graph without learning Mermaid, write plain chain syntax and it becomes a flowchart (不用学 mermaid 的语法):

  LR 
  a-b-<xxx>-c-b-a
  d-b
  

  
  
  

【中文版介绍请见底部】

30-second understanding

Open any Markdown (or SQL / JS / TXT)
        ↓
Mark lines: Ordered / Unordered / Quote / Custom / Delete blank line
        ↓
Convert structure ⇄ ASCII tree ⇄ Mermaid — or copy its outline
        ↓
Navigate any file via File Outline (# / ## / ###) / drag / edit
        ↓
Group related files in Context / Tab Groups 【like Edge/Google tag groups】
        ↓
Copy / Replace in place — done in seconds

1. Marker Tools

            MarkKit Marker Tools
                 │
   ┌─────────────┼─────────────┬───────────┐
   ↓             ↓             ↓           ↓
 Ordered      Unordered      Quote      Custom
   │             │             │           │
 1. a. i.       - * + •         >        // -- $ # -[x] 
 8 formats     4 formats      single    any prefix you define
                 │
                 │    Numbering: auto / continuous / perBlock
                 ↓
       Apply / Toggle / Strip (layer by layer)

2. Structure Tools (Tree + Mermaid)

   Markdown (unordered / ordered / heading)  ⇄  ASCII Tree  ⇄  Mermaid flowchart
                  │                                                │
                  ↓                                                ↓
         parse hierarchy                                     copy / preview / replace

The Structure Converter panel (sidebar STRUCTURE entry) is a single three-way switch:

• Input type — Auto by default detects whether your selection is Markdown / ASCII tree / Mermaid / graph syntax; a Manual folder lets you force one if auto-detection ever guesses wrong.
• Output type — ASCII Tree, Markdown, or Mermaid. When Markdown is chosen, pick the form you want: - unordered list, 1. numbered list, or ## headings.
• Select text, open the converter, and it auto-fills the input; converting, previewing, and replacing the selection (single undo) work the same as before.

3. File Outline: navigate any text/code file

MarkKit gives any text file a Markdown-style section outline. Inside your file, define hierarchy with # / ## / ### behind your language's comment prefix — the MarkKit Outline TreeView lists it as a navigable tree. Click a node to jump to its exact line.

-- # 用户分析
-- ## 注册用户
-- ### 新用户
-- ### 老用户
-- ## 活跃用户

• Default syntax is language comment; switch to custom prefix (@, MK, …) via markdownStructureTools.outline.syntax.
• Levels 1–6, level jumps allowed (# A → ### C nests C under A, no phantom nodes).
• Same # language feeds back into Structure: Outline → ASCII / Mermaid, and ASCII → Outline (to SQL/Python/JS/CSS comments).

3a. Outline Editor — edit the file structure from the tree (v0.4)

MarkKit Outline is no longer read-only. Rename, reparent and delete sections from the tree; MarkKit writes the change back to the source file.

One tree node = one Section Block, not one line of marker. A node owns from its marker line down to the next marker of the same or higher level — so dragging a node drags its entire section and code block with it. This is what makes reshaping a SQL CTE chain painless: drag user_base and its whole select … block travels.

-- # 用户分析
-- ## 注册用户        ← drag this node…
select ...             ← …this body comes along
-- ## 活跃用户

• Promote / Demote = level change only — they rewrite just that node's marker (### → ##) and never move the Section Block or touch its children (# B + ### C stays legal after promoting B).
• Move = reparent / reorder — this is the one that actually relocates things. Dropping B Into D rebases the whole subtree so relative depth is preserved (B = target + 1, children shift by the same delta).
• Drag is same-document only, and refuses to drop a node into its own descendant.
• Every action is one undo (Ctrl/Cmd+Z). MarkKit never reformats the file — indentation, blank lines, trailing whitespace and EOL are preserved byte-for-byte.
• Auto Outline nodes (SQL CTE, e.g. Query / user_base) are read-only until you materialize them: right-click → Convert to Explicit Outline writes -- # Query / -- ## <cte> into the file, and they become editable. It's idempotent — already-marked entries are skipped, so running it again is safe. Your SQL body is never modified, only marker lines are inserted (one undo).

4. Context: Tab Groups for your working set

The MarkKit Context view groups the files you're currently working on into named, persistent collections — a lightweight "what am I focusing on" layer, not a file-manager replacement.

📊 Revenue Analysis
   user.sql
   revenue.sql
   dashboard.tsx

💻 Auth Refactor
   auth.ts
   login.tsx

• Create / rename / delete / reorder groups; expand several groups side by side.
• One file → one group; drag files across groups, reorder files within a group, and drag groups to reorder them.
• Multi-select — Ctrl/Cmd+click several files, then right-click → Remove from Group / Move to Group, or just drag the whole selection to another group.
• Closing a tab ≠ removing from the group — the file stays in the group (shown as closed), and only returns to Ungrouped when you explicitly remove it.
• All / Active filter and Focus one or several groups (right-click any group → Focus Group → tick the ones you want); auto-detected missing files (moved/deleted outside VS Code) show a ⚠ and can be re-linked via Locate File.
• Group icon & color — each group takes a Codicon (folder / database / rocket / …) plus one of 9 distinct pastel theme colors.
• Same-name files are disambiguated — since a group is a work topic, not a project, it can hold several index.html. MarkKit appends the shortest path that tells them apart (A/ vs B/src/) as a secondary description; unique files stay uncluttered. Configure via ⚙ Context Settings → Same-name files only (default) / All files / Never.
• Everything persists to workspaceState, and file renames/moves are tracked automatically — display paths are always re-derived from the live URI, never stored.
• Snapshot your whole working context (v0.4.4) — workspaceState is keyed to the current window, so reopening VS Code (or switching machines) loses your groups. Save Context Snapshot... writes a portable .markkit-context.json (plus a companion .code-workspace) next to your project; Import Context Snapshot... restores the workspace roots, every group with its icon/color/order, file membership and order, and the File Path Display setting. Files are re-located via workspace folder + relative path, so even moving the whole project from /old/project to /new/project still works. See FAQ 5.

Why MarkKit?

Structural editing in Markdown is repetitive: typing - , 1., > by hand is slow, inconsistent, and error-prone. MarkKit solves both directions of that problem.

Product map

MarkKit
├─ Marker Tools (any text file)
│  ├─ Ordered   (1. 1) 1、 ① ❶ (1) a. A. i.)
│  ├─ Unordered (- * + •)
│  ├─ Quote     (>)
│  └─ Custom    (// -- $ # - [ ]  … any prefix)
│     └─ Numbering: auto / continuous / perBlock
├─ Structure Tools (Tree + Mermaid)
│  ├─ Markdown ⇄ ASCII Tree (list / ordered / heading)
│  ├─ Markdown ⇄ Mermaid (flowchart TD)
│  └─ Graph syntax A-B-C / A-B-C-A
├─ Outline — File Outline (any text / code file)
│  ├─ MarkKit Outline native TreeView
│  ├─ Syntax: language comment (-- #) / custom prefix (@#)
│  ├─ Levels 1–6, level jump, click-to-jump, auto refresh
│  └─ Outline ⇄ Structure ⇄ ASCII / Mermaid
├─ Context — Tab Groups (working set)
│  ├─ MarkKit Context native TreeView + D&D
│  ├─ Manual groups: create / rename / delete / reorder
│  ├─ One file → one group; close tab ≠ remove from group
│  ├─ All / Active filter + Focus + missing reconcile
│  └─ workspaceState persistence + rename/move tracking
├─ Sidebar panel
│  ├─ Available Styles + Prefixes
│  ├─ Current formats
│  ├─ STRUCTURE (three-way Structure Converter)
│  │  ├─ Input: Auto (detect) / Manual (force type)
│  │  ├─ Output: ASCII / Markdown (- 1. ##) / Mermaid
│  │  ├─ Copy text / Copy PNG / Preview / Replace
│  └─ TOOLS — Markdown Icons palette
├─ Structure Converter panel (Copy / Preview / Replace)
└─ Entry points: context menu / lightbulb / command palette / shortcuts

Keyboard shortcuts (can be customized)

Active in Markdown files with a selection (editorLangId == markdown && editorHasSelection).

Customize: Cmd+K Cmd+S → search "MarkKit", or edit keybindings.json via Preferences: Open Keyboard Shortcuts (JSON):

{
  "key": "ctrl+alt+1",
  "command": "markdownStructureTools.toggleOrdered",
  "when": "editorLangId == markdown && editorHasSelection"
}

No Mermaid required. To draw a graph, just write the connections as plain chains: To add a label on an edge, wrap the text in <...> between the hyphens: write a-b-<1.复制>-c to get a b -->|1.复制| c edge. Plain - edges remain unlabeled; mix freely in one line. To control the layout direction, put a single line TD / LR / RL / BT / TB before the chain:

LR
a-b-<xx>-c-d-a
a-d

Open the Structure Converter (STRUCTURE) with a chain like this selected — input Auto recognizes it and converts straight to a flowchart. No need to learn Mermaid.

Supported files & limitations

🌟FAQ

1.How do I focus several groups at once, and how do I leave focus? Right-click any group → Focus Group → a checklist appears. Tick the groups you want to work on together; untick one to drop it. Unfocused groups stay visible but greyed out at the bottom, so you can always right-click another one to add it. To leave focus entirely: right-click → Clear Focus, or Shift+Cmd+P → Clear Focus.

2.What does "Add Active Tabs" do (right-click a group)? It collects all currently open editor tabs into that group at once — no dragging one by one. Example: with user.sql / revenue.sql / dashboard.tsx open, right-click a group → Add Active Tabs → all three files land in the group.

3.How do I remove several files from a group at once?（Same as Move to Group） Ctrl/Cmd+click to select multiple files, then right-click → Remove from Group. Ctrl/Cmd+click to select multiple files, then right-click → Move to Group, or drag directly into the new group.

3b.Several files in one group have the same name — how do I tell them apart? A group is a work topic (e.g. todolist, bug-fix), not a project, so it can easily hold several index.html or 交互 prompt.md. MarkKit appends a secondary path after the file name:

todolist
├── index.html    A/            ← A/index.html
├── index.html    B/            ← B/index.html
├── index.html    「028」…/      ← 「028」行业热点分析/…/index.html
└── app.ts                      ← unique, no path shown

Click the ⚙ settings button in the MARKKIT CONTEXT view title bar → pick a File Path Display preference:

• Same-name files only — the default. The path appears only for files whose name collides inside the same group, using the shortest path that tells them apart. Unique files stay clean.
• All files — every file also shows its folder.
• Never — only the file name, even when ambiguous.

The path is always the shortest one that disambiguates: A/x + B/x → A/ B/; but A/src/x + B/src/x → A/src/ B/src/ (because src/ alone would be identical). Multi-root workspaces fall back to the workspace folder name (Frontend/src/) when relative paths still collide. The setting is per-workspace.

4.What do the right-click actions on an Outline node mean? Click a node to select it, then right-click it:

Rule of thumb: Promote / Demote change a node's depth. Move changes a node's parent or sibling order. Auto nodes can't be edited directly — run Convert to Explicit Outline first, then they behave like any other node.

5.How do I back up and restore my whole working context (groups + workspace roots)?

First, Save Context Snapshot... (💾 in the MARKKIT CONTEXT view title bar). There are two ways to restore:

【Method 1】 — Restore the workspace roots too (recommended)

Save Context Snapshot...
        ↓
Double-click (or right-click → Open with VS Code / Trae) my-work.code-workspace
        ↓
The Explorer immediately shows all your workspace roots — before any extension runs
        ↓
In MARKKIT CONTEXT, click the Import icon
        ↓
Groups are restored

【Method 2】 — Import only (groups without roots)

In MARKKIT CONTEXT, click the Import icon directly
        ↓
MarkKit asks you to pick each workspace root folder by hand
        ↓
Pick them all → both workspace roots and groups are restored
   — or —
Click Cancel → the Explorer workspace is left untouched,
               but the group context is still restored

Notes:

• Files that can't be found (deleted, renamed, or on a machine that doesn't have them) stay in their group and show ⚠ missing — membership and ordering are preserved, so nothing shifts around.
• Restoring is a replace: the current groups are swapped for the snapshot's. If groups already exist, MarkKit asks for confirmation first (it can't be undone).
• A snapshot that was saved on an older layout still resolves, because files are identified by workspace folder + relative path, not by absolute path.

Feedback

Found a bug or have a feature request? Open an issue in the extension repository, or reach me via WeChat (Yvonne1ru, please state your issue in the verification message).

MarkKit 中文说明

打开任意 Markdown（或 SQL / JS / TXT）
        ↓
选中要改的行
        ↓
打标记：有序 / 无序 / 引用 / 自定义前缀 / 删除空行
        ↓
结构 ⇄ ASCII 树 ⇄ Mermaid 转换 —— 或复制其大纲
        ↓
用 File Outline（# / ## / ###）导航任意文件
        ↓
用 Context / Tab Groups 分组收纳相关文件
        ↓
复制 / 就地替换，几秒完成

            MarkKit Marker Tools
                 │
   ┌─────────────┼─────────────┬───────────┐
   ↓             ↓             ↓           ↓
 有序         无序          引用        自定义
   │             │             │           │
 1. a. i.       - * + •         >        // -- $ # -[x]
 8 种格式     4 种格式       单级      任意前缀
                 │
                 │    编号：auto / continuous / perBlock
                 ↓
       应用 / 切换 / 逐层剥离

   Markdown（无序 / 有序 / 标题）  ⇄  ASCII 树  ⇄  Mermaid 流程图
                  │                                 │
                  ↓                                 ↓
         解析层级                             复制 / 预览 / 替换

-- # 用户分析
-- ## 注册用户
-- ### 新用户
-- ### 老用户
-- ## 活跃用户

源文件  ←→  Outline 树        （源文件始终是唯一事实来源）

-- # 用户分析
-- ## 注册用户        ← 拖这个节点…
select ...             ← …这段正文跟着走
-- ## 活跃用户

📊 Revenue Analysis
   user.sql
   revenue.sql
   dashboard.tsx

💻 Auth Refactor
   auth.ts
   login.tsx

MarkKit
├─ Marker Tools（适用于任意文本文件）
│  ├─ 有序   (1. 1) 1、 ① ❶ (1) a. A. i.)
│  ├─ 无序   (- * + •)
│  ├─ 引用   (>)
│  └─ 自定义 (// -- $ # - [ ]  … 任意前缀)
│     └─ 编号：auto / continuous / perBlock
├─ Structure Tools（Tree + Mermaid）
│  ├─ Markdown ⇄ ASCII 树（无序 / 有序 / 标题）
│  ├─ Markdown ⇄ Mermaid（flowchart TD）
│  └─ 图语法 A-B-C / A-B-C-A
├─ Outline —— File Outline（任意文本 / 代码文件）
│  ├─ MarkKit Outline 原生 TreeView
│  ├─ 语法：语言注释（-- #）/ 自定义前缀（@#）
│  ├─ 层级 1–6、跳级、点击跳转、自动刷新
│  └─ Outline ⇄ Structure ⇄ ASCII / Mermaid
├─ Context —— Tab Groups（工作上下文）
│  ├─ MarkKit Context 原生 TreeView + 拖拽
│  ├─ 手动分组：建 / 改名 / 删 / 重排
│  ├─ 一文件一组；关 Tab ≠ 移出分组
│  ├─ All / Active 过滤 + Focus + missing 恢复
│  └─ workspaceState 持久化 + 重命名/移动追踪
├─ 侧边栏面板
│  ├─ 可用样式 + 前缀
│  ├─ 当前格式
│  ├─ STRUCTURE（三向 Structure Converter）
│  └─ Actions + TOOLS（Markdown Icons）
├─ Tree Converter 面板（复制 / 就地替换）
└─ 入口：右键菜单 / 灯泡 / 命令面板 / 快捷键

Apple        →  有序    →  1. Apple
Banana          无序       - Banana
                引用       > Orange
             自定义前缀    // Pear

aaa          →  1. aaa
    bbb             1. bbb
    ccc             2. ccc
ddd             2. ddd

aaa          →  1. aaa
    bbb             1.1 bbb
    ccc             1.2 ccc
ddd             2. ddd

LR
a-b-<xx>-c-d-a
a-d

todolist
├── index.html    A/            ← A/index.html
├── index.html    B/            ← B/index.html
├── index.html    「028」…/      ← 「028」行业热点分析/…/index.html
└── app.ts                      ← 不冲突，不显示路径

Save Context Snapshot...
         ↓
双击 my-work.code-workspace（或右键 →「用 VS Code / Trae 打开」）
         ↓
资源管理器立刻显示全部 workspace 根目录 —— 在扩展启动之前就已就位
         ↓
在 MARKKIT CONTEXT 点 Import 图标
         ↓
group 上下文恢复

在 MARKKIT CONTEXT 直接点 Import 图标
         ↓
MarkKit 提示你手动选择全部根目录文件夹的路径
         ↓
都选上 → 资源管理器 workspace 和 group 上下文一起恢复
   —— 或者 ——
点「取消」→ 资源管理器 workspace 不恢复，
             但 group 上下文依旧会恢复