Sidepad
English version | Русская версия → README.ru.md
A Chrome side panel for managing task lists in Markdown format. Works as a native Side Panel — stays alongside the page without covering it.
Table of Contents
What is it
Sidepad is a Chrome extension that opens a side panel with a task list. The panel works alongside any browser tab without closing it. Tasks are stored locally in the browser and read/saved in Markdown (.md) format.
The default legacy mode requires no registration and sends task data only to files selected by the user. An experimental, off-by-default Notes API mode is available for development; it is described separately below. The extension has no dependencies and requires no build step.
Features
Tasks
- Add tasks with text, URL link, and section assignment
- Mark tasks as done (checkbox)
- Edit task text by clicking
- Delete user-created tasks
- Copy task text to clipboard with one button
- Move a task to another section with the
→ button (appears on hover)
- Completed tasks automatically move to the end of their section
Sections
- Group tasks into named sections
- Add new sections via a form
- Collapse/expand sections by clicking the header
- "▸ Collapse all / ▾ Expand" button to manage all sections at once
- Rename a section with the
✎ button (appears on hover over the header)
- Delete a section along with all its tasks
- Auto-collapse a section when all its tasks are completed
- Completed task counter in each section header
Tabs
- Work with multiple lists simultaneously in separate tabs
- Each imported file opens in a separate tab
- Rename a tab by double-clicking its name
- Hidden-tab indicator (
+N) when the tab bar overflows horizontally
- Closing a tab saves the list if that tab's
↓auto is on (off by default each session)
- Closing the last tab resets the content to an empty default state
Import and Export
- Load
.md and .txt files via the system file dialog
- Save the current list to
.md via a Save As dialog
↓auto button connects a tab to a file on disk and keeps it saved automatically (per tab, off by default each session)- Support for
[x] and [ ] checkboxes in Markdown
- URLs in tasks are extracted and become clickable links
Cross-Browser Sync
- Connect the same tab to the same file from two different browsers (e.g. Chrome and Brave) — edits made in one appear in the other within a couple of seconds
- Works entirely through the shared file on disk, no network or account involved
- Requires the File System Access API (built into Chrome; in Brave, enable it via
brave://flags)
Appearance
- Dark and light theme (toggle in the header)
- Language switch: Russian / English (toggle in the header)
- Drag & Drop for tasks and sections
Installation
- Download or clone the repository
- Open in Chrome:
chrome://extensions
- Enable Developer mode (toggle in the top right corner)
- Click Load unpacked
- Select the
Sidepad/ folder
- Click the extension icon in the Chrome toolbar — the side panel will open
After changing extension files, click the reload button on the extension card in chrome://extensions, then close and reopen the side panel.
Quick Start
The extension folder contains example.md — a ready-made list with tasks that demonstrates all Sidepad features: sections, links, drag & drop, import and export.
Two ways to load the example:
- Button in the empty list: on first launch, the empty
default.md shows a "Load example →" button — click it and example.md opens immediately
- Manually: click ↑ import and select
example.md from the Sidepad/ folder
After loading, default.md closes automatically.
Interface
┌─────────────────────────────────┐
│ ✳ default.md × ✳ work.md × ↓auto RU ◐│ ← Tabs + action buttons
├─────────────────────────────────┤
│ ~/tasks/ default.md — 3 / 10 │ ← Breadcrumb + done counter
├─────────────────────────────────┤
│ + new section... │ ← New section field
│ + new task... │ ← New task field
│ url (optional) │ ← URL field
│ [Select section ▾] [+ add] │ ← Dropdown + add button
├─────────────────────────────────┤
│ ↑ import ↓ export ▸ collapse ✕ clear│ ← Toolbar
├─────────────────────────────────┤
│ ▸ Section 1 2/5 › │ ← Section header (collapsed)
│ ▾ Section 2 0/3 › │ ← Section header (expanded)
│ ⠿ ☐ Task with link ⧉ → × │ ← Task (buttons appear on hover)
│ https://example.com │
│ ⠿ ☑ Completed task ⧉ × │ ← Completed task (with delete button)
└─────────────────────────────────┘
Interface Elements
| Element | Description |
|---|
✳ name.md × | Tab. × — close (saves first if ↓auto is on) |
RU / EN | Language toggle button |
◐ / ● | Dark/light theme toggle |
~/tasks/ name.md | Breadcrumb — current tab name |
N / M | Counter: done / total tasks |
↑ import | Open a .md file in a new tab |
↓ export | Save the current list to a file |
✕ clear | Clear the list (saves first if ↓auto is on; asks for confirmation) |
⠿ | Drag handle for a task |
⧉ | Copy task text to clipboard |
× on a task | Delete the task |
× on a section | Delete the section with all its tasks (appears on hover) |
✎ on a section | Rename the section (appears on hover) |
→ on a task | Move the task to another section (appears on hover) |
N/M in section header | Done / total in this section |
↓auto | Connect this tab to a file and keep it synced automatically |
▸ collapse / ▾ expand | Collapse or expand all sections at once |
Working with Tasks
Add a Task
- Fill in the "+ new task..." field
- Optionally specify a URL in the "url (optional)" field
- Choose a section from the dropdown (default — "Extra tasks")
- Press "+ add" or
Enter
The new task is added to the beginning of the selected section.
Mark as Done
Click the checkbox to the left of the task. A completed task moves to the end of its section and is visually marked. If all tasks in a section are done — the section auto-collapses.
Clicking again removes the checkmark.
Edit a Task
Click on the task text. The text becomes an editable field. To save — press Enter or click outside. To cancel — press Escape.
Delete a Task
Click the × button to the right of the task. The button is only available for manually added tasks.
Copy Text
Click ⧉ — the task text is copied to the clipboard, and a "⧉ copied" notification briefly appears.
Move to Another Section
Hover over a task — the → button appears on the right. Click it and select a section from the menu. The task moves to the beginning of the selected section.
Open a Link
If a task has a URL, it is displayed below the text. Clicking the link opens it in a new browser tab.
Working with Sections
Add a Section
- Fill in the "+ new section..." field
- Press "+ add" or
Enter while in the section field
The new section is added to the top of the list and becomes available in the dropdown when adding tasks.
If both fields are filled (both section and task) — pressing "+ add" will add both.
Collapse / Expand a Section
Click the section header. The › arrow indicates direction.
A section automatically collapses when all its tasks are marked as done.
The "▸ collapse all" button in the toolbar collapses all sections at once. Clicking it again — "▾ expand" — restores them.
Rename a Section
Hover over the section header — a ✎ button appears on the right. Click it — the header becomes an editable field. To save — press Enter or click outside. To cancel — press Escape.
If the new name matches an existing section, tasks from both sections are merged.
Delete a Section
Hover over the section header — a × button appears on the right. Click it. The section and all its tasks are deleted without confirmation.
Tabs
Each imported file opens as a separate tab. Tabs allow working with multiple lists simultaneously.
Switch Tabs
Click the desired tab in the top bar. Each tab's state is saved when switching.
Close a Tab
Click × on a tab. If ↓auto is on for that tab, the list is saved first — to the file it's connected to, or to Downloads as a plain name.md if it isn't connected to one. ↓auto is off by default and resets every time the panel reopens, so this only applies to tabs you've turned it on for during the current session.
Closing the last tab does not clear the list — the content resets to the empty default.md state.
Rename a Tab
Double-click the tab name to edit it inline. The .md extension is always appended automatically — you only edit the name part. Press Enter to confirm, Escape to cancel.
Import and Export
Import a File
Click ↑ import. A system file dialog opens (.md, .txt formats). After selecting, the file is parsed and opens in a new tab.
The format is detected automatically:
Markdown (file contains - or * bullets):
# List title
## Section name
- [ ] Uncompleted task
- [x] Completed task
- [ ] Task with link https://example.com
## Another section
- [ ] Another task
- Lines
## Heading become sections
- Lines
- [ ], - [x], * become tasks
- A URL in a task line automatically becomes a clickable link
- Lines starting with
#, |, `, ! and lines longer than 120 characters are ignored
Plain text (no - / * bullets — numbered lists, plain text notes):
SECTION HEADING
1. First task
2. Second task
Another section:
* Third task
• Fourth task
ALL CAPS LINE (≤ 60 chars) → sectionLine ending with : (≤ 60 chars) → section- Heading underlined with
--- or === → section
1. / 1) numbered items → tasks* / • bullet items → tasks- Any other plain line → task
[x], ✓, ✔ marks a task as done
Export to .md File
Click ↓ export. A Save As dialog opens with the current filename. The exported file contains all sections and tasks with [x] / [ ] marks. The chosen file is remembered — later exports or ↓auto (see below) reuse it directly, without asking again.
If the File System Access API isn't available (Brave with the flag off — see Cross-Browser Sync), export falls back to a native download dialog, which still avoids creating duplicate files like name (1).md.
Auto-save
Controlled by the ↓auto button in the tab bar — per tab, not global. The state persists across collapsing/reopening the panel — the next time the panel opens, the extension tries to silently resume sync for every tab that had ↓auto on.
Clicking ↓auto on:
- A tab that already has a connected file — silently reconfirms access to it (may show a brief in-page permission prompt)
- A tab with no connected file yet — opens a file picker to choose an existing file to connect to
If the tab already has real tasks and the chosen file holds a different list, you'll be asked to confirm before it's replaced — nothing is overwritten silently. Once connected, edits write to that file automatically (about 1.5 seconds after you stop typing), and changes made to the file from elsewhere — including another browser, see Cross-Browser Sync — are picked up automatically too.
Without a connected file, ↓auto still saves on close/clear as a plain, non-timestamped name.md in Downloads.
The example tab can never have ↓auto turned on. The default tab still asks for confirmation before saving over an existing list.
Resuming after the panel closes. The browser's file-access permission can occasionally expire without a way to silently renew it (the browser requires a click to ask again). When that happens, ↓auto reopens in its on state but with a warning icon — ↓auto ⚠ — meaning "this was on, click once to reconfirm access and resume syncing." If the permission hadn't expired, sync resumes fully automatically, with no indicator at all.
There are exactly three ways to turn auto-save off: clicking ↓auto manually, closing the tab itself, or declining to reconfirm access in the ↓auto ⚠ scenario above. Simply collapsing or closing the extension panel does not turn it off.
Cross-Browser Sync
Two browsers (e.g. Chrome and Brave) can keep the same tab's list in sync live, through a shared file on disk — no server, no account, no network traffic beyond your own filesystem.
This is the unchanged legacy file mode. It remains the default while the Notes API client is experimental.
How it Works
- In the first browser, click ↓auto on the tab you want to sync and pick the file to use (or connect to one you already export to).
- In the second browser, open the same tab (or the empty
default tab) and click ↓auto, choosing the same file.
- From then on, edits in either browser reach the other within a couple of seconds, as long as both side panels are open and both have
↓auto on for that tab.
Connecting the empty default tab to an existing file automatically renames it to match the file, so it stops behaving like a disposable default tab.
Requirements
- Chrome supports this out of the box.
- Brave disables the underlying File System Access API by default. Enable it at
brave://flags/#file-system-access-api, set it to Enabled, and relaunch Brave. Without this flag, ↓auto still works for local auto-save, just not live sync.
Safety
- Connecting a tab that already has tasks to a file with different content asks for confirmation first — it never silently replaces your list.
↓auto resets to off every time you reopen the panel, in both browsers — sync only runs while you've explicitly turned it on for the current session.- Sync is one file per tab and doesn't merge simultaneous edits from both sides — whichever write reaches the file last wins. It's meant for one person switching between two browsers, not concurrent editing by multiple people.
Experimental Notes API Mode
The Notes API switch changes only where tasks are stored: a regular notes.md tab appears and lives in Notes Lab instead of a file. The interface is the same — checkboxes, drag and drop, inline edit, sections, → move, import and export. The server owns task order (a new task goes to the top of its section, a finished one to the end). File tabs and ↓auto keep working as before.
The mode is off by default. While it is off, Sidepad does not request the optional https://notes.lab/* permission and sends no Notes API requests.
Connecting
- Turn on Notes API. Sidepad requests access to
https://notes.lab/* and opens https://notes.lab/#sidepad-connect=<extension id>.
- Sign in to Notes Lab and confirm. The page hands a one-time code to the extension through
externally_connectable; the Sidepad service worker exchanges it directly with https://notes.lab and stores the key only in chrome.storage.local.
- A connection attempt lives at most 10 minutes. Messages are accepted only from
https://notes.lab, only while an attempt is pending, and only with the exact schema.
Manual pairing_id + code entry stays in settings (⚙) under recovery. The key is never shown in the DOM and never reaches browser sync, storage.session, exports or logs. Forget the key removes only the local copy; revoke it in Notes Lab.
Legacy tab
On the first connection Sidepad asks which tab holds the old list (dop.md is suggested when present). While Notes API is on, that tab is read-only with “go to notes.md” and “close tab” actions; the file is never changed. The choice can be cleared in settings, and turning Notes API off restores the previous behavior completely.
Sync and revision safety
notes.md is read on open, on focus and every 2 seconds via ETag/304, only while the panel is visible. Offline, 429 and 503 use bounded backoff.- The protocol — revisions, semantic operations,
operation_id, refs, task order and error codes — is defined by the Notes Lab contract: HTTP API. Sidepad does not redefine it; if they disagree, the contract wins.
- A revision conflict rereads the document without replaying the operation. A lost response requires an explicit “retry”.
- Task text is normalized on save to the Markdown store rules: whitespace and line breaks collapse, a link in the text moves to the URL field.
- Offline shows the last confirmed snapshot read-only — no queue, no automatic replay.
- The «Неразобранные» section (the Whisper import inbox) is pinned on top of
notes.md and highlighted, as in Notes Lab web; the document order itself is unchanged. The section cannot be renamed, deleted or dragged, because the import looks it up by its exact name. Its tasks are edited as usual, long voice notes included: the text limit is 10,000 characters, as in web.
- ✕ clear on
notes.md only closes the local tab; the tasks stay on the server. Bring it back with “open notes.md”.
Drag and Drop
Drag & drop is supported for both tasks and sections.
Drag Tasks
Grab a task by the ⠿ handle and drag:
- Onto another task — places it before or after it (depending on cursor position)
- Onto a section header — moves the task to that section (at the end)
As an alternative to drag & drop, use the → button on hover — the task moves to the beginning of the selected section.
Drag Sections
Grab a section header and drag it onto another header — the section with all its tasks moves before or after the target section.
Keyboard Shortcuts
| Key | Context | Action |
|---|
Enter | Task field | Add task |
Enter | Section field | Add section |
Enter | URL field | Add task |
Enter | Edit task | Save changes |
Escape | Edit task | Cancel changes |
Enter | Rename section | Save new name |
Escape | Rename section | Cancel rename |
Enter | Rename tab | Save new name |
Escape | Rename tab | Cancel rename |
↑ / ↓ | Section dropdown | Navigate sections |
Enter / Space | Section dropdown | Select section |
Escape / Tab | Section dropdown | Close dropdown |
Data Storage
Legacy tab data is stored in chrome.storage.local. Experimental API state uses separate notesApi*V1 keys and contains only the last confirmed snapshot, a local draft and (when needed) an uncertain semantic operation; it stores no credential.
Storage structure:
{
"tabs": [
{
"id": "tab_1234567890",
"title": "work",
"tasks": [ ... ],
"sections": ["Priority", "Backlog"],
"autoSave": false
}
],
"activeTabId": "tab_1234567890",
"lightMode": false,
"lang": "en"
}
autoSave is per tab and persists across collapsing/reopening the panel (see Auto-save).
Data is saved on every change and restored on the next panel open. Legacy data format (before tabs were introduced) automatically migrates on first open.
Files connected via ↓auto or ↓ export are referenced through FileSystemFileHandle objects, which can't be stored as JSON — they're kept in a separate IndexedDB database (sidepad-handles), one entry per tab.
Technical Details
| Parameter | Value |
|---|
| Manifest version | V3 |
| Permissions | storage, sidePanel, downloads; optional https://notes.lab/* |
| Dependencies | none |
| Build | not required |
| Stack | Vanilla JS, HTML, CSS |
| Entry point | popup.html → popup.js |
| Service Worker | background.js |
Extension folder structure:
Sidepad/
├── manifest.json — extension configuration
├── background.js — service worker, opens panel on click
├── popup.html — UI markup
├── popup.css — styles
├── popup.js — all logic
├── popup-api.js — experimental API UI boundary
├── notes-api-auth.js — local-only pairing and scoped Bearer authorization
├── notes-api-client.js — revisioned client and injected transport
├── notes-api-state.js — pure client state machine
├── notes-api-mode.js — permission/cache/session controller
├── tests/ — Node unit and legacy-boundary tests
├── default.md — empty default list
├── example.md — usage example for new users
├── README.md — documentation (English)
├── README.ru.md — documentation (Russian)
├── INFO.ru.txt — plain text documentation (Russian)
├── INFO.en.txt — plain text documentation (English)
└── icons/
├── icon16.png
├── icon32.png
├── icon48.png
└── icon128.png
Task ID convention: built-in tasks have id ≤ 10000, user-created tasks have id > 10000 (calculated as Date.now() + 10001). The delete button is only shown for tasks with id > 10000.
