From 9c6968aedd9eaccebdf85f88dc6cbf0cacf3ee86 Mon Sep 17 00:00:00 2001 From: sudacode Date: Sun, 29 Mar 2026 15:37:49 -0700 Subject: [PATCH] docs: add subtitle sidebar guide and release note --- ...le-sidebar-and-Jimaku-integration-pages.md | 25 +++++++ changes/251-docs-site-sidebar.md | 6 ++ docs-site/.vitepress/config.ts | 2 + docs-site/.vitepress/theme/tui-theme.css | 29 ++++++-- docs-site/configuration.md | 2 + docs-site/index.md | 6 +- docs-site/jimaku-integration.md | 2 +- docs-site/subtitle-sidebar.md | 71 +++++++++++++++++++ 8 files changed, 134 insertions(+), 9 deletions(-) create mode 100644 backlog/tasks/task-251 - Docs-add-subtitle-sidebar-and-Jimaku-integration-pages.md create mode 100644 changes/251-docs-site-sidebar.md create mode 100644 docs-site/subtitle-sidebar.md diff --git a/backlog/tasks/task-251 - Docs-add-subtitle-sidebar-and-Jimaku-integration-pages.md b/backlog/tasks/task-251 - Docs-add-subtitle-sidebar-and-Jimaku-integration-pages.md new file mode 100644 index 0000000..42d809f --- /dev/null +++ b/backlog/tasks/task-251 - Docs-add-subtitle-sidebar-and-Jimaku-integration-pages.md @@ -0,0 +1,25 @@ +--- +id: TASK-251 +title: 'Docs: add subtitle sidebar and Jimaku integration pages' +status: In Progress +assignee: [] +created_date: '2026-03-29 22:36' +labels: + - docs +dependencies: [] +priority: medium +--- + +## Description + + +Track the docs-site update that adds a dedicated subtitle sidebar page, links Jimaku integration from the homepage/config docs, and refreshes the docs-site theme styling used by those pages. + + +## Acceptance Criteria + +- [ ] #1 docs-site nav includes a Subtitle Sidebar entry +- [ ] #2 Subtitle Sidebar page documents layout, shortcut, and config options +- [ ] #3 Jimaku integration page and configuration docs link to the new docs page +- [ ] #4 Changelog fragment exists for the user-visible docs release note + diff --git a/changes/251-docs-site-sidebar.md b/changes/251-docs-site-sidebar.md new file mode 100644 index 0000000..ef61782 --- /dev/null +++ b/changes/251-docs-site-sidebar.md @@ -0,0 +1,6 @@ +type: docs +area: docs-site + +- Added a dedicated Subtitle Sidebar guide and linked it from the homepage and configuration docs. +- Linked Jimaku integration from the homepage to its dedicated docs page. +- Refreshed docs-site theme tokens and hover/selection styling for the updated pages. diff --git a/docs-site/.vitepress/config.ts b/docs-site/.vitepress/config.ts index 62e74b0..f3d282b 100644 --- a/docs-site/.vitepress/config.ts +++ b/docs-site/.vitepress/config.ts @@ -74,7 +74,9 @@ export default { { text: 'Configuration', link: '/configuration' }, { text: 'Keyboard Shortcuts', link: '/shortcuts' }, { text: 'Subtitle Annotations', link: '/subtitle-annotations' }, + { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' }, { text: 'Immersion Tracking', link: '/immersion-tracking' }, + { text: 'JLPT Vocabulary Bundle', link: '/jlpt-vocab-bundle' }, { text: 'Troubleshooting', link: '/troubleshooting' }, ], }, diff --git a/docs-site/.vitepress/theme/tui-theme.css b/docs-site/.vitepress/theme/tui-theme.css index a98a239..1ff3b2f 100644 --- a/docs-site/.vitepress/theme/tui-theme.css +++ b/docs-site/.vitepress/theme/tui-theme.css @@ -34,6 +34,25 @@ system-ui, sans-serif; --tui-transition: 180ms ease; + + /* Theme-specific values — overridden in .dark below */ + --tui-nav-bg: color-mix(in srgb, var(--vp-c-bg-alt) 88%, transparent); + --tui-table-hover-bg: color-mix(in srgb, var(--vp-c-bg-soft) 80%, transparent); + --tui-link-underline: color-mix(in srgb, var(--vp-c-brand-1) 40%, transparent); + --tui-selection-bg: hsla(267, 83%, 45%, 0.14); + --tui-hero-glow: hsla(267, 83%, 45%, 0.05); + --tui-step-hover-bg: var(--vp-c-bg-alt); + --tui-step-hover-glow: color-mix(in srgb, var(--vp-c-brand-1) 30%, transparent); +} + +.dark { + --tui-nav-bg: hsla(232, 23%, 18%, 0.82); + --tui-table-hover-bg: hsla(232, 23%, 18%, 0.4); + --tui-link-underline: hsla(267, 83%, 80%, 0.3); + --tui-selection-bg: hsla(267, 83%, 80%, 0.22); + --tui-hero-glow: hsla(267, 83%, 80%, 0.06); + --tui-step-hover-bg: hsla(232, 23%, 18%, 0.6); + --tui-step-hover-glow: hsla(267, 83%, 80%, 0.3); } :root { @@ -48,7 +67,7 @@ /* === Selection === */ ::selection { - background: hsla(267, 83%, 80%, 0.22); + background: var(--tui-selection-bg); color: var(--vp-c-text-1); } @@ -102,7 +121,7 @@ button, } .VPNav .VPNavBar:not(.has-sidebar) { - background: hsla(232, 23%, 18%, 0.82); + background: var(--tui-nav-bg); } .VPNav .VPNavBar.has-sidebar .content { @@ -245,13 +264,13 @@ button, } .vp-doc table tr:hover td { - background: hsla(232, 23%, 18%, 0.4); + background: var(--tui-table-hover-bg); } /* === Links === */ .vp-doc a { text-decoration: none; - border-bottom: 1px solid hsla(267, 83%, 80%, 0.3); + border-bottom: 1px solid var(--tui-link-underline); transition: border-color var(--tui-transition), color var(--tui-transition); } @@ -653,7 +672,7 @@ body { height: 400px; background: radial-gradient( ellipse at center, - hsla(267, 83%, 80%, 0.06) 0%, + var(--tui-hero-glow) 0%, transparent 70% ); pointer-events: none; diff --git a/docs-site/configuration.md b/docs-site/configuration.md index 399bc63..0b6e2b6 100644 --- a/docs-site/configuration.md +++ b/docs-site/configuration.md @@ -390,6 +390,8 @@ The sidebar is only available when the active subtitle source has been parsed in `embedded` layout is intended to act like a split-pane view: it reserves player space with a right-side video margin and keeps interaction in both the player area and sidebar. If you see unexpected offset behavior in your environment, switch back to `overlay` to isolate sidebar placement. +For full details on layout modes, behavior, and the keyboard shortcut, see the [Subtitle Sidebar](/subtitle-sidebar) page. + `jlptColors` keys are: | Key | Default | Description | diff --git a/docs-site/index.md b/docs-site/index.md index 62c98e2..f11b8d1 100644 --- a/docs-site/index.md +++ b/docs-site/index.md @@ -67,7 +67,7 @@ features: alt: Subtitle download icon title: Subtitle Download & Sync details: Search and pull subtitles from Jimaku, then auto-sync timing with alass or ffsubsync — all from the overlay. - link: /configuration#jimaku + link: /jimaku-integration linkText: Jimaku integration - icon: src: /assets/tokenization.svg @@ -223,12 +223,12 @@ const demoAssetVersion = '20260223-2'; } .workflow-step:hover { - background: hsla(232, 23%, 18%, 0.6); + background: var(--tui-step-hover-bg); } .workflow-step:hover .step-number { color: var(--vp-c-brand-1); - text-shadow: 0 0 12px hsla(267, 83%, 80%, 0.3); + text-shadow: 0 0 12px var(--tui-step-hover-glow); } .workflow-connector { diff --git a/docs-site/jimaku-integration.md b/docs-site/jimaku-integration.md index 4d74bd6..2c6e9b0 100644 --- a/docs-site/jimaku-integration.md +++ b/docs-site/jimaku-integration.md @@ -131,6 +131,6 @@ Verify mpv is running and connected via IPC. SubMiner loads the subtitle by issu ## Related -- [Configuration Reference](/configuration#jimaku) — full config section +- [Configuration Reference](/configuration#jimaku) — full config options - [Mining Workflow](/mining-workflow#jimaku-subtitle-search) — how Jimaku fits into the sentence mining loop - [Troubleshooting](/troubleshooting#jimaku) — additional error guidance diff --git a/docs-site/subtitle-sidebar.md b/docs-site/subtitle-sidebar.md new file mode 100644 index 0000000..42be19a --- /dev/null +++ b/docs-site/subtitle-sidebar.md @@ -0,0 +1,71 @@ +# Subtitle Sidebar + +The subtitle sidebar displays the full parsed cue list for the active subtitle file as a scrollable panel alongside mpv. It lets you review past and upcoming lines, click any cue to seek directly to that moment, and follow along without depending on the transient overlay subtitles. + +The sidebar is opt-in and disabled by default. Enable it under `subtitleSidebar.enabled` in your config. + +## How It Works + +When SubMiner parses the active subtitle source into a cue list, the sidebar becomes available. Toggle it with the `\` key (configurable via `subtitleSidebar.toggleKey`). While open: + +- The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`). +- Clicking any cue seeks mpv to that timestamp. +- The sidebar stays synchronized with the overlay — media transitions and subtitle source changes update both simultaneously. + +The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar. + +## Layout Modes + +Two layout modes are available via `subtitleSidebar.layout`: + +**`overlay`** (default) — The sidebar floats over mpv as a panel. It does not affect the player window size or position. + +**`embedded`** — Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue. + +## Configuration + +Enable and configure the sidebar under `subtitleSidebar` in your config file: + +```json +{ + "subtitleSidebar": { + "enabled": false, + "autoOpen": false, + "layout": "overlay", + "toggleKey": "Backslash", + "pauseVideoOnHover": false, + "autoScroll": true, + "fontFamily": "\"M PLUS 1\", \"Noto Sans CJK JP\", sans-serif", + "fontSize": 16 + } +} +``` + +| Option | Type | Default | Description | +| --------------------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------- | +| `enabled` | boolean | `false` | Enable subtitle sidebar support | +| `autoOpen` | boolean | `false` | Open the sidebar automatically on overlay startup | +| `layout` | string | `"overlay"` | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space | +| `toggleKey` | string | `"Backslash"` | `KeyboardEvent.code` for the toggle shortcut | +| `pauseVideoOnHover` | boolean | `false` | Pause playback while hovering the cue list | +| `autoScroll` | boolean | `true` | Keep the active cue in view during playback | +| `maxWidth` | number | `420` | Maximum sidebar width in CSS pixels | +| `opacity` | number | `0.95` | Sidebar opacity between `0` and `1` | +| `backgroundColor` | string | — | Sidebar shell background color | +| `textColor` | string | — | Default cue text color | +| `fontFamily` | string | — | CSS `font-family` applied to cue text | +| `fontSize` | number | `16` | Base cue font size in CSS pixels | +| `timestampColor` | string | — | Cue timestamp color | +| `activeLineColor` | string | — | Active cue text color | +| `activeLineBackgroundColor` | string | — | Active cue background color | +| `hoverLineBackgroundColor` | string | — | Hovered cue background color | + +Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like a solid overlay. + +## Keyboard Shortcut + +| Key | Action | Config key | +| --- | ----------------------- | ------------------------------ | +| `\` | Toggle subtitle sidebar | `subtitleSidebar.toggleKey` | + +The toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source. See [Keyboard Shortcuts](/shortcuts) for the full shortcut reference.