Skip to content

Commit 943680c

Browse files
committed
feat(docs): add vitepress-sidebar-accordion plugin page and config
1 parent c0f05ab commit 943680c

10 files changed

Lines changed: 172 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ It documents BinaryNoir's open-source VitePress plugins, Vite plugins and comman
1010
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
1111
| [`@binarynoir/vitepress-auto-sidebar`](https://github.com/binarynoir/vitepress-auto-sidebar) | Builds the sidebar from the folder tree |
1212
| [`@binarynoir/vitepress-auto-navbar`](https://github.com/binarynoir/vitepress-auto-navbar) | Builds the top navbar from the folder tree |
13+
| [`@binarynoir/vitepress-sidebar-accordion`](https://github.com/binarynoir/vitepress-sidebar-accordion) | One open sidebar group per level, as in VuePress |
1314
| [`@binarynoir/vitepress-markdown-tags`](https://github.com/binarynoir/vitepress-markdown-tags) | Status badges and tagged-page lists |
1415
| [`@binarynoir/vitepress-reading-time-tag`](https://github.com/binarynoir/vitepress-reading-time-tag) | `[[readingTime]]` tip blocks |
1516
| [`@binarynoir/vitepress-downloads`](https://github.com/binarynoir/vitepress-downloads) | Downloadable files from a `downloads` folder |

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,8 @@ export default defineConfig({
101101
maxTitleLength: 50,
102102
...menuTitleOptions,
103103
groupTitleFromIndex: true,
104+
// Groups start closed, so @binarynoir/vitepress-sidebar-accordion (in the theme) has a caret to toggle.
105+
collapsed: true,
104106
}),
105107

106108
socialLinks: [{ icon: 'github', link: 'https://github.com/binarynoir' }],

‎docs/.vitepress/theme/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { enableGlossaryTooltips } from 'markdown-it-glossary/client';
66
import { enableHtmlEscapeHints } from '@binarynoir/vitepress-html-escape/client';
77
import { enableBrokenLinkHints } from '@binarynoir/vitepress-broken-links/client';
88
import { enableImageFallbackHints } from '@binarynoir/vite-plugin-image-fallback/client';
9+
import { useSidebarAccordion } from '@binarynoir/vitepress-sidebar-accordion';
910
import './custom.css';
1011

1112
export default {
@@ -22,4 +23,8 @@ export default {
2223
// Dashed outlines and popovers on placeholders for images that are missing.
2324
enableImageFallbackHints();
2425
},
26+
setup() {
27+
// One open sidebar group per level, and only the current page's branch open after navigating.
28+
useSidebarAccordion();
29+
},
2530
} satisfies Theme;

‎docs/guide/how-this-site-works.md‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ title: How this site works
66

77
[[readingTime]]
88

9-
This site is plain VitePress 2 plus thirteen plugins. There is no hand-written navigation anywhere: add a Markdown file in the right folder and it shows up in the sidebar, the navbar, search and the sitemap.
9+
This site is plain VitePress 2 plus fourteen plugins. There is no hand-written navigation anywhere: add a Markdown file in the right folder and it shows up in the sidebar, the navbar, search and the sitemap.
1010

1111
## Folder layout
1212

@@ -33,21 +33,22 @@ docs/
3333

3434
## Which plugin does what
3535

36-
| You see | Plugin | Where it is wired |
37-
| ------------------------------- | --------------------------------------------- | ------------------------------------- |
38-
| Top navbar | [Auto Navbar](/plugins/auto-navbar) | `themeConfig.nav` in `config.mts` |
39-
| Left sidebar | [Auto Sidebar](/plugins/auto-sidebar/) | `themeConfig.sidebar` in `config.mts` |
40-
| Status badges | [Markdown Tags](/plugins/markdown-tags/) | `markdown.config`, plus the theme |
41-
| "Reading time" box | [Reading Time Tag](/plugins/reading-time-tag) | `markdown.config` |
42-
| Dotted-underline hovers | [Glossary Tooltips](/plugins/glossary/) | `markdown.config` |
43-
| Colored and sized text | [Text Style](/plugins/text-style) | `markdown.config` |
44-
| File download links | [Downloads](/plugins/downloads) | `markdown.config` and `vite.plugins` |
45-
| Stray `<tags>` shown as text | [HTML Escape](/plugins/html-escape/) | `markdown.config`, plus the theme |
46-
| Dead links shown as text | [Broken Links](/plugins/broken-links) | `markdown.config`, plus the theme |
47-
| Pages left out by `.exclude` | [Exclude](/plugins/exclude/) | `srcExclude` and `vite.plugins` |
48-
| `README.md` as a folder's index | [README Index](/plugins/readme-index/) | `rewrites` and `markdown.config` |
49-
| Smaller images | [Optimize Images](/plugins/optimize-images) | `vite.plugins` |
50-
| Placeholder for a missing image | [Image Fallback](/plugins/image-fallback) | `vite.plugins`, plus the theme |
36+
| You see | Plugin | Where it is wired |
37+
| -------------------------------- | ----------------------------------------------- | ------------------------------------------------ |
38+
| Top navbar | [Auto Navbar](/plugins/auto-navbar) | `themeConfig.nav` in `config.mts` |
39+
| One open sidebar group per level | [Sidebar Accordion](/plugins/sidebar-accordion) | The theme, plus `collapsed: true` on the sidebar |
40+
| Left sidebar | [Auto Sidebar](/plugins/auto-sidebar/) | `themeConfig.sidebar` in `config.mts` |
41+
| Status badges | [Markdown Tags](/plugins/markdown-tags/) | `markdown.config`, plus the theme |
42+
| "Reading time" box | [Reading Time Tag](/plugins/reading-time-tag) | `markdown.config` |
43+
| Dotted-underline hovers | [Glossary Tooltips](/plugins/glossary/) | `markdown.config` |
44+
| Colored and sized text | [Text Style](/plugins/text-style) | `markdown.config` |
45+
| File download links | [Downloads](/plugins/downloads) | `markdown.config` and `vite.plugins` |
46+
| Stray `<tags>` shown as text | [HTML Escape](/plugins/html-escape/) | `markdown.config`, plus the theme |
47+
| Dead links shown as text | [Broken Links](/plugins/broken-links) | `markdown.config`, plus the theme |
48+
| Pages left out by `.exclude` | [Exclude](/plugins/exclude/) | `srcExclude` and `vite.plugins` |
49+
| `README.md` as a folder's index | [README Index](/plugins/readme-index/) | `rewrites` and `markdown.config` |
50+
| Smaller images | [Optimize Images](/plugins/optimize-images) | `vite.plugins` |
51+
| Placeholder for a missing image | [Image Fallback](/plugins/image-fallback) | `vite.plugins`, plus the theme |
5152

5253
## The config
5354

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ features:
2626
width: 28
2727
height: 28
2828
title: Navigation from your folders
29-
details: Auto Sidebar and Auto Navbar build the menus from your folder tree, ordered and titled by small plain-text files.
29+
details: Auto Sidebar and Auto Navbar build the menus from your folder tree, ordered and titled by small plain-text files. Sidebar Accordion keeps one group open at a time.
3030
link: /plugins/#navigation
3131
linkText: Navigation plugins
3232
- icon:

‎docs/plugins/.sidebar‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ index.md:Overview
55
[Navigation from your folders]
66
auto-sidebar:Auto Sidebar
77
auto-navbar.md:Auto Navbar
8+
sidebar-accordion.md:Sidebar Accordion
89
[Richer pages]
910
markdown-tags:Markdown Tags
1011
glossary:Glossary Tooltips

‎docs/plugins/index.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,19 @@ title: Plugins
66

77
[[readingTime]]
88

9-
Thirteen small packages that make a documentation site easier to build and nicer to read. Each one does a single job and they share conventions. All thirteen are running on the site you are looking at.
9+
Fourteen small packages that make a documentation site easier to build and nicer to read. Each one does a single job and they share conventions. All fourteen are running on the site you are looking at.
1010

1111
Pick by the job you need done. Each plugin's page has a live demo.
1212

1313
## Navigation from your folders {#navigation}
1414

1515
Menus that follow your folder tree, so adding a page never means editing the config.
1616

17-
| Plugin | Works with | What it does |
18-
| -------------------------------------- | ----------- | ----------------------------------------------- |
19-
| [Auto Sidebar](/plugins/auto-sidebar/) | VitePress 2 | Builds `themeConfig.sidebar` from your folders. |
20-
| [Auto Navbar](/plugins/auto-navbar) | VitePress 2 | Builds `themeConfig.nav` from your folders. |
17+
| Plugin | Works with | What it does |
18+
| ----------------------------------------------- | ----------- | ------------------------------------------------- |
19+
| [Auto Sidebar](/plugins/auto-sidebar/) | VitePress 2 | Builds `themeConfig.sidebar` from your folders. |
20+
| [Auto Navbar](/plugins/auto-navbar) | VitePress 2 | Builds `themeConfig.nav` from your folders. |
21+
| [Sidebar Accordion](/plugins/sidebar-accordion) | VitePress | One open sidebar group per level, as in VuePress. |
2122

2223
## Richer pages {#pages}
2324

@@ -64,6 +65,7 @@ Smaller images in the output, and no failed build over a missing one.
6465
npm install --save-dev \
6566
@binarynoir/vitepress-auto-sidebar \
6667
@binarynoir/vitepress-auto-navbar \
68+
@binarynoir/vitepress-sidebar-accordion \
6769
@binarynoir/vitepress-markdown-tags \
6870
@binarynoir/vitepress-reading-time-tag \
6971
@binarynoir/vitepress-downloads \
@@ -79,7 +81,7 @@ npm install --save-dev \
7981

8082
The VitePress plugins target VitePress 2 (currently an alpha release line). Node 22 or newer is required.
8183

82-
## One config, all thirteen
84+
## One config, all fourteen
8385

8486
This is this site's real `config.mts`, included straight from the repository, so it can't drift from what is deployed. [How this site works](/guide/how-this-site-works) walks through it.
8587

‎docs/plugins/sidebar-accordion.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Sidebar Accordion
3+
---
4+
5+
# Sidebar Accordion ((tag|VitePress plugin|blue))
6+
7+
[[readingTime]]
8+
9+
[![GitHub repo](https://img.shields.io/badge/GitHub-binarynoir%2Fvitepress--sidebar--accordion-181717?logo=github)](https://github.com/binarynoir/vitepress-sidebar-accordion) [![npm version](https://img.shields.io/npm/v/@binarynoir/vitepress-sidebar-accordion)](https://www.npmjs.com/package/@binarynoir/vitepress-sidebar-accordion) [![CI](https://img.shields.io/github/actions/workflow/status/binarynoir/vitepress-sidebar-accordion/ci.yml?branch=main&label=CI)](https://github.com/binarynoir/vitepress-sidebar-accordion/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/binarynoir/vitepress-sidebar-accordion)](https://github.com/binarynoir/vitepress-sidebar-accordion/blob/main/LICENSE)
10+
11+
`@binarynoir/vitepress-sidebar-accordion` turns the default theme's sidebar into an accordion: one open group per level. Opening a group closes the groups beside it, and after navigating, only the branch holding the current page stays open.
12+
13+
That is how the VuePress sidebar behaved, so a site moving to VitePress keeps the same feel. On a large docs site it also keeps the sidebar short.
14+
15+
## See it live
16+
17+
This site's sidebar is the demo. Try it in the sidebar beside this page:
18+
19+
1. Open **Richer pages**. **Navigation from your folders**, the group this page is in, closes.
20+
2. Inside **Richer pages**, open **Markdown Tags**, then **Glossary Tooltips**. Markdown Tags closes; Richer pages stays open.
21+
3. Follow any link in the sidebar. Only the new page's branch is left open.
22+
4. Come back to this page and close **Navigation from your folders**, then follow the [Auto Navbar](/plugins/auto-navbar) link. The group opens again, because the page you landed on is in it.
23+
24+
| Reader does | Default VitePress | With the accordion |
25+
| ---------------------------------- | ------------------------------------- | ---------------------------------------------- |
26+
| Opens a group | Every group they opened stays open | Open groups at the same level close |
27+
| Opens a group inside another group | Its siblings stay open | Only its siblings close; the parent stays open |
28+
| Follows a link to another page | Groups opened along the way stay open | Only the new page's branch is left open |
29+
| Closes the current page's group | It stays closed on the next page | It opens again on the next page in that branch |
30+
31+
## Install
32+
33+
```sh
34+
npm install --save-dev @binarynoir/vitepress-sidebar-accordion
35+
```
36+
37+
## Use
38+
39+
**1. Theme.** Call `useSidebarAccordion()` from your theme's `setup`:
40+
41+
```ts
42+
// .vitepress/theme/index.ts
43+
import DefaultTheme from 'vitepress/theme';
44+
import { useSidebarAccordion } from '@binarynoir/vitepress-sidebar-accordion';
45+
46+
export default {
47+
extends: DefaultTheme,
48+
setup() {
49+
useSidebarAccordion();
50+
},
51+
};
52+
```
53+
54+
**2. Sidebar.** Give each group a `collapsed` value. VitePress only draws the caret that opens and closes a group when `collapsed` is set, and the accordion works through that caret. `collapsed: true` starts the groups closed; VitePress opens the current page's branch on load.
55+
56+
```ts
57+
// .vitepress/config.mts
58+
export default defineConfig({
59+
themeConfig: {
60+
sidebar: [
61+
{
62+
text: 'Guide',
63+
collapsed: true,
64+
items: [
65+
{ text: 'Introduction', link: '/guide/' },
66+
{
67+
text: 'Advanced',
68+
collapsed: true,
69+
items: [{ text: 'Plugins', link: '/guide/plugins' }],
70+
},
71+
],
72+
},
73+
{ text: 'Reference', collapsed: true, items: [{ text: 'API', link: '/reference/api' }] },
74+
],
75+
},
76+
});
77+
```
78+
79+
Groups without `collapsed` are always open, and the accordion leaves them alone.
80+
81+
### With Auto Sidebar
82+
83+
[Auto Sidebar](/plugins/auto-sidebar/) sets `collapsed` on every group it generates through its `collapsed` option. This site does exactly that:
84+
85+
```ts
86+
sidebar: generateSidebar(docsRoot, {
87+
collapsed: true,
88+
}),
89+
```
90+
91+
## How it works
92+
93+
VitePress keeps each group's open state inside its sidebar item component and offers no API to change it. So the accordion clicks the group's caret, the same button a reader would press, and VitePress's own state stays in sync.
94+
95+
- A click the reader makes on a group header or caret is caught in the capture phase, because the caret stops its click from bubbling. Once Vue has updated, if the group is now open, the open groups beside it, and any open groups inside those, are closed, innermost first.
96+
- Clicks the accordion makes itself are not trusted events, so they never start another round.
97+
- After each route change, once VitePress has opened the new page's branch, the accordion opens any group in that branch the reader had closed and closes the branches beside it.
98+
- During the server-side build, `useSidebarAccordion()` does nothing.
99+
100+
It reads VitePress's own class names (`.VPSidebarItem`, `.collapsible`, `.collapsed`, `.has-active`, `.is-active`, `.caret`), so it works with the default theme's sidebar, or a custom one that renders the same markup.
101+
102+
## Exports
103+
104+
`useSidebarAccordion()` is all most sites need. The pieces it is built from are exported too, for a theme that wants to wire them up its own way:
105+
106+
| Export | What it does |
107+
| ---------------------------- | ---------------------------------------------------------------------- |
108+
| `handleSidebarClick(event)` | The capture-phase click handler `useSidebarAccordion` adds. |
109+
| `keepActiveBranchOnly(root)` | Opens the current page's branch and closes the rest. |
110+
| `closeOpenSiblings(item)` | Closes the open groups beside `item`, and any open groups inside them. |
111+
| `getSiblingItems(item)` | The sidebar items at the same level as `item`. |
112+
| `toggleGroup(group)` | Opens or closes a group by clicking its caret. |
113+
| `isOpenGroup(item)` | Whether `item` is a group that is currently open. |
114+
| `GROUP_SELECTOR` and friends | The CSS selectors above, for matching the same elements in theme code. |
115+
116+
## Limits
117+
118+
- **Default theme markup only.** A theme that replaces the sidebar with different markup needs its own accordion.
119+
- **Groups need `collapsed`.** A group without it has no caret, and stays open.
120+
121+
[Source and full README on GitHub](https://github.com/binarynoir/vitepress-sidebar-accordion)

‎package-lock.json‎

Lines changed: 15 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
"@binarynoir/vitepress-markdown-tags": "^0.2.6",
3434
"@binarynoir/vitepress-reading-time-tag": "^0.1.8",
3535
"@binarynoir/vitepress-readme-index": "^0.1.1",
36+
"@binarynoir/vitepress-sidebar-accordion": "^0.1.0",
3637
"@binarynoir/vitepress-text-style": "^0.1.1",
3738
"@types/node": "^24.19.2",
3839
"markdown-it-glossary": "^0.4.3",

0 commit comments

Comments
 (0)