MARK IT DOWN
Mark It Down
पेज · Mark It Down

Notes Sidebar

Status: shipped in Phase 0.7 · Issue: #7

The Notes sidebar is a dedicated VSCode activity-bar surface for capturing, organizing, and editing personal notes — without leaving the editor and without polluting the workspace file tree. Notes are real markdown files, opened through the same Mark It Down custom editor used for any .md file in the workspace, so everything you can do in the viewer (live mermaid, code-block copy, tables) works on notes too.

At a glance

WhereActivity bar (left rail) → "Mark It Down" icon → Notes view
Storage backendVSCode workspaceState + globalState (metadata) and storageUri / globalStorageUri (markdown content)
Editor surfaceThe existing Mark It Down custom editor — no second editor, no extra parser
Two scopesWorkspace (visible only in this folder) and Global (everywhere)
CategoriesUser-configurable; defaults to Daily / Reference / Snippet / Drafts
Per-machine?Workspace notes are folder-scoped. Global notes are user-scoped (per VSCode profile). Cross-machine sync arrives in F9 (warehouse repo)

Tree shape

text
  • Notes inside a category are sorted most-recent-first by updatedAt.
  • A category appears in the tree if it is either listed in markItDown.notes.categories or has at least one note in it. So if you remove a category from settings but still have notes filed under it, the tree continues to surface them (under the original name) so nothing is hidden.

Two storage scopes

Workspace

  • Metadata key: markItDown.notes.index in context.workspaceState
  • Content files: ${context.storageUri}/notes/<id>.md
  • Visible only in the VSCode workspace where the notes were created.
  • Use this for project-bound notes: sprint logs, code-review checklists, design-doc drafts that live with the codebase but aren't part of the codebase.
  • Unavailable when no folder is open — VSCode does not provide storageUri for a folder-less window. The tree quietly drops the Workspace root in that case.

Global

  • Metadata key: markItDown.notes.index in context.globalState
  • Content files: ${context.globalStorageUri}/notes/<id>.md
  • Visible across every VSCode workspace on the same machine, scoped to the active VSCode profile.
  • Use this for personal stuff: daily journal, recipes, reference snippets that follow you between projects.

If you're unsure which scope to pick, the new-note flow's Quick Pick previews both with a description.

Commands

All commands are prefixed Mark It Down: in the command palette.

Command IDTitleWhere it shows
markItDown.notes.createNew NoteView title bar (+) · scope/category context menus (inline +) · command palette
markItDown.notes.openOpen NoteCommand palette (Quick Pick of all notes) · invoked when clicking a tree leaf
markItDown.notes.renameRename NoteNote context menu (inline pencil)
markItDown.notes.moveMove to Category…Note context menu
markItDown.notes.deleteDelete NoteNote context menu (inline trash)
markItDown.notes.refreshRefreshView title bar (↻)
markItDown.notes.revealStorageReveal Notes FolderView title bar overflow menu

The destructive context-menu commands (rename, move, delete) are hidden from the command palette so you cannot fire them without a target — see package.json#contributes.menus.commandPalette.

Settings

SettingDefaultWhat it does
markItDown.notes.categories["Daily", "Reference", "Snippet", "Drafts"]List of categories shown in the tree and offered when creating/moving a note. Empty entries are ignored. Categories used by existing notes still appear even if removed from this list.
markItDown.notes.defaultCategory"Drafts"Pre-selected entry in the category Quick Pick when creating a note. If the value isn't in categories, the first listed category wins.
markItDown.notes.defaultScope"workspace""workspace" or "global". Pre-selects the scope on new-note Quick Pick. Falls back to "global" automatically when no folder is open.

Edit via Cmd+, → search "Mark It Down: Notes" or directly in settings.json:

json

Workflows

Creating a note

  1. Open the Notes sidebar.
  2. Click + in the view title bar (or right-click a scope/category row → New Note).
  3. Scope — Workspace or Global. Skipped if you launched from a scope/category row that already pinned one.
  4. Category — pick from the configured list, or + New category… to type one inline.
  5. Title — required, free text.
  6. The note opens immediately in the Mark It Down custom editor with a # Title heading pre-populated. Save (Cmd+S) any time; the tree updates with a fresh updatedAt.

Renaming a note

Right-click a note → Rename Note. The new title is reflected in the tree. The underlying file's <id>.md filename is not changed — the note's stable identifier is its random id, and the title is purely metadata. This avoids breaking external references (used later by F8 MCP and F9 warehouse).

Moving a note between categories

Right-click a note → Move to Category…. Pick the destination from the category Quick Pick (same picker as create — supports + New category…). The file stays put on disk; only the metadata category field changes.

Deleting a note

Right-click a note → Delete Note → confirm in the modal. The metadata entry is removed and the file is unlinked from <storage>/notes/<id>.md. There is no soft-delete or trash in v0.7 — once confirmed, the note is gone.

Inspecting on disk

Right-click empty space in the Notes view → Reveal Notes Folder (or run from the title-bar overflow). VSCode opens the Notes folder in your OS file manager. Useful for backups, manual edits, or wiring third-party tools.

How the data is stored

Metadata (per scope) lives in VSCode's key/value state under markItDown.notes.index. Each entry is:

ts

Content is a plain markdown file at <storageRoot>/notes/<id>.md where <storageRoot> is context.storageUri (workspace) or context.globalStorageUri (global). The file is created with # <title>\n\n as a starter; everything after that is normal markdown.

Why split metadata and content?

  • Renames are cheap — just edit a string in the index, no file move.
  • Sorting and grouping are O(N) over a small index, no per-file reads needed when the tree refreshes.
  • The custom editor stays unchanged — it operates on a real vscode.Uri, exactly like any other .md in the workspace. No virtual-FS plumbing.
  • Future features (F8 MCP server, F9 warehouse, F13 Claude plugin) can read the same <id>.md files and the same index without duplicating storage.

Edge cases & behavior notes

  • No folder open — Workspace storage is unavailable (VSCode quirk). The tree drops the Workspace root automatically; the new-note Quick Pick auto-selects Global with a status message.
  • Empty configured categories list — falls back to the four defaults so you never see an empty tree.
  • Category not in settings but used by a note — still rendered. Editing settings to remove a category does not orphan its notes.
  • Save bumps timestamp — saving a note in the custom editor (Cmd+S) calls NotesStore.touch(uri), which refreshes updatedAt and re-fires the tree-change emitter. The note jumps to the top of its category.
  • Content-only edits outside the custom editor (e.g. opening the file directly with the default editor and saving) do update updatedAt — the save listener watches every vscode.workspace.onDidSaveTextDocument, not just custom-editor saves.
  • Crash safety — both metadata and content are written through vscode.workspace.fs and the VSCode state APIs, which are atomic at the call boundary. There is no in-memory write-behind.
  • Concurrent windows — two VSCode windows pointing at the same Global storage will race on metadata writes. The last writer wins. Multi-window safety is deferred to F9 (warehouse), where a real conflict policy lives.

What it unblocks

FeatureHow it builds on F6
F8 — MCP serverExposes list_notes / get_note / create_note / update_note / delete_note over stdio. Reads the same NotesStore and the same <id>.md files.
F9 — Notes warehouse repoPushes the contents of <storageRoot>/notes/ to a configured GitHub repo. Pull merges back into the same files.
F13 — Claude Code pluginBundles skills (/mid:new-note, /mid:list-notes, /mid:open) that wrap the same store via the F8 MCP server.

Files of interest