feat(docs): add Exclude and README Index plugins, regroup plugin pages

Author: jsmith3rd

README.md

@@ -16,6 +16,8 @@ It documents BinaryNoir's open-source VitePress plugins, Vite plugins and comman
 | [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary)                           | Hover definitions from `docs/reference/glossary.md`                                            |
 | [`@binarynoir/vitepress-html-escape`](https://github.com/binarynoir/vitepress-html-escape)             | Stray tags like `Array<string>` and `{{ }}` render as text; hints underline them in `docs:dev` |
 | [`@binarynoir/vitepress-broken-links`](https://github.com/binarynoir/vitepress-broken-links)           | Dead links render as text with a fix-it popover instead of failing the build                   |
+| [`@binarynoir/vitepress-exclude`](https://github.com/binarynoir/vitepress-exclude)                     | `.exclude` files keep pages out of the build (a draft in `docs/plugins/exclude/` on purpose)   |
+| [`@binarynoir/vitepress-readme-index`](https://github.com/binarynoir/vitepress-readme-index)           | `README.md` served as a folder's index page, for VuePress migrations                           |
 | [`@binarynoir/vite-plugin-optimize-images`](https://github.com/binarynoir/vite-plugin-optimize-images) | Re-compresses images in the build output                                                       |
 | [`@binarynoir/vite-plugin-image-fallback`](https://github.com/binarynoir/vite-plugin-image-fallback)   | Placeholder for missing images (one is missing on purpose)                                     |
 

docs/.vitepress/config.mts

@@ -12,6 +12,8 @@ import { downloadsMarkdown, downloadsVitePlugin } from '@binarynoir/vitepress-do
 import { downloadsSrcExclude } from '@binarynoir/vitepress-downloads/vitepress';
 import { markdownHtmlEscape } from '@binarynoir/vitepress-html-escape';
 import { markdownBrokenLinks } from '@binarynoir/vitepress-broken-links';
+import { excludeSrc, excludeVitePlugin } from '@binarynoir/vitepress-exclude';
+import { readmeLinks, readmeRewrites } from '@binarynoir/vitepress-readme-index';
 
 // import.meta.dirname, not __dirname: VitePress configs are ESM.
 const docsRoot = path.resolve(import.meta.dirname, '..');
@@ -28,8 +30,17 @@ export default defineConfig({
   cleanUrls: true,
   lastUpdated: true,
 
-  // Files in a `downloads` or `files` folder are published as-is, never built as pages.
-  srcExclude: downloadsSrcExclude(downloadsOptions),
+  srcExclude: [
+    // Files in a `downloads` or `files` folder are published as-is, never built as pages.
+    ...downloadsSrcExclude(downloadsOptions),
+    // @binarynoir/vitepress-exclude: whatever a folder's `.exclude` file lists is not built.
+    // The same files hide those pages from the sidebar and navbar.
+    ...excludeSrc(docsRoot),
+  ],
+
+  // @binarynoir/vitepress-readme-index: a folder's README.md is served as its index page,
+  // as VuePress did, so a VuePress site can move over without renaming files.
+  rewrites: readmeRewrites(docsRoot),
 
   sitemap: { hostname: SITE_URL },
 
@@ -110,6 +121,8 @@ export default defineConfig({
       md.use(markdownTags);
       // @binarynoir/vitepress-downloads: links into a `downloads` or `files` folder become file downloads.
       md.use(downloadsMarkdown, downloadsOptions);
+      // @binarynoir/vitepress-readme-index: a link to README.md goes to the page it is served as.
+      md.use(readmeLinks);
       // @binarynoir/vitepress-html-escape: stray tags like Array<string>, and {{ }} in prose,
       // render as text instead of breaking the Vue compile. It runs after every other rule.
       // In `vitepress dev`, hints underline each fix and explain it; `vitepress build` leaves them out.
@@ -141,6 +154,8 @@ export default defineConfig({
       taggedPagesVitePlugin(),
       // Publishes the files in each `downloads` or `files` folder at their page-relative URL.
       downloadsVitePlugin(downloadsOptions),
+      // Restarts `vitepress dev` when an `.exclude` file changes, so new rules apply right away.
+      excludeVitePlugin(),
     ],
   },
 });

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

@@ -6,7 +6,7 @@ title: How this site works
 
 [[readingTime]]
 
-This site is plain VitePress 2 plus ten 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.
+This site is plain VitePress 2 plus twelve 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.
 
 ## Folder layout
 
@@ -19,6 +19,8 @@ docs/
   plugins/              developer docs for each plugin
     .sidebar            order and titles for this section
     downloads/          files the Downloads demo publishes as-is
+    exclude/            a .exclude file and the draft it keeps out of the build
+    readme-index/       pages served from README.md, as in VuePress
   apps/                 user docs for the CLI apps
   guide/                this section
   reference/            glossary terms and the generated list of every tag
@@ -41,6 +43,8 @@ docs/
 | File download links             | [Downloads](/plugins/downloads)               | `markdown.config` and `vite.plugins`  |
 | Stray `<tags>` shown as text    | [HTML Escape](/plugins/html-escape/)          | `markdown.config`, plus the theme     |
 | Dead links shown as text        | [Broken Links](/plugins/broken-links)         | `markdown.config`, plus the theme     |
+| Pages left out by `.exclude`    | [Exclude](/plugins/exclude/)                  | `srcExclude` and `vite.plugins`       |
+| `README.md` as a folder's index | [README Index](/plugins/readme-index/)        | `rewrites` and `markdown.config`      |
 | Smaller images                  | [Optimize Images](/plugins/optimize-images)   | `vite.plugins`                        |
 | Placeholder for a missing image | [Image Fallback](/plugins/image-fallback)     | `vite.plugins`                        |
 

docs/index.md

@@ -25,73 +25,46 @@ features:
       dark: /icons/layout-dark.svg
       width: 28
       height: 28
-    title: Auto Sidebar & Navbar
-    details: Menus built from your folder structure, ordered and titled by tiny plain-text files.
-    link: /plugins/auto-sidebar
-    linkText: See the sidebar plugin
+    title: Navigation from your folders
+    details: Auto Sidebar and Auto Navbar build the menus from your folder tree, ordered and titled by small plain-text files.
+    link: /plugins/#navigation
+    linkText: Navigation plugins
   - icon:
       light: /icons/tag-light.svg
       dark: /icons/tag-dark.svg
       width: 28
       height: 28
-    title: Markdown Tags
-    details: Inline status badges for VitePress, VS Code and Obsidian, plus site-wide pages that list every tag.
-    link: /plugins/markdown-tags/
-    linkText: See the tags plugin
+    title: Richer pages
+    details: Markdown Tags, Glossary Tooltips and Reading Time add status badges, hover definitions and reading-time estimates.
+    link: /plugins/#pages
+    linkText: Page plugins
   - icon:
-      light: /icons/book-light.svg
-      dark: /icons/book-dark.svg
+      light: /icons/folder-light.svg
+      dark: /icons/folder-dark.svg
       width: 28
       height: 28
-    title: Glossary Tooltips
-    details: Define a term once and every mention in your docs gets a hover definition.
-    link: /plugins/glossary
-    linkText: See the glossary plugin
-  - icon:
-      light: /icons/clock-light.svg
-      dark: /icons/clock-dark.svg
-      width: 28
-      height: 28
-    title: Reading Time
-    details: One line in a page gets an estimated reading time, computed at build time.
-    link: /plugins/reading-time-tag
-    linkText: See the reading-time plugin
-  - icon:
-      light: /icons/download-light.svg
-      dark: /icons/download-dark.svg
-      width: 28
-      height: 28
-    title: Downloads
-    details: Keep a .sql, .zip or .xlsx next to the page that links to it, and the link downloads the file.
-    link: /plugins/downloads
-    linkText: See the downloads plugin
+    title: Content where it lives
+    details: Downloads next to the page that links them, drafts left out with a .exclude file, and README.md index pages for VuePress migrations.
+    link: /plugins/#content
+    linkText: Content plugins
   - icon:
       light: /icons/escape-light.svg
       dark: /icons/escape-dark.svg
       width: 28
       height: 28
-    title: HTML Escape
-    details: A stray Array<string> or {{ }} in your Markdown shows up as text instead of breaking the build.
-    link: /plugins/html-escape/
-    linkText: See the HTML Escape plugin
-  - icon:
-      light: /icons/link-light.svg
-      dark: /icons/link-dark.svg
-      width: 28
-      height: 28
-    title: Broken Links
-    details: A link to a page that doesn't exist shows up as text with a fix-it hint instead of failing the build.
-    link: /plugins/broken-links
-    linkText: See the Broken Links plugin
+    title: Builds that don't break
+    details: HTML Escape and Broken Links turn a stray Array<string> or a dead link into a fix-it hint instead of a failed build.
+    link: /plugins/#builds
+    linkText: Build plugins
   - icon:
       light: /icons/image-light.svg
       dark: /icons/image-dark.svg
       width: 28
       height: 28
-    title: Image Optimization & Fallback
-    details: Smaller images in the build output, and a placeholder instead of a failed build when one goes missing.
-    link: /plugins/optimize-images
-    linkText: See the image plugins
+    title: Images handled
+    details: Optimize Images shrinks every image in the build output, and Image Fallback stands in for one that goes missing.
+    link: /plugins/#images
+    linkText: Image plugins
   - icon:
       light: /icons/terminal-light.svg
       dark: /icons/terminal-dark.svg
@@ -109,23 +82,9 @@ features:
 - **Want a tool for your terminal?** Pick one on the [apps page](/apps/). Each installs with one Homebrew command.
 - **Building a site like this one?** Read [how this site works](/guide/how-this-site-works) and copy what is useful.
 
-## Install the whole VitePress toolkit
-
-```sh
-npm install --save-dev \
-  @binarynoir/vitepress-auto-sidebar \
-  @binarynoir/vitepress-auto-navbar \
-  @binarynoir/vitepress-markdown-tags \
-  @binarynoir/vitepress-reading-time-tag \
-  @binarynoir/vitepress-downloads \
-  @binarynoir/vitepress-html-escape \
-  @binarynoir/vitepress-broken-links \
-  @binarynoir/vite-plugin-optimize-images \
-  @binarynoir/vite-plugin-image-fallback \
-  markdown-it-glossary
-```
+## Install the VitePress toolkit
 
-Every plugin is optional and independent. Take one, or take them all. Each plugin's page shows how to register it, and the VitePress plugins need Node 22 or newer.
+Every plugin is optional and independent: take one, or take them all. The [plugins overview](/plugins/#install-them-all) has the one-line install for the whole set, and each plugin's page shows how to register it. The VitePress plugins need Node 22 or newer.
 
 ## Support the work
 

docs/plugins/.sidebar

@@ -1,13 +1,21 @@
 # Titles are set here, not in each page's H1, so the ((tag|...)) badges in the
 # headings stay out of the menu. The navbar reuses these titles automatically.
+# [Group] lines match the groups on the home page and the plugins overview.
 index.md:Overview
+[Navigation from your folders]
 auto-sidebar.md:Auto Sidebar
 auto-navbar.md:Auto Navbar
+[Richer pages]
 markdown-tags:Markdown Tags
+glossary:Glossary Tooltips
 reading-time-tag.md:Reading Time Tag
+[Content where it lives]
 downloads.md:Downloads
-glossary:Glossary Tooltips
+exclude:Exclude
+readme-index:README Index
+[Builds that don't break]
 html-escape:HTML Escape
 broken-links.md:Broken Links
+[Images handled]
 optimize-images.md:Optimize Images
 image-fallback.md:Image Fallback

docs/plugins/exclude/.exclude

@@ -0,0 +1,3 @@
+# Demo for the Exclude plugin: draft.md stays in the repository but is not built,
+# and Auto Sidebar leaves it out of the menu.
+draft.md

docs/plugins/exclude/draft.md

@@ -0,0 +1,7 @@
+---
+title: Draft
+---
+
+# Draft
+
+This page is the live demo for [Exclude](./index.md). It is listed in this folder's `.exclude` file, so it is never built: if you are reading this on the site, the plugin is not working.

docs/plugins/exclude/index.md

@@ -0,0 +1,110 @@
+---
+title: Exclude
+---
+
+# Exclude ((tag|VitePress plugin|blue))
+
+[[readingTime]]
+
+[![GitHub repo](https://img.shields.io/badge/GitHub-binarynoir%2Fvitepress--exclude-181717?logo=github)](https://github.com/binarynoir/vitepress-exclude) [![npm version](https://img.shields.io/npm/v/@binarynoir/vitepress-exclude)](https://www.npmjs.com/package/@binarynoir/vitepress-exclude) [![CI](https://img.shields.io/github/actions/workflow/status/binarynoir/vitepress-exclude/ci.yml?branch=main&label=CI)](https://github.com/binarynoir/vitepress-exclude/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/binarynoir/vitepress-exclude)](https://github.com/binarynoir/vitepress-exclude/blob/main/LICENSE)
+
+`@binarynoir/vitepress-exclude` keeps pages out of the build with a `.exclude` file in the folder that holds them. VitePress's own `srcExclude` is one list of globs in `config.mts`, far from the pages it hides. With this plugin, each folder says what to leave out, next to the files themselves.
+
+```txt
+docs/guide/
+  .exclude
+  index.md
+  draft.md
+  internal-notes.md
+  drafts/
+```
+
+```txt
+# docs/guide/.exclude
+draft.md
+internal-*.md
+drafts/
+```
+
+Those pages are not built, not in search and not in the sitemap. The files stay where they are.
+
+## See it live
+
+This page's folder has a [`draft.md`](https://github.com/binarynoir/binarynoir.github.io/blob/main/docs/plugins/exclude/draft.md) next to it, and an [`.exclude`](https://github.com/binarynoir/binarynoir.github.io/blob/main/docs/plugins/exclude/.exclude) file that lists it. The draft is in the repository, but it is not on this site: it is missing from the sidebar, from search and from the build.
+
+[Auto Sidebar](/plugins/auto-sidebar) and [Auto Navbar](/plugins/auto-navbar) read the same `.exclude` files, so one line hides a page from the menus and keeps it out of the build.
+
+## Install
+
+```sh
+npm install --save-dev @binarynoir/vitepress-exclude
+```
+
+## Use
+
+Wrap the config with `withExclude` and pass it the docs source directory:
+
+```ts
+// .vitepress/config.mts
+import path from 'node:path';
+import { defineConfig } from 'vitepress';
+import { withExclude } from '@binarynoir/vitepress-exclude/vitepress';
+
+export default withExclude(
+  defineConfig({
+    // ...your config
+  }),
+  path.resolve(import.meta.dirname, '..'),
+);
+```
+
+`withExclude` keeps your existing `srcExclude` and `vite.plugins`, so it composes with other wrappers in any order.
+
+Or wire the two pieces by hand, as this site does to combine them with [Downloads](/plugins/downloads):
+
+```ts
+import { excludeSrc, excludeVitePlugin } from '@binarynoir/vitepress-exclude';
+
+const docsRoot = path.resolve(import.meta.dirname, '..');
+
+export default defineConfig({
+  srcExclude: [...excludeSrc(docsRoot), '**/_snippets/**'],
+  vite: {
+    plugins: [excludeVitePlugin()],
+  },
+});
+```
+
+## `.exclude` files
+
+One rule per line. Blank lines and lines starting with `#` are ignored. Rules are relative to the folder the `.exclude` file is in, and a `.exclude` file in the docs root works too.
+
+| Rule             | Excludes                                                      |
+| ---------------- | ------------------------------------------------------------- |
+| `draft.md`       | That file. A name without a `/` also matches a folder.        |
+| `drafts/`        | That folder and everything in it.                             |
+| `internal-*.md`  | Matching files in this folder. `*` and `?` stay in one level. |
+| `**/internal.md` | Matching files in this folder or any folder below it.         |
+| `.`              | The whole folder the `.exclude` file is in.                   |
+
+Two kinds of rule are skipped, with a warning in the log:
+
+- `!keep.md`: VitePress cannot re-include a file that another rule excluded.
+- `../other.md`: a rule cannot reach outside its own folder. Put a `.exclude` file in that folder instead.
+
+## Options
+
+| Option             | Default        | Description                                                |
+| ------------------ | -------------- | ---------------------------------------------------------- |
+| `excludeFilenames` | `[".exclude"]` | Filenames read in each folder.                             |
+| `verbose`          | `false`        | Log each `.exclude` file, its rules and the globs it made. |
+
+`withExclude(config, srcDir, options)` and `excludeSrc(srcDir, options)` take both. `excludeVitePlugin(options)` takes `excludeFilenames`; pass it the same list.
+
+## Good to know
+
+- **Live in `vitepress dev`.** Add, change or delete a `.exclude` file and the dev server restarts with the new rules. The rules are read when the config loads, so the plugin registers each `.exclude` file as part of the config.
+- **Hidden folders are skipped.** `.vitepress`, `node_modules` and other folders whose names start with `.` are not searched. VitePress never builds pages from them.
+- **Excluded is not secret.** An excluded file is not published, but it is still in your repository.
+
+[Source and full README on GitHub](https://github.com/binarynoir/vitepress-exclude)