From 3f2a2d94e1850499c98363062afe5eac99ae454e Mon Sep 17 00:00:00 2001
From: "Robert (GaimsDevSoftware)"
<285959242+GaimsDevSoftware@users.noreply.github.com>
Date: Sun, 21 Jun 2026 18:03:38 +0200
Subject: [PATCH 1/5] SEO/discoverability pass: meta, structured data, sitemap;
humanise copy
Make the project easier to find in web and AI search without reading as
machine-generated.
- docs: add canonical, Open Graph, Twitter and robots meta to all pages;
JSON-LD (SoftwareApplication + FAQ) on the landing page; robots.txt and
sitemap.xml.
- Rewrite landing-page and README copy in the project's own plain voice;
replace long dashes with ordinary punctuation throughout.
- Drop the emoji icon badges from the feature grid (and the unused CSS) so
both grids match; remove the decorative emoji from the Snippet guide button.
- Fix stale install/Wayland text on the site to match the README.
---
README.md | 19 ++++-
docs/assets/style.css | 12 ---
docs/develop.html | 20 ++++-
docs/index.html | 126 ++++++++++++++++++++++++------
docs/plugins.html | 20 ++++-
docs/robots.txt | 28 +++++++
docs/sitemap.xml | 18 +++++
plugins_repo/clipboard_history.py | 4 +-
8 files changed, 206 insertions(+), 41 deletions(-)
create mode 100644 docs/robots.txt
create mode 100644 docs/sitemap.xml
diff --git a/README.md b/README.md
index d8a9257..c284149 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# LinuxPop
-> Like PopClip on the Mac, but for Linux.
+> Like PopClip on the Mac, but for Linux. Highlight text, get a popup of actions. Works on X11 and KDE Plasma 6 Wayland.
@@ -169,6 +169,23 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full plugin API.
---
+## FAQ
+
+**Is there a PopClip for Linux?**
+That's pretty much what LinuxPop is. Highlight some text and a popup of actions shows up over it. It's free, MIT-licensed, and runs on X11 and KDE Plasma 6 Wayland.
+
+**Does it work on Wayland?**
+On KDE Plasma 6, yes: selection goes through `wl-clipboard`, the popup is placed with `gtk-layer-shell`, and the cursor position comes from KWin's scripting API. Other Wayland compositors fall back to the X11 path under XWayland.
+
+**Which desktops are supported?**
+Cinnamon, GNOME-on-X11, KDE, XFCE and MATE on X11, plus KDE Plasma 6 on Wayland.
+
+**Does it send my text anywhere?**
+No, not unless a plugin clearly does (the "Send to Claude" button being the obvious one). Otherwise everything stays on your machine. No telemetry, no accounts.
+
+**How do I uninstall it?**
+`bash ~/linuxpop/install.sh --uninstall` for a source install, or remove the Flatpak or native package the usual way.
+
## License
MIT. See [LICENSE](LICENSE).
diff --git a/docs/assets/style.css b/docs/assets/style.css
index cc5c178..2699f27 100644
--- a/docs/assets/style.css
+++ b/docs/assets/style.css
@@ -251,18 +251,6 @@ section.tight { padding: 32px 0; }
transform: translateY(-2px);
border-color: var(--border-strong);
}
-.feature-icon {
- width: 36px;
- height: 36px;
- border-radius: 9px;
- background: var(--gradient);
- display: inline-flex;
- align-items: center;
- justify-content: center;
- margin-bottom: 14px;
- color: white;
- font-size: 18px;
-}
.feature h3 { margin-top: 0; font-size: 1.1rem; }
.feature p { color: var(--text-dim); margin: 0; font-size: 0.94rem; }
diff --git a/docs/develop.html b/docs/develop.html
index 3e88c5b..bbadf61 100644
--- a/docs/develop.html
+++ b/docs/develop.html
@@ -3,10 +3,26 @@
- Build your own plugin - LinuxPop
-
+ Build your own LinuxPop plugin: no-code wizard & Python API
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/index.html b/docs/index.html
index 51816f6..13ace4a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -3,10 +3,91 @@
- LinuxPop - PopClip-inspired text actions for Linux
-
+ LinuxPop: PopClip for Linux (X11 & KDE Plasma Wayland)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -28,9 +109,9 @@
Text actions for Linux, without leaving where you are.
- Highlight anything. A small popup appears with context-aware actions -
- open URLs, run commands, ask an AI, transform text. Inspired by PopClip
- on macOS, built native for X11.
+ Highlight anything. A small popup appears with actions that fit what you
+ grabbed: open URLs, run commands, ask an AI, transform text. It's the
+ PopClip idea from macOS, done for Linux. Works on X11 and KDE Plasma 6 Wayland.
git clone https://github.com/GaimsDevSoftware/linuxpop.git ~/linuxpop
cd ~/linuxpop
bash install.sh
python3 ~/linuxpop/main.py # start now without logging out
-
3. Use it
+
Use it
Highlight any text on screen → popup appears with actions
Press Super+Shift+Y → popup on current selection at cursor
diff --git a/docs/plugins.html b/docs/plugins.html
index 669ff16..1920aac 100644
--- a/docs/plugins.html
+++ b/docs/plugins.html
@@ -3,10 +3,26 @@
- Plugin Store - LinuxPop
-
+ Plugin Store: LinuxPop plugins for Linux text actions
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/robots.txt b/docs/robots.txt
new file mode 100644
index 0000000..e2aa3ed
--- /dev/null
+++ b/docs/robots.txt
@@ -0,0 +1,28 @@
+# LinuxPop - https://gaimsdevsoftware.github.io/linuxpop/
+# All crawlers welcome, including AI answer engines.
+User-agent: *
+Allow: /
+
+# Explicitly welcome AI / answer-engine crawlers (GEO/AEO)
+User-agent: GPTBot
+Allow: /
+User-agent: OAI-SearchBot
+Allow: /
+User-agent: ChatGPT-User
+Allow: /
+User-agent: ClaudeBot
+Allow: /
+User-agent: Claude-Web
+Allow: /
+User-agent: anthropic-ai
+Allow: /
+User-agent: PerplexityBot
+Allow: /
+User-agent: Google-Extended
+Allow: /
+User-agent: Applebot-Extended
+Allow: /
+User-agent: CCBot
+Allow: /
+
+Sitemap: https://gaimsdevsoftware.github.io/linuxpop/sitemap.xml
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
new file mode 100644
index 0000000..9fd5fcf
--- /dev/null
+++ b/docs/sitemap.xml
@@ -0,0 +1,18 @@
+
+
+
+ https://gaimsdevsoftware.github.io/linuxpop/
+ weekly
+ 1.0
+
+
+ https://gaimsdevsoftware.github.io/linuxpop/plugins.html
+ weekly
+ 0.8
+
+
+ https://gaimsdevsoftware.github.io/linuxpop/develop.html
+ monthly
+ 0.6
+
+
diff --git a/plugins_repo/clipboard_history.py b/plugins_repo/clipboard_history.py
index cb60b13..f466c3c 100644
--- a/plugins_repo/clipboard_history.py
+++ b/plugins_repo/clipboard_history.py
@@ -2814,7 +2814,7 @@ def _ask_edit_snippet_meta(
orientation=Gtk.Orientation.HORIZONTAL, margin_top=10)
spacer = Gtk.Label()
guide_row.pack_start(spacer, True, True, 0)
- guide_btn = Gtk.Button(label="📖 Snippet guide")
+ guide_btn = Gtk.Button(label="Snippet guide")
guide_btn.connect(
"clicked", lambda _b: self._show_snippet_help_dialog(parent=dlg))
guide_row.pack_start(guide_btn, False, False, 0)
@@ -2995,7 +2995,7 @@ def _ask_new_snippet(self) -> Optional[Tuple[str, str, str, str]]:
"Click to insert a placeholder (filled in at paste time):"
)
help_row.pack_start(help_intro, True, True, 0)
- help_btn = Gtk.Button(label="📖 Snippet guide")
+ help_btn = Gtk.Button(label="Snippet guide")
help_btn.set_tooltip_text(
"Open a friendly walkthrough of snippets, triggers, and placeholders."
)
From 93a7ec473c75b4f41a20c9770d8ddd7a571585b0 Mon Sep 17 00:00:00 2001
From: "Robert (GaimsDevSoftware)"
<285959242+GaimsDevSoftware@users.noreply.github.com>
Date: Sun, 21 Jun 2026 23:04:45 +0200
Subject: [PATCH 2/5] Add regression tests pinning the min-selection-length
boundary
The "skip short selections" knob must only gate the auto-popup-on-selection
path. The empty-field double-click and hotkey paths show the edit menu
directly and must stay unaffected.
These tests exercise the App methods against a stub self (no X11/GTK loop):
- empty-field double-click still pops the edit menu with an aggressive
minimum-character setup;
- _show_no_selection_popup never consults the filter (but still honours the
blocklist, for contrast);
- the watcher path does filter short selections, and shows them when the
knob is off.
---
test_min_selection_filter.py | 187 +++++++++++++++++++++++++++++++++++
1 file changed, 187 insertions(+)
create mode 100644 test_min_selection_filter.py
diff --git a/test_min_selection_filter.py b/test_min_selection_filter.py
new file mode 100644
index 0000000..a93ae79
--- /dev/null
+++ b/test_min_selection_filter.py
@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Regression tests for the minimum-selection-length filter boundary.
+
+The "skip short selections" knob (min_selection_length_enabled +
+min_selection_length) must only ever gate the *auto-popup on selection*
+path. The two double-click-in-empty-field and hotkey paths show the
+edit menu directly and must NOT be affected by it.
+
+These tests pin that boundary so a future refactor can't quietly leak
+the filter into the no-selection popup path.
+
+They exercise the App methods in isolation against a stub `self`, so no
+X11/GTK main loop or real backend is needed.
+"""
+import sys
+import types
+
+import pytest
+
+# The app imports GTK via gobject-introspection; skip cleanly where that
+# (or a display) isn't available, same as the other GUI-touching test.
+pytest.importorskip("gi")
+sys.argv = ["test"]
+try:
+ import main
+except Exception as exc: # pragma: no cover - environment without GTK/display
+ pytest.skip(f"cannot import main ({exc})", allow_module_level=True)
+
+
+class FakeSettings:
+ """Minimal stand-in for the settings singleton."""
+
+ def __init__(self, **values):
+ self._values = values
+
+ def get(self, key, default=None):
+ return self._values.get(key, default)
+
+
+# Settings that would suppress every short selection on the watcher path.
+AGGRESSIVE_MIN = dict(
+ min_selection_length_enabled=True,
+ min_selection_length=100,
+ blocklist_patterns=[],
+ clipboard_history_enabled=True,
+ selection_debounce_ms=0,
+)
+
+
+def _double_click_stub():
+ return types.SimpleNamespace(
+ _show_no_selection_popup=_Recorder(),
+ )
+
+
+class _Recorder:
+ """Callable that records the calls made to it."""
+
+ def __init__(self):
+ self.calls = []
+
+ def __call__(self, *args, **kwargs):
+ self.calls.append((args, kwargs))
+
+
+# --- the actual regression: empty-field double-click ignores the filter ----
+
+def test_double_click_empty_field_fires_despite_min_length(monkeypatch):
+ """ctrl+double-click in an editable empty field must still pop the edit
+ menu even with an aggressive minimum-character setup."""
+ monkeypatch.setattr(main, "is_focus_editable", lambda *a, **k: True)
+ stub = _double_click_stub()
+
+ main.App._on_global_double_click(stub, 11, 22)
+
+ assert stub._show_no_selection_popup.calls == [((11, 22), {})], \
+ "empty-field double-click must open the no-selection popup"
+
+
+def test_double_click_non_editable_does_nothing(monkeypatch):
+ """The only gate on the double-click path is 'is the focus editable',
+ never the minimum-length setting."""
+ monkeypatch.setattr(main, "is_focus_editable", lambda *a, **k: False)
+ stub = _double_click_stub()
+
+ main.App._on_global_double_click(stub, 11, 22)
+
+ assert stub._show_no_selection_popup.calls == []
+
+
+def test_no_selection_popup_builds_menu_with_min_length_on(monkeypatch):
+ """_show_no_selection_popup never consults the min-length filter: it
+ shows the edit menu whenever the active window isn't blocklisted."""
+ monkeypatch.setattr(main, "_active_window_blocked", lambda patterns: False)
+ popup = types.SimpleNamespace(show_actions=_Recorder())
+ stub = types.SimpleNamespace(
+ settings=FakeSettings(**AGGRESSIVE_MIN),
+ popup=popup,
+ _on_clipboard_hotkey=lambda *a, **k: None,
+ )
+
+ main.App._show_no_selection_popup(stub, 5, 6)
+
+ assert len(popup.show_actions.calls) == 1, "the edit menu must be shown"
+ (items, x, y), _ = popup.show_actions.calls[0]
+ assert (x, y) == (5, 6)
+ assert items, "the edit menu must contain at least one action"
+
+
+def test_no_selection_popup_still_respects_blocklist(monkeypatch):
+ """Contrast: the blocklist IS allowed to suppress the popup. This keeps
+ the test honest about what does and doesn't gate this path."""
+ monkeypatch.setattr(main, "_active_window_blocked", lambda patterns: True)
+ popup = types.SimpleNamespace(show_actions=_Recorder())
+ stub = types.SimpleNamespace(
+ settings=FakeSettings(**AGGRESSIVE_MIN),
+ popup=popup,
+ )
+
+ main.App._show_no_selection_popup(stub, 5, 6)
+
+ assert popup.show_actions.calls == []
+
+
+# --- the other side of the boundary: the watcher path DOES filter ----------
+
+def _capture_watcher_callback(monkeypatch, stub):
+ """Run _start_watcher against a fake backend and return the on_selection
+ callback it registered."""
+ captured = {}
+
+ class FakeWatcher:
+ def __init__(self, cb):
+ captured["cb"] = cb
+
+ def start(self):
+ pass
+
+ def stop(self):
+ pass
+
+ fake_backend = types.SimpleNamespace(
+ make_selection_watcher=lambda cb, debounce: FakeWatcher(cb),
+ )
+ monkeypatch.setattr(main, "get_backend", lambda: fake_backend)
+ main.App._start_watcher(stub)
+ return captured["cb"]
+
+
+def test_watcher_path_filters_short_selection(monkeypatch):
+ scheduled = []
+ monkeypatch.setattr(main.GLib, "idle_add", lambda *a, **k: scheduled.append(a))
+ stub = types.SimpleNamespace(
+ watcher=None,
+ _watcher_active=False,
+ min_len=100,
+ settings=FakeSettings(**AGGRESSIVE_MIN),
+ _show_for_text=lambda *a, **k: None,
+ )
+
+ on_selection = _capture_watcher_callback(monkeypatch, stub)
+ on_selection("ab", 1, 2) # 2 chars < 100, filter enabled
+
+ assert scheduled == [], "short selection must be filtered on the watcher path"
+
+
+def test_watcher_path_shows_when_filter_disabled(monkeypatch):
+ scheduled = []
+ monkeypatch.setattr(main.GLib, "idle_add", lambda *a, **k: scheduled.append(a))
+ settings = dict(AGGRESSIVE_MIN)
+ settings["min_selection_length_enabled"] = False
+ stub = types.SimpleNamespace(
+ watcher=None,
+ _watcher_active=False,
+ min_len=100,
+ settings=FakeSettings(**settings),
+ _show_for_text=lambda *a, **k: None,
+ )
+
+ on_selection = _capture_watcher_callback(monkeypatch, stub)
+ on_selection("ab", 1, 2)
+
+ assert len(scheduled) == 1, "with the filter off, the popup must be scheduled"
+
+
+if __name__ == "__main__":
+ sys.exit(pytest.main([__file__, "-v"]))
From d38ba921dc1a36ba32a6e60d3b566fad71a6b44b Mon Sep 17 00:00:00 2001
From: "Robert (GaimsDevSoftware)"
<285959242+GaimsDevSoftware@users.noreply.github.com>
Date: Mon, 22 Jun 2026 04:34:32 +0200
Subject: [PATCH 3/5] Add markdown/formatting icon sets and category grouping
in the popup
Replace the borrowed freedesktop format-text-* theme icons (visually foreign,
sometimes missing under KDE themes / in the Flatpak sandbox) with a cohesive
house-style set, and let related actions collapse behind a category chip.
Icons (icons/linuxpop-{format,md}-*, glyph + colour):
- linuxpop-format-{bold,italic,underline}: plain serif letterforms for the
rich-text Formatting plugin (Ctrl+B/I/U).
- linuxpop-md-{bold,italic,strikethrough,highlight,quote,code,link}: the same
base glyphs carrying a red ".md" earmark so markdown actions never look like
the rich-text ones.
- Category chips linuxpop-format ("A" + teal bar) and linuxpop-md (.md
document), each with its own signature colour, legible down to 16px.
Category grouping:
- Plugin.category field; plugin_loader.CATEGORIES + a pure, tested plan_grouped()
that collapses a category into one chip once it has >= popup_category_min
members (else inline).
- popup.py renders category chips that reveal their members on row 2 on click
(reusing the existing expand-reveal idiom) and collapse on a second click.
- New opt-in catalogue plugin plugins_repo/markdown.py: 7 wrap actions
(**, *, ~~, ==, >, `, []()) via actions.replace_selection.
- Setting popup_group_categories (default on) with a Settings toggle; bold/
italic/underline tagged category="format".
Design assets and generators under docs/design/ (philosophy, specimen, mock).
---
docs/design/_gen_grouped_mock.py | 87 ++++++++
docs/design/_gen_markdown_icons.py | 205 +++++++++++++++++++
docs/design/_gen_specimen.py | 119 +++++++++++
docs/design/category-grouping-mock.png | Bin 0 -> 124949 bytes
docs/design/markdown-icons-philosophy.md | 46 +++++
docs/design/markdown-icons-specimen.png | Bin 0 -> 262726 bytes
icons/linuxpop-format-bold-symbolic.svg | 1 +
icons/linuxpop-format-bold.svg | 1 +
icons/linuxpop-format-italic-symbolic.svg | 1 +
icons/linuxpop-format-italic.svg | 1 +
icons/linuxpop-format-symbolic.svg | 1 +
icons/linuxpop-format-underline-symbolic.svg | 1 +
icons/linuxpop-format-underline.svg | 1 +
icons/linuxpop-format.svg | 1 +
icons/linuxpop-md-bold-symbolic.svg | 1 +
icons/linuxpop-md-bold.svg | 1 +
icons/linuxpop-md-code-symbolic.svg | 1 +
icons/linuxpop-md-code.svg | 1 +
icons/linuxpop-md-highlight-symbolic.svg | 1 +
icons/linuxpop-md-highlight.svg | 1 +
icons/linuxpop-md-italic-symbolic.svg | 1 +
icons/linuxpop-md-italic.svg | 1 +
icons/linuxpop-md-link-symbolic.svg | 1 +
icons/linuxpop-md-link.svg | 1 +
icons/linuxpop-md-quote-symbolic.svg | 1 +
icons/linuxpop-md-quote.svg | 1 +
icons/linuxpop-md-strikethrough-symbolic.svg | 1 +
icons/linuxpop-md-strikethrough.svg | 1 +
icons/linuxpop-md-symbolic.svg | 1 +
icons/linuxpop-md.svg | 1 +
plugin_base.py | 5 +
plugin_loader.py | 54 +++++
plugins_repo/formatting.py | 16 +-
plugins_repo/markdown.py | 57 ++++++
popup.py | 93 ++++++++-
settings.py | 9 +
settings_gui.py | 17 ++
37 files changed, 727 insertions(+), 5 deletions(-)
create mode 100644 docs/design/_gen_grouped_mock.py
create mode 100644 docs/design/_gen_markdown_icons.py
create mode 100644 docs/design/_gen_specimen.py
create mode 100644 docs/design/category-grouping-mock.png
create mode 100644 docs/design/markdown-icons-philosophy.md
create mode 100644 docs/design/markdown-icons-specimen.png
create mode 100644 icons/linuxpop-format-bold-symbolic.svg
create mode 100644 icons/linuxpop-format-bold.svg
create mode 100644 icons/linuxpop-format-italic-symbolic.svg
create mode 100644 icons/linuxpop-format-italic.svg
create mode 100644 icons/linuxpop-format-symbolic.svg
create mode 100644 icons/linuxpop-format-underline-symbolic.svg
create mode 100644 icons/linuxpop-format-underline.svg
create mode 100644 icons/linuxpop-format.svg
create mode 100644 icons/linuxpop-md-bold-symbolic.svg
create mode 100644 icons/linuxpop-md-bold.svg
create mode 100644 icons/linuxpop-md-code-symbolic.svg
create mode 100644 icons/linuxpop-md-code.svg
create mode 100644 icons/linuxpop-md-highlight-symbolic.svg
create mode 100644 icons/linuxpop-md-highlight.svg
create mode 100644 icons/linuxpop-md-italic-symbolic.svg
create mode 100644 icons/linuxpop-md-italic.svg
create mode 100644 icons/linuxpop-md-link-symbolic.svg
create mode 100644 icons/linuxpop-md-link.svg
create mode 100644 icons/linuxpop-md-quote-symbolic.svg
create mode 100644 icons/linuxpop-md-quote.svg
create mode 100644 icons/linuxpop-md-strikethrough-symbolic.svg
create mode 100644 icons/linuxpop-md-strikethrough.svg
create mode 100644 icons/linuxpop-md-symbolic.svg
create mode 100644 icons/linuxpop-md.svg
create mode 100644 plugins_repo/markdown.py
diff --git a/docs/design/_gen_grouped_mock.py b/docs/design/_gen_grouped_mock.py
new file mode 100644
index 0000000..a631d61
--- /dev/null
+++ b/docs/design/_gen_grouped_mock.py
@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Mock of the category-grouped popup (collapsed vs expanded), built from the
+real symbolic icon files so it reflects what ships."""
+import os
+import cairosvg
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ICONS = os.path.normpath(os.path.join(HERE, "..", "..", "icons"))
+
+
+def icon_inner(name):
+ svg = open(os.path.join(ICONS, name + ".svg")).read()
+ return svg[svg.index(">", svg.index("")]
+
+
+def place(name, x, y, s=34):
+ return f'{icon_inner(name)}'
+
+
+W, H = 1180, 720
+BG, PANEL, RULE = "#0E1016", "#161922", "#262B38"
+INK, DIM, ACC = "#E8EAF2", "#6B7184", "#8AA0FF"
+THIN = 'font-family="Helvetica Neue,Arial,sans-serif" font-weight="200"'
+REG = 'font-family="Helvetica Neue,Arial,sans-serif" font-weight="400"'
+
+p = [f'']
+p.append(f'Category grouping')
+p.append(f'FORMATTING & MARKDOWN COLLAPSE BEHIND A CHIP · CLICK TO EXPAND')
+p.append(f'')
+
+
+def pill(x, y, w, h):
+ return (f'')
+
+
+g = 44 # cell pitch
+
+# --- collapsed -----------------------------------------------------------
+p.append(f'COLLAPSED — what you see first')
+row = ["linuxpop-clipboard-symbolic", "linuxpop-format-symbolic", "linuxpop-md-symbolic", "linuxpop-dictionary-symbolic"]
+bx, by, bh = 80, 256, 64
+bw = g * len(row) + 24
+p.append(pill(bx, by, bw, bh))
+x = bx + 16
+for name in row:
+ p.append(place(name, x, by + 15))
+ x += g
+p.append(f'copy · ')
+p.append(f'Aâ–¾ Formatting')
+p.append(f'.mdâ–¾ Markdown')
+
+# --- expanded ------------------------------------------------------------
+p.append(f'EXPANDED — after clicking the Markdown chip')
+ex, ey = 80, 424
+row2 = ["linuxpop-md-bold-symbolic", "linuxpop-md-italic-symbolic", "linuxpop-md-strikethrough-symbolic",
+ "linuxpop-md-highlight-symbolic", "linuxpop-md-quote-symbolic", "linuxpop-md-code-symbolic",
+ "linuxpop-md-link-symbolic"]
+ew = max(g * len(row) + 24, g * len(row2) + 24)
+eh = 64 * 2 + 6
+p.append(f'')
+# row 1 (collapsed view, markdown chip now "active")
+x = ex + 16
+for name in row:
+ box = ''
+ if name == "linuxpop-md-symbolic":
+ box = f''
+ p.append(box + place(name, x, ey + 15))
+ x += g
+# divider
+p.append(f'')
+# row 2 (members)
+x = ex + 16
+for name in row2:
+ p.append(place(name, x, ey + 78))
+ x += g
+p.append(f'the 7 markdown')
+p.append(f'actions reveal on')
+p.append(f'the second row')
+
+p.append(f'')
+p.append(f'popup_group_categories · the red .md tag marks every markdown action')
+
+svg = f'"
+out = os.path.join(HERE, "category-grouping-mock.png")
+cairosvg.svg2png(bytestring=svg.encode(), write_to=out, output_width=W * 2, output_height=H * 2)
+print("wrote", out)
diff --git a/docs/design/_gen_markdown_icons.py b/docs/design/_gen_markdown_icons.py
new file mode 100644
index 0000000..e7dd182
--- /dev/null
+++ b/docs/design/_gen_markdown_icons.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Generate the LinuxPop text-formatting icon set.
+
+Two families, one house style (48x48, rounded indigo plate + hairline bezel
+for colour; bare #f0f0f0 glyph for symbolic):
+
+ linuxpop-format-* rich-text formatting (Ctrl+B/I/U). The styled letter.
+ linuxpop-md-* markdown wrapping (**, ==, > ...). Same base glyph PLUS
+ a small monospace corner badge of the literal syntax it
+ inserts, so the user can tell the two mechanisms apart.
+
+Renders a comparison specimen PNG via _gen_specimen.py separately.
+"""
+import glob
+import os
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ICONS = os.path.normpath(os.path.join(HERE, "..", "..", "icons"))
+
+# --- house style ----------------------------------------------------------
+TOP, BOT = "#6E8BF5", "#3F3AD0" # formatting family gradient (indigo)
+AMBER = "#FFD773" # the one sanctioned warm accent
+GLYPH_SYM = "#f0f0f0" # symbolic ink (white-on-dark popup)
+GLYPH_COL = "#ffffff" # ink on the colour plate
+
+COLOR_HEAD = (
+ '
