Floating Text Overlay

Movable, resizable Markdown annotations that remain attached to the part of an Obsidian note where they matter.

[!NOTE] v0.7.0 introduces document-positioned labels with scroll synchronisation. A label now moves with the note content instead of remaining fixed in the reading viewport.

Why this plugin

Markdown notes are inherently linear. Research, revision, planning, and review work often require short contextual annotations that should sit beside an idea without interrupting the original document flow.

Floating Text Overlay adds editable note widgets above a Markdown note. A widget can be moved, resized, linked to selected text, hidden and reopened from that text, and styled independently. The original Markdown file remains untouched.

Feature set

Interface preview

These editable SVG previews establish the intended dark-theme visual language. Before submitting to Obsidian Community Plugins, replace them with captures from a local test vault that show the released interface exactly.

Editable floating label	Linked source text
Right-click appearance controls	Scroll synchronisation

Scroll synchronisation

A label's coordinates are now measured relative to the note document rather than the visible window.

• Create a label halfway down a long note: it remains beside that document region.
• Scroll the note: the label moves up or down with the corresponding Markdown content.
• Drag and resize operations respect the scrollable document dimensions, not only the visible viewport.
• The scroll listener is scoped to each rendered Markdown view and is removed when the view or the plugin unloads.

Installation

Manual installation — current release path

1. Download the latest Release from this repository.

2. Create the folder below inside your vault:

   <vault>/.obsidian/plugins/floating-text-overlay/
   

3. Copy these release assets into that folder:

   main.js
   manifest.json
   styles.css
   

4. In Obsidian, open Settings → Community plugins and enable Floating Text Overlay.

Community Plugins — pending submission

The plugin is not yet listed in Obsidian's Community Plugins directory. Once it has passed the submission review, users will be able to install it from Settings → Community plugins → Browse.

Usage

Create a label

Open a Markdown note and use either the ribbon icon or the command:

Floating Text Overlay: Add floating text box

A newly created, untouched empty label is only a transient draft. It is saved after a real action such as typing, dragging, resizing, styling, previewing, or explicitly linking text.

Link a label to source text

1. In Live Preview or Source mode, select non-empty text in the Markdown editor.
2. Create a floating label. The label is linked automatically.
3. Alternatively, select text, right-click an existing label, and choose Link current selection.
4. Use Ctrl + click / Cmd + click on the highlighted linked text to toggle the label.

Move and resize

• Hover the label to reveal its header.
• Drag the header to move the label.
• Drag the lower-right corner handle to resize it.

Change appearance

Right-click a label to change its background colour and transparency. New labels start with a white surface.

Preview Markdown

Click Preview Markdown from the label footer. Click Back to edit to return to the source editor.

Editing Toolbar compatibility

This plugin includes an experimental bridge for Editing Toolbar. Keep the floating label focused, select text inside it, then invoke a toolbar command.

The bridge is intended for common Markdown operations such as bold, italic, headings, lists, inline code, undo/redo, font colour, and background colour. Since Editing Toolbar is a separate community plugin with its own command registration and UI modes, verify the exact buttons you use in your vault before release. Track results in TESTING.md.

Storage model

Floating label state is stored in the plugin's Obsidian data file, keyed by note path. The following values are persisted after a meaningful edit:

• label text
• document-space position
• width and height
• background colour and opacity
• visibility state
• optional linked-text anchor and contextual metadata

Moving or resizing a label does not write, reflow, or insert content into the note's Markdown body.

Development

Prerequisites

• Node.js 18 or later
• Obsidian desktop
• A separate test vault

Run locally

npm install
npm run dev

During development, place the repository at:

<test-vault>/.obsidian/plugins/floating-text-overlay/

Reload Obsidian after a build. The folder name must match the plugin id in manifest.json.

Build a release

npm run build
npm run docs:toc

A GitHub release must attach:

main.js
manifest.json
styles.css

The release tag must match manifest.json, for example 0.7.0.

Testing

Follow the full workflow in TESTING.md. The scroll-specific regression test should be run in both Live Preview and Reading View with a note long enough to scroll through multiple screen heights.

Repository assets

Contributing

Open an issue with a reproducible vault setup, Obsidian version, operating system, theme, enabled editor plugins, and screenshots or screen recording. Pull requests are welcome for isolated, tested improvements.

License

MIT © 2026 Qiuyi Liao