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.

Table of contents

• Why this plugin
• Feature set
• Interface preview
• Scroll synchronisation
• Installation
  • Manual installation — current release path
  • Community Plugins — pending submission
• Usage
  • Create a label
  • Link a label to source text
  • Move and resize
  • Change appearance
  • Preview Markdown
• Editing Toolbar compatibility
• Storage model
• Development
  • Prerequisites
  • Run locally
  • Build a release
• Testing
• Repository assets
• Contributing
• License

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

Capability	What it does
Floating labels	Add an editable annotation anywhere over the current note.
Document-positioned scrolling	Labels use document-space coordinates and move with the page when you scroll.
Text links	Select source text, create a label, and retain an interactive link between the two.
Context toggle	Ctrl + click linked text on Windows/Linux, or Cmd + click on macOS, to show or hide associated labels.
Flexible layout	Drag with the header and resize from the lower-right handle.
Minimal interface	Controls stay hidden until the label is hovered or focused.
Appearance controls	Set a label background colour and transparency from the right-click menu.
Markdown preview	Switch a label between Markdown source and a rendered preview.
Safe note body	Label content and geometry are stored in plugin data, not inserted into the Markdown file.

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

Asset	Purpose
assets/logo.svg	Repository avatar, release asset, and future directory branding.
assets/hero-banner.svg	GitHub README header.
docs/images/scroll-sync-demo.gif	Visual explanation of the v0.7.0 scroll behaviour.
docs/images/*.svg	Editable dark-theme preview set.

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