note-transit

Keep blocks, heading sections and moved text in a sidebar of Markdown-backed cards. Drag text out of a note while writing, then bring it back wherever it belongs.

中文说明 · Development · Release procedure · Changelog

Features

• Block references use native ![[Note#^block-id]] embeds. Reuse an existing block ID or add one to the selected blocks.
• Heading references show a section with ![[Note#Heading]], without adding markers to the source.
• Move to the sidebar by dragging a text selection into the panel. The card is saved before the exact selection is removed.
• Drag back to the editor using the top of a card. Moved text is inserted at the drop position; its card is deleted only after the destination saves successfully. Reference cards insert a native embed and stay in the sidebar.
• Navigate to the source and briefly highlight the referenced block or heading. Moved cards open their source file.
• Keep your data in Markdown: one file per card, with content and metadata stored together. The default folder is note-transit/, configurable inside the vault.
• Clean up owned markers when deleting a reference card. Shared references keep their block IDs, and user-created block IDs are never removed.

Installation

The plugin is being prepared for its first community-directory submission; it is not claimed to be listed yet.

For manual installation, download main.js, manifest.json and styles.css from a published GitHub Release and put them in <vault>/.obsidian/plugins/note-transit/ (use your vault's configured settings folder if different). Reload Obsidian and enable note-transit under Settings → Community plugins.

The declared API baseline is Obsidian 1.8.0. Compatibility with older app versions and physical mobile devices has not yet been verified. Desktop dragging requires an editable Markdown view; commands provide an alternative on devices without drag-and-drop.

Usage

1. Open the panel with the ribbon icon or the 打开侧记面板 command. The current UI is in Simplified Chinese.
2. Select text in editing mode or Live Preview. Use the context menu or 引用选中段落 command for a block reference. Partial selections expand to complete blocks.
3. Put the cursor in a heading or its section and run 引用当前标题章节 to reference that section. Duplicate headings require a block reference instead.
4. Drag a selection into the sidebar, or run 将选中文字移入侧记, to move it out of the source note.
5. Drag a card's type/source header to the main editor to insert at the mouse position. A moved card inserts its content and disappears after saving; a reference card inserts its embed and remains available.
6. Use 定位原文 to navigate and highlight, 打开来源 for a moved card's source file, or 编辑侧记 to edit the card Markdown directly.

No hotkeys are assigned by default. Bind the commands in Obsidian's hotkey settings if desired.

Storage and recovery

Each card is a Markdown file under the configured folder. Moving text preserves its whitespace, and resolved links are regenerated for the destination folder. A block-reference card looks like this:

---
side-note-id: "example-id"
side-note-version: 1
mode: reference
created: "2026-11-04T01:00:00Z"
source: "[[Notes/Design]]"
source-file: "Notes/Design.md"
reference-type: block
anchors:
  - { id: "sn-example", owned: true }
---

![[Notes/Design#^sn-example]]

The side-note-* metadata names are retained for compatibility with existing cards. Settings store only the folder and highlight duration; there is no separate card database. Changing the folder switches the displayed cards without moving existing files.

When a save fails or content changes during a move, the plugin retains the existing copy instead of deleting it. Undoing a text move restores the source text and leaves the saved card. Undoing insertion after a successful card-to-editor move does not restore its deleted card; use your configured trash mechanism to recover that file.

Deleting a card follows Obsidian's file-deletion setting. The cleanup option scans Markdown references, card metadata, unsaved editor text and Canvas before removing an unused plugin-owned sn- marker. If you may restore a reference card later, choose the option to keep its markers. Deleting a Markdown file outside the sidebar does not clean up its source markers.

Limitations

• Native block embeds show complete blocks, not arbitrary character ranges. Supported structures include paragraphs, headings, lists, quotes, callouts, code and tables.
• Renamed or missing headings, removed blocks and missing source files show a warning. The plugin does not guess a replacement heading.
• A multi-block card navigates to its first block. Highlight duration defaults to two seconds and can be changed.
• Reading mode cannot create selection cards. Cards must be dropped into an editable Markdown note in the main area, not into their own card file.
• Source renames while the plugin is enabled update card metadata. External renames while it is disabled may require manual repair.
• Unresolved relative links, reference-style Markdown links and incomplete Markdown selections may need manual adjustment after a move.

Privacy

No accounts, payments, advertisements or telemetry. The runtime makes no network requests and uses Obsidian APIs to read and write files inside the current vault. It can add reference block IDs, edit selected text, create card files and delete cards or unused owned markers as described above.

Obsidian's Markdown renderer may load remote images or embeds already present in your notes according to your app configuration. The plugin does not introduce a separate remote service. The development installer is separate from the runtime and writes only to the vault supplied by the developer.

Development

Use Node.js 22.15 or later:

npm ci
npm run check
npm run package
npm run install:local -- /absolute/path/to/test-vault

npm run check runs Obsidian ESLint rules, TypeScript checks, automated regression tests and release validation. dist/note-transit/ contains the three manual-install files. A version tag creates a draft GitHub Release; see the release procedure for public release and community submission steps.

License and acknowledgments

MIT, copyright maxwell.

The repository's release structure was informed by cparsell/sidenotes and Obsidian's sample-plugin conventions. note-transit's runtime was developed independently and includes no code from sidenotes.