joplin-plugin-minimap 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lim0513
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Joplin Minimap
+
+A hover-to-expand table of contents minimap for the [Joplin](https://joplinapp.org/) note viewer — heading tick marks on the right edge that expand into a clickable outline.
+
+[中文说明](README-CN.md) | [日本語](README-JA.md)
+
+## Features
+
+- **Tick Bar Minimap** — Each heading is shown as a small horizontal bar on the right edge of the note viewer; bar length reflects the heading level (H1 longest)
+- **Hover to Expand** — Move the mouse over the bars and they expand into a full table of contents overlay, indented by level, with long titles ellipsized
+- **Click to Jump** — Click any entry to smooth-scroll to that heading
+- **Reading Position** — The section currently in view is highlighted automatically
+- **Live Rebuild** — Rebuilds itself when you switch notes or edit content (listens to `joplin-noteDidUpdate` with a MutationObserver fallback)
+- **Theme Aware** — Follows light and dark themes automatically (colors derive from `currentColor`)
+- **Unobtrusive** — Hidden for notes with fewer than 2 headings, hidden when printing/exporting, never steals focus or keyboard input
+
+## Install
+
+### From the Joplin plugin repository (once published)
+
+1. In Joplin, go to **Tools → Options → Plugins**
+2. Search for **Joplin Minimap**
+3. Install and restart Joplin
+
+### From file
+
+1. Download `plugin.jpl` from the [latest release](https://github.com/lim0513/joplin-minimap/releases/latest)
+2. In Joplin, go to **Tools → Options → Plugins**
+3. Click the gear icon and select **Install from file**
+4. Choose the downloaded `.jpl` file
+5. Restart Joplin
+
+## Usage
+
+Open any note with 2 or more headings in the **rendered Markdown viewer** (reading view, or the preview side of the split editor):
+
+- A column of tick bars appears at the right edge
+- **Hover** over it to expand the full table of contents
+- **Click** an entry to jump to that heading
+
+Note: the minimap only appears in the rendered viewer, not in the plain Markdown editor or the Rich Text editor.
+
+## How It Works
+
+A markdown-it content script injects two assets into the rendered viewer: `minimap-view.js` builds the minimap dynamically from the rendered `h1`–`h6` elements after each render, and `minimap.css` handles the collapsed/expanded styling. The Markdown rendering itself is untouched.
+
+## Settings
+
+Configurable in **Tools → Options → Joplin Minimap**:
+
+- **Minimum headings** — hide the minimap when the note has fewer headings than this (default 2)
+- **Expanded panel width (px)** — maximum width of the hover-expanded table of contents (default 240)
+- **Distance from right edge (px)** — gap between the minimap and the viewer's right edge (default 6)
+
+Changed settings apply on the next render (switch notes or edit the note).
+
+## Development
+
+Zero dependencies — no `npm install` needed:
+
+```bash
+npm run dist
+```
+
+This builds `dist/` (loadable via Joplin's **Development plugins** setting pointed at the project root) and `publish/` including `publish/plugin.jpl`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "joplin-plugin-minimap",
+  "version": "1.1.1",
+  "description": "A hover-to-expand table of contents minimap for the Joplin note viewer",
+  "author": "lim0513",
+  "homepage": "https://github.com/lim0513/joplin-minimap",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lim0513/joplin-minimap.git"
+  },
+  "scripts": {
+    "dist": "node build.js && node scripts/pack-jpl.js"
+  },
+  "keywords": ["joplin-plugin", "joplin", "toc", "outline", "minimap", "table-of-contents", "viewer"],
+  "license": "MIT",
+  "files": ["publish"]
+}

package/publish/index.js

@@ -0,0 +1,68 @@
+/* Joplin Minimap — plugin entry (runs in the plugin host, Node context).
+ * Registers the settings UI and a markdown-it content script whose only job
+ * is to inject the minimap assets (JS + CSS) into the rendered note viewer.
+ * The viewer asset fetches settings via webviewApi.postMessage -> onMessage.
+ */
+
+// SettingItemType numeric values: Int=1, String=2, Bool=3 (no 'api' import in plain JS)
+const TYPE_INT = 1;
+
+joplin.plugins.register({
+	onStart: async function () {
+		await joplin.settings.registerSection('minimap', {
+			label: 'Joplin Minimap',
+			iconName: 'fas fa-list',
+		});
+
+		try {
+			await joplin.settings.registerSettings({
+			'minimapMinHeadings': {
+				value: 2,
+				minimum: 1,
+				type: TYPE_INT,
+				section: 'minimap',
+				public: true,
+				label: 'Minimum headings',
+				description: 'Hide the minimap when the note has fewer headings than this. Default: 2.',
+			},
+			'minimapPanelWidth': {
+				value: 240,
+				minimum: 120,
+				type: TYPE_INT,
+				section: 'minimap',
+				public: true,
+				label: 'Expanded panel width (px)',
+				description: 'Maximum width of the hover-expanded table of contents. Default: 240.',
+			},
+			'minimapRightOffset': {
+				value: 6,
+				minimum: 0,
+				type: TYPE_INT,
+				section: 'minimap',
+				public: true,
+				label: 'Distance from right edge (px)',
+				description: 'Gap between the minimap and the right edge of the viewer. Default: 6.',
+			},
+			});
+		} catch (error) {
+			console.error('Joplin Minimap: registerSettings failed:', error);
+		}
+
+		await joplin.contentScripts.register(
+			'markdownItPlugin',
+			'joplin-minimap',
+			'./minimapContentScript.js'
+		);
+
+		await joplin.contentScripts.onMessage('joplin-minimap', async function (message) {
+			if (message === 'getSettings') {
+				return {
+					minHeadings: await joplin.settings.value('minimapMinHeadings'),
+					panelWidth: await joplin.settings.value('minimapPanelWidth'),
+					rightOffset: await joplin.settings.value('minimapRightOffset'),
+				};
+			}
+			return null;
+		});
+	},
+});

package/publish/manifest.json

@@ -0,0 +1,13 @@
+{
+	"manifest_version": 1,
+	"id": "com.github.joplin-minimap",
+	"app_min_version": "2.8",
+	"version": "1.1.1",
+	"name": "Joplin Minimap",
+	"description": "A hover-to-expand table of contents minimap for the note viewer. Shows heading tick marks on the right edge; hover to expand into a full ToC, click to jump.",
+	"author": "lim0513",
+	"homepage_url": "https://github.com/lim0513/joplin-minimap",
+	"repository_url": "https://github.com/lim0513/joplin-minimap",
+	"keywords": ["toc", "outline", "minimap", "table-of-contents"],
+	"categories": ["appearance", "viewer"]
+}

package/publish/minimap-view.js

@@ -0,0 +1,148 @@
+/* Joplin Minimap - runs inside the rendered note viewer.
+ * Collects h1-h6 from the rendered DOM, draws collapsed tick bars on the
+ * right edge, expands into a full ToC on hover, and jumps on click.
+ * Rebuilds itself whenever the note content changes (note switch, edit).
+ */
+(function () {
+	'use strict';
+
+	// Defaults; overridden from Joplin's plugin settings (Tools > Options > Minimap)
+	// when webviewApi is available in this webview.
+	var settings = { minHeadings: 2, panelWidth: 240, rightOffset: 6 };
+
+	function loadSettings() {
+		if (typeof webviewApi === 'undefined' || !webviewApi.postMessage) {
+			return Promise.resolve();
+		}
+		return webviewApi.postMessage('joplin-minimap', 'getSettings').then(function (s) {
+			if (s && typeof s.minHeadings === 'number') settings = s;
+		}).catch(function () { /* keep defaults (e.g. print/export context) */ });
+	}
+
+	// Only ever install one instance of the watcher per webview session.
+	if (window.__jpMinimapInstalled) return;
+	window.__jpMinimapInstalled = true;
+
+	var cleanup = null; // removes listeners belonging to the current build
+
+	function build() {
+		if (cleanup) { cleanup(); cleanup = null; }
+
+		var old = document.getElementById('jp-minimap');
+		if (old) old.remove();
+
+		var root = document.getElementById('rendered-md') || document.body;
+		var headings = Array.prototype.slice.call(
+			root.querySelectorAll('h1, h2, h3, h4, h5, h6')
+		);
+		if (headings.length < settings.minHeadings) return;
+
+		var nav = document.createElement('nav');
+		nav.id = 'jp-minimap';
+		nav.style.right = settings.rightOffset + 'px';
+		nav.style.setProperty('--jp-mm-width', settings.panelWidth + 'px');
+		// The viewer DOM can be editable in some contexts; make sure the
+		// minimap never shows a caret or accepts keyboard input.
+		nav.setAttribute('contenteditable', 'false');
+		nav.addEventListener('mousedown', function (e) { e.preventDefault(); });
+		// Own the wheel entirely while the cursor is over the minimap:
+		// scroll the ToC list ourselves and never let the event chain
+		// through to the note underneath (scroll chaining feels erratic).
+		nav.addEventListener('wheel', function (e) {
+			e.preventDefault();
+			list.scrollTop += e.deltaY;
+		}, { passive: false });
+
+		var list = document.createElement('div');
+		list.className = 'jp-mm-list';
+
+		var items = headings.map(function (h) {
+			var level = Number(h.tagName.charAt(1));
+
+			// NOT an <a>: Joplin's viewer shows a "Ctrl+click to open" tooltip
+			// on anchors and treats them as external links.
+			var item = document.createElement('div');
+			item.className = 'jp-mm-item jp-mm-l' + level;
+
+			var bar = document.createElement('span');
+			bar.className = 'jp-mm-bar';
+
+			var label = document.createElement('span');
+			label.className = 'jp-mm-label';
+			label.textContent = (h.textContent || '').trim();
+
+			item.appendChild(bar);
+			item.appendChild(label);
+
+			item.addEventListener('click', function () {
+				h.scrollIntoView({ behavior: 'smooth', block: 'start' });
+			});
+
+			list.appendChild(item);
+			return item;
+		});
+
+		nav.appendChild(list);
+		document.body.appendChild(nav);
+
+		function updateActive() {
+			var activeIndex = 0;
+			for (var i = 0; i < headings.length; i++) {
+				if (headings[i].getBoundingClientRect().top <= 90) activeIndex = i;
+			}
+			for (var j = 0; j < items.length; j++) {
+				items[j].classList.toggle('jp-mm-active', j === activeIndex);
+			}
+		}
+
+		document.addEventListener('scroll', updateActive, { passive: true, capture: true });
+		updateActive();
+
+		cleanup = function () {
+			document.removeEventListener('scroll', updateActive, { capture: true });
+		};
+	}
+
+	function settingsAndBuild() {
+		loadSettings().then(build);
+	}
+
+	var timer = null;
+	function scheduleBuild() {
+		clearTimeout(timer);
+		timer = setTimeout(settingsAndBuild, 150);
+	}
+
+	// True if a mutation was caused by the minimap itself (avoid rebuild loops).
+	function isOwnMutation(m) {
+		if (m.target && m.target.closest && m.target.closest('#jp-minimap')) return true;
+		var nodes = Array.prototype.slice.call(m.addedNodes)
+			.concat(Array.prototype.slice.call(m.removedNodes));
+		if (!nodes.length) return false;
+		return nodes.every(function (n) {
+			return n.id === 'jp-minimap' || (n.closest && n.closest('#jp-minimap'));
+		});
+	}
+
+	function watch() {
+		// Joplin fires this after each note render/update.
+		document.addEventListener('joplin-noteDidUpdate', scheduleBuild);
+
+		// Fallback: watch for the rendered content being swapped out
+		// (note switch replaces the DOM without re-running this script).
+		var mo = new MutationObserver(function (mutations) {
+			for (var i = 0; i < mutations.length; i++) {
+				if (!isOwnMutation(mutations[i])) { scheduleBuild(); return; }
+			}
+		});
+		mo.observe(document.body, { childList: true, subtree: true });
+
+		settingsAndBuild();
+	}
+
+	if (document.readyState === 'loading') {
+		document.addEventListener('DOMContentLoaded', watch);
+	} else {
+		watch();
+	}
+})();

package/publish/minimap.css

@@ -0,0 +1,116 @@
+/* Joplin Minimap — collapsed tick bars, hover-expanded ToC panel.
+ * Colors use currentColor / rgba so it follows both light and dark themes.
+ */
+
+#jp-minimap {
+	user-select: none;
+	-webkit-user-select: none;
+	caret-color: transparent;
+	cursor: default;
+	position: fixed;
+	top: 50%;
+	right: 6px;
+	transform: translateY(-50%);
+	z-index: 9999;
+	font-size: 12.5px;
+	line-height: 1.35;
+	color: inherit;
+}
+
+.jp-mm-list {
+	display: flex;
+	flex-direction: column;
+	align-items: flex-end;
+	padding: 8px 6px;
+	max-height: 84vh;
+	overflow: hidden;
+	border-radius: 10px;
+	transition: background 0.15s ease, box-shadow 0.15s ease;
+}
+
+.jp-mm-item {
+	display: flex;
+	align-items: center;
+	justify-content: flex-end;
+	padding: 3px 4px;
+	border-radius: 6px;
+	text-decoration: none;
+	color: inherit;
+	opacity: 0.5;
+	cursor: pointer;
+	outline: none;
+}
+
+/* ---- collapsed state: tick bars, width by heading level ---- */
+
+.jp-mm-bar {
+	display: block;
+	height: 2px;
+	border-radius: 1px;
+	background: currentColor;
+}
+
+.jp-mm-l1 .jp-mm-bar { width: 18px; }
+.jp-mm-l2 .jp-mm-bar { width: 13px; }
+.jp-mm-l3 .jp-mm-bar { width: 9px; }
+.jp-mm-l4 .jp-mm-bar { width: 7px; }
+.jp-mm-l5 .jp-mm-bar { width: 5px; }
+.jp-mm-l6 .jp-mm-bar { width: 5px; }
+
+.jp-mm-label { display: none; }
+
+/* ---- expanded state (hover) ---- */
+
+#jp-minimap:hover .jp-mm-list {
+	align-items: stretch;
+	overflow-y: auto;
+	overscroll-behavior: contain;
+	background: rgba(127, 127, 127, 0.16);
+	backdrop-filter: blur(10px);
+	-webkit-backdrop-filter: blur(10px);
+	box-shadow: 0 6px 28px rgba(0, 0, 0, 0.28);
+}
+
+#jp-minimap:hover .jp-mm-bar { display: none; }
+
+#jp-minimap:hover .jp-mm-item { justify-content: flex-start; }
+
+#jp-minimap:hover .jp-mm-label {
+	display: block;
+	max-width: var(--jp-mm-width, 240px);
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+/* indent by heading level when expanded */
+#jp-minimap:hover .jp-mm-l2 { padding-left: 16px; }
+#jp-minimap:hover .jp-mm-l3 { padding-left: 28px; }
+#jp-minimap:hover .jp-mm-l4 { padding-left: 40px; }
+#jp-minimap:hover .jp-mm-l5 { padding-left: 52px; }
+#jp-minimap:hover .jp-mm-l6 { padding-left: 52px; }
+
+/* ---- shared states ---- */
+
+.jp-mm-item:hover {
+	opacity: 1;
+	background: rgba(127, 127, 127, 0.22);
+}
+
+.jp-mm-active { opacity: 1; }
+
+#jp-minimap:hover .jp-mm-active {
+	background: rgba(127, 127, 127, 0.18);
+}
+
+/* slim scrollbar in the expanded panel */
+.jp-mm-list::-webkit-scrollbar { width: 4px; }
+.jp-mm-list::-webkit-scrollbar-thumb {
+	background: rgba(127, 127, 127, 0.4);
+	border-radius: 2px;
+}
+
+/* don't show over printed/exported output */
+@media print {
+	#jp-minimap { display: none; }
+}

package/publish/minimapContentScript.js

@@ -0,0 +1,20 @@
+/* Content script: no markdown transformation needed.
+ * We only ship two assets into the rendered viewer:
+ *   - minimap-view.js  builds the minimap from the rendered DOM
+ *   - minimap.css      collapsed tick bars + hover-expanded ToC panel
+ */
+module.exports = {
+	default: function (_context) {
+		return {
+			plugin: function (_markdownIt, _options) {
+				// intentionally empty — rendering is untouched
+			},
+			assets: function () {
+				return [
+					{ name: 'minimap.css' },
+					{ name: 'minimap-view.js' },
+				];
+			},
+		};
+	},
+};