diff --git a/metadata.json b/metadata.json
new file mode 100644
index 0000000..18aee20
--- /dev/null
+++ b/metadata.json
@@ -0,0 +1,10 @@
+{
+	"author": "spleenftw",
+	"email": "",
+	"website": "https://github.com/spleenftw/bludit-toc",
+	"version": "1.0.0",
+	"releaseDate": "2026-06-04",
+	"license": "MIT",
+	"compatible": "3.22.0",
+	"notes": "Sticky Table of Contents sidebar (desktop) and floating drawer (mobile) built from the article's h2/h3/h4 headings."
+}
diff --git a/plugin.php b/plugin.php
new file mode 100644
index 0000000..4f9c794
--- /dev/null
+++ b/plugin.php
@@ -0,0 +1,93 @@
+<?php
+/**
+ * Bludit ToC Plugin
+ *
+ * Injects a sticky Table of Contents sidebar (desktop) + floating drawer
+ * (mobile) built from the article's h2/h3/h4 headings. Works standalone
+ * on any Bludit theme that wraps article body in a `.content` element.
+ *
+ * Drop this directory into bl-plugins/ and activate via the admin panel.
+ */
+class PluginBluditToc extends Plugin {
+
+    public function init() {
+        $this->dbFields = array(
+            // Label shown at the top of the sidebar and in the mobile drawer.
+            'title'        => 'On this page',
+            // Pixel offset to clear the fixed navbar when jumping to a heading.
+            'navbarHeight' => 80,
+            // Viewport width (px) at which the fixed sidebar appears.
+            // Below this width the mobile floating-button drawer is used instead.
+            'minWidth'     => 1280,
+        );
+    }
+
+    // ---- Admin settings form ----
+
+    public function form() {
+        global $L;
+
+        $title        = htmlspecialchars($this->getDbField('title'), ENT_QUOTES, 'UTF-8');
+        $navbarHeight = (int) $this->getDbField('navbarHeight');
+        $minWidth     = (int) $this->getDbField('minWidth');
+
+        $h  = '';
+
+        $h .= '<div class="form-group">';
+        $h .= '<label for="bltoc-field-title">' . $L->get('Sidebar title') . '</label>';
+        $h .= '<input class="form-control" type="text" id="bltoc-field-title" name="title" value="' . $title . '">';
+        $h .= '</div>';
+
+        $h .= '<div class="form-group">';
+        $h .= '<label for="bltoc-field-navbar">' . $L->get('Navbar height (px)') . '</label>';
+        $h .= '<input class="form-control" type="number" id="bltoc-field-navbar" name="navbarHeight" min="0" max="300" value="' . $navbarHeight . '">';
+        $h .= '<small class="form-text text-muted">' . $L->get('Used to offset hash-jump anchors so they clear the fixed navbar.') . '</small>';
+        $h .= '</div>';
+
+        $h .= '<div class="form-group">';
+        $h .= '<label for="bltoc-field-minwidth">' . $L->get('Fixed sidebar min-width (px)') . '</label>';
+        $h .= '<input class="form-control" type="number" id="bltoc-field-minwidth" name="minWidth" min="768" max="2560" value="' . $minWidth . '">';
+        $h .= '<small class="form-text text-muted">' . $L->get('Viewport widths below this value use the mobile floating button instead.') . '</small>';
+        $h .= '</div>';
+
+        return $h;
+    }
+
+    // ---- Front-end hooks ----
+
+    /**
+     * Inject the plugin CSS in <head>.
+     */
+    public function siteHead() {
+        $url = DOMAIN_PLUGINS . $this->directoryName . '/toc.css';
+        return HTML::style($url) . PHP_EOL;
+    }
+
+    /**
+     * Inject the ToC sidebar container right after <body>.
+     * It is position:fixed, so placement in the DOM doesn't affect layout.
+     * JS will populate <nav id="bltoc-nav"> and mark the container visible.
+     */
+    public function siteBodyBegin() {
+        $title = htmlspecialchars($this->getDbField('title'), ENT_QUOTES, 'UTF-8');
+        return '<aside class="bltoc-sidebar" id="bltoc-sidebar" aria-label="' . $title . '">'
+             . '<div class="bltoc-header"><span class="bltoc-title">' . $title . '</span></div>'
+             . '<nav id="bltoc-nav" aria-label="' . $title . '"></nav>'
+             . '</aside>' . PHP_EOL;
+    }
+
+    /**
+     * Inject config + script just before </body>.
+     * Config is passed via window.BLTOC so the JS file stays cache-friendly.
+     */
+    public function siteBodyEnd() {
+        $title        = json_encode($this->getDbField('title'));
+        $navbarHeight = (int) $this->getDbField('navbarHeight');
+        $minWidth     = (int) $this->getDbField('minWidth');
+        $url          = DOMAIN_PLUGINS . $this->directoryName . '/toc.js';
+
+        $out  = '<script>window.BLTOC={title:' . $title . ',navbarHeight:' . $navbarHeight . ',minWidth:' . $minWidth . '};</script>' . PHP_EOL;
+        $out .= HTML::script($url) . PHP_EOL;
+        return $out;
+    }
+}
diff --git a/toc.css b/toc.css
new file mode 100644
index 0000000..f46f53e
--- /dev/null
+++ b/toc.css
@@ -0,0 +1,223 @@
+/* =============================================================
+   Bludit ToC Plugin — toc.css
+   Self-contained: no dependency on the host theme's CSS variables.
+   Dark mode is handled via prefers-color-scheme.
+   If the theme exposes --accent / --text-muted / --bg-primary,
+   those are layered on top via @supports for a seamless integration.
+   ============================================================= */
+
+/* ---- Color tokens (light) ---- */
+#bltoc-sidebar {
+    --bltoc-text:       #777;
+    --bltoc-hover:      #111;
+    --bltoc-active:     #0066cc;
+    --bltoc-label:      #999;
+    --bltoc-bg:         #fff;
+    --bltoc-border:     rgba(0,0,0,0.08);
+    --bltoc-fab-bg:     #0066cc;
+    --bltoc-fab-color:  #fff;
+}
+
+/* ---- Color tokens (dark) ---- */
+@media (prefers-color-scheme: dark) {
+    #bltoc-sidebar {
+        --bltoc-text:   #999;
+        --bltoc-hover:  #eee;
+        --bltoc-active: #4d9fff;
+        --bltoc-label:  #666;
+        --bltoc-bg:     #1a1a1a;
+        --bltoc-border: rgba(255,255,255,0.08);
+    }
+}
+
+/* Let blowdit (or any theme) override via its own design tokens */
+@supports (color: var(--accent)) {
+    #bltoc-sidebar { --bltoc-active: var(--accent); }
+}
+@supports (color: var(--text-muted)) {
+    #bltoc-sidebar { --bltoc-text: var(--text-muted); }
+}
+@supports (color: var(--bg-primary)) {
+    #bltoc-sidebar { --bltoc-bg: var(--bg-primary); }
+}
+
+/* ============================================================
+   Desktop fixed sidebar
+   Visible only at min-width set by the admin (default 1280px).
+   JS adds .bltoc-ready when headings are found, making it appear.
+   ============================================================ */
+.bltoc-sidebar {
+    display: none; /* hidden until JS confirms headings exist */
+    position: fixed;
+    left: 1rem;
+    top: 5rem;   /* approx below a typical navbar; fine-tuned with navbarHeight in JS */
+    width: 210px;
+    max-height: calc(100vh - 6rem);
+    overflow-y: auto;
+    overflow-x: hidden;
+    z-index: 200;
+    font-size: 0.8125rem;
+    line-height: 1.5;
+    scrollbar-width: thin;
+    scrollbar-color: var(--bltoc-border) transparent;
+}
+
+/* JS adds data-bltoc-minwidth on <html>; sidebar shows only above that threshold. */
+/* Actual media-query breakpoint is injected by JS via a <style> tag since the
+   min-width value is dynamic (set in admin). */
+
+/* ---- Sidebar header ("On this page") ---- */
+.bltoc-header {
+    margin-bottom: 0.65rem;
+}
+
+.bltoc-title {
+    font-size: 0.68rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--bltoc-label);
+}
+
+/* ---- ToC list ---- */
+.bltoc-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+
+.bltoc-item {
+    padding: 0.12rem 0;
+}
+
+.bltoc-h3 { padding-left: 0.75rem; }
+.bltoc-h4 { padding-left: 1.5rem; }
+
+.bltoc-link {
+    display: block;
+    color: var(--bltoc-text);
+    text-decoration: none;
+    line-height: 1.5;
+    transition: color 0.15s ease;
+}
+
+.bltoc-link:hover {
+    color: var(--bltoc-hover);
+    text-decoration: none;
+}
+
+.bltoc-link.active {
+    color: var(--bltoc-active);
+    font-weight: 600;
+}
+
+/* ============================================================
+   Mobile floating action button + bottom drawer
+   FAB appears below the sidebar breakpoint.
+   Both are injected by JS, but their CSS lives here.
+   ============================================================ */
+.bltoc-fab {
+    display: none; /* shown by JS via flex when headings exist */
+    position: fixed;
+    left: 1.5rem;
+    bottom: 1.5rem;
+    z-index: 1500;
+    width: 46px;
+    height: 46px;
+    border-radius: 50%;
+    border: none;
+    background: var(--bltoc-fab-bg, #0066cc);
+    color: var(--bltoc-fab-color, #fff);
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    box-shadow: 0 3px 10px rgba(0,0,0,0.25);
+    transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.bltoc-fab:hover {
+    transform: scale(1.08);
+    box-shadow: 0 4px 14px rgba(0,0,0,0.3);
+}
+
+.bltoc-fab svg { display: block; }
+
+/* ---- Bottom drawer backdrop ---- */
+.bltoc-drawer {
+    position: fixed;
+    inset: 0;
+    z-index: 2000;
+    background: rgba(0, 0, 0, 0.45);
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 0.22s ease, visibility 0s linear 0.22s;
+}
+
+.bltoc-drawer.is-open {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity 0.22s ease;
+}
+
+/* ---- Drawer panel (slides up from bottom) ---- */
+.bltoc-drawer-panel {
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    background: #fff;
+    border-radius: 1rem 1rem 0 0;
+    padding: 1.5rem 1.5rem calc(1.5rem + env(safe-area-inset-bottom, 0px));
+    max-height: 72vh;
+    overflow-y: auto;
+    transform: translateY(100%);
+    transition: transform 0.25s ease;
+}
+
+@media (prefers-color-scheme: dark) {
+    .bltoc-drawer-panel { background: #1e1e1e; }
+}
+
+@supports (color: var(--bg-primary)) {
+    .bltoc-drawer-panel { background: var(--bg-primary); }
+}
+
+.bltoc-drawer.is-open .bltoc-drawer-panel {
+    transform: translateY(0);
+}
+
+.bltoc-drawer-title {
+    font-size: 0.68rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: #999;
+    margin-bottom: 0.75rem;
+}
+
+.bltoc-drawer .bltoc-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+
+.bltoc-drawer .bltoc-link {
+    display: block;
+    padding: 0.5rem 0;
+    color: #555;
+    text-decoration: none;
+}
+
+.bltoc-drawer .bltoc-link:hover {
+    color: #0066cc;
+    text-decoration: none;
+}
+
+@media (prefers-color-scheme: dark) {
+    .bltoc-drawer .bltoc-link       { color: #ccc; }
+    .bltoc-drawer .bltoc-link:hover { color: #4d9fff; }
+}
+
+@supports (color: var(--accent)) {
+    .bltoc-drawer .bltoc-link:hover { color: var(--accent); }
+}
diff --git a/toc.js b/toc.js
new file mode 100644
index 0000000..2415156
--- /dev/null
+++ b/toc.js
@@ -0,0 +1,175 @@
+/* Bludit ToC Plugin — toc.js
+   Reads config from window.BLTOC (injected inline by plugin.php).
+   No dependencies; works with any Bludit theme that wraps the article
+   body in a .content element (Bludit's default page template does this). */
+(function () {
+    'use strict';
+
+    var cfg = window.BLTOC || {};
+    var TITLE         = cfg.title        || 'On this page';
+    var NAVBAR_HEIGHT = cfg.navbarHeight != null ? cfg.navbarHeight : 80;
+    var MIN_WIDTH     = cfg.minWidth     != null ? cfg.minWidth     : 1280;
+
+    /* ---- Inject the dynamic min-width media query for the sidebar ---- */
+    var styleEl = document.createElement('style');
+    styleEl.textContent =
+        '@media (min-width: ' + MIN_WIDTH + 'px) { .bltoc-sidebar.bltoc-ready { display: block; } }' +
+        '@media (max-width: ' + (MIN_WIDTH - 1) + 'px) { .bltoc-fab.bltoc-ready { display: flex; } }';
+    document.head.appendChild(styleEl);
+
+    /* ---- Find the article content area ---- */
+    var content = document.querySelector('.content')
+               || document.querySelector('article .entry-content')
+               || document.querySelector('.entry-content')
+               || document.querySelector('.post-content')
+               || document.querySelector('article')
+               || document.querySelector('main');
+
+    if (!content) return;
+
+    /* ---- Collect headings ---- */
+    var headings = content.querySelectorAll('h2, h3, h4');
+    if (!headings.length) return;
+
+    /* ---- Assign stable IDs to any heading that lacks one ---- */
+    var usedIds = {};
+    Array.prototype.forEach.call(headings, function (h) {
+        if (h.id) {
+            usedIds[h.id] = true;
+        } else {
+            var base = h.textContent.trim().toLowerCase()
+                .replace(/[^a-z0-9\s-]/g, '')
+                .replace(/\s+/g, '-')
+                .replace(/^-+|-+$/g, '') || 'heading';
+            var id = base, n = 2;
+            while (usedIds[id]) { id = base + '-' + (n++); }
+            usedIds[id] = true;
+            h.id = id;
+        }
+        /* Offset anchor jumps so the heading clears the fixed navbar */
+        h.style.scrollMarginTop = NAVBAR_HEIGHT + 'px';
+    });
+
+    /* ---- Build the <ul> list ---- */
+    var ul = document.createElement('ul');
+    ul.className = 'bltoc-list';
+
+    Array.prototype.forEach.call(headings, function (h) {
+        var li = document.createElement('li');
+        li.className = 'bltoc-item bltoc-' + h.tagName.toLowerCase();
+
+        var a = document.createElement('a');
+        a.href = '#' + h.id;
+        a.textContent = h.textContent;
+        a.className = 'bltoc-link';
+
+        li.appendChild(a);
+        ul.appendChild(li);
+    });
+
+    /* ---- Populate #bltoc-nav and reveal the sidebar ---- */
+    var nav = document.getElementById('bltoc-nav');
+    if (nav) {
+        nav.appendChild(ul);
+    }
+
+    var sidebar = document.getElementById('bltoc-sidebar');
+    if (sidebar) {
+        sidebar.classList.add('bltoc-ready');
+    }
+
+    /* ---- Scroll-spy: highlight the last heading above the viewport fold ---- */
+    var headingArr = Array.prototype.slice.call(headings);
+
+    function updateActive() {
+        var scrollY    = window.scrollY || window.pageYOffset;
+        var threshold  = scrollY + NAVBAR_HEIGHT + 16; /* small extra gap */
+        var active     = null;
+
+        headingArr.forEach(function (h) {
+            if (h.getBoundingClientRect().top + scrollY <= threshold) {
+                active = h;
+            }
+        });
+
+        if (!nav) return;
+        var links = nav.querySelectorAll('.bltoc-link');
+        Array.prototype.forEach.call(links, function (a) {
+            a.classList.remove('active');
+        });
+        if (active) {
+            var link = nav.querySelector('a[href="#' + active.id + '"]');
+            if (link) link.classList.add('active');
+        }
+    }
+
+    window.addEventListener('scroll', updateActive, { passive: true });
+    updateActive();
+
+    /* ---- Mobile: floating button + bottom drawer ---- */
+    var fab = document.createElement('button');
+    fab.type = 'button';
+    fab.className = 'bltoc-fab bltoc-ready';
+    fab.setAttribute('aria-label', TITLE);
+    fab.innerHTML =
+        '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" ' +
+        'stroke="currentColor" stroke-width="2" stroke-linecap="round" ' +
+        'stroke-linejoin="round" aria-hidden="true">' +
+        '<path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"/>' +
+        '</svg>';
+
+    var drawer = document.createElement('div');
+    drawer.className = 'bltoc-drawer';
+    drawer.setAttribute('role', 'dialog');
+    drawer.setAttribute('aria-modal', 'true');
+    drawer.setAttribute('aria-label', TITLE);
+
+    var panel = document.createElement('div');
+    panel.className = 'bltoc-drawer-panel';
+
+    var drawerTitle = document.createElement('div');
+    drawerTitle.className = 'bltoc-drawer-title';
+    drawerTitle.textContent = TITLE;
+
+    var clone = ul.cloneNode(true);
+
+    panel.appendChild(drawerTitle);
+    panel.appendChild(clone);
+    drawer.appendChild(panel);
+
+    document.body.appendChild(fab);
+    document.body.appendChild(drawer);
+
+    function openDrawer() {
+        drawer.classList.add('is-open');
+        document.body.style.overflow = 'hidden';
+        fab.setAttribute('aria-expanded', 'true');
+    }
+
+    function closeDrawer() {
+        drawer.classList.remove('is-open');
+        document.body.style.overflow = '';
+        fab.setAttribute('aria-expanded', 'false');
+    }
+
+    fab.setAttribute('aria-expanded', 'false');
+    fab.addEventListener('click', openDrawer);
+
+    /* Close when clicking the backdrop */
+    drawer.addEventListener('click', function (e) {
+        if (e.target === drawer) closeDrawer();
+    });
+
+    /* Close when a drawer link is followed */
+    Array.prototype.forEach.call(clone.querySelectorAll('a'), function (a) {
+        a.addEventListener('click', closeDrawer);
+    });
+
+    /* Close on Escape */
+    document.addEventListener('keydown', function (e) {
+        if ((e.key === 'Escape' || e.key === 'Esc') && drawer.classList.contains('is-open')) {
+            closeDrawer();
+            fab.focus();
+        }
+    });
+})();