feat(docs): add HTML Escape plugin and nest glossary demo pages

Author: kryptonianson

README.md

@@ -6,16 +6,17 @@ It documents BinaryNoir's open-source VitePress plugins, Vite plugins and comman
 
 ## Plugins demonstrated
 
-| Package                                                                                                | Role on this site                                                    |
-| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| [`@binarynoir/vitepress-auto-sidebar`](https://github.com/binarynoir/vitepress-auto-sidebar)           | Builds the sidebar from the folder tree                              |
-| [`@binarynoir/vitepress-auto-navbar`](https://github.com/binarynoir/vitepress-auto-navbar)             | Builds the top navbar from the folder tree                           |
-| [`@binarynoir/vitepress-markdown-tags`](https://github.com/binarynoir/vitepress-markdown-tags)         | Status badges and tagged-page lists                                  |
-| [`@binarynoir/vitepress-reading-time-tag`](https://github.com/binarynoir/vitepress-reading-time-tag)   | `[[readingTime]]` tip blocks                                         |
-| [`@binarynoir/vitepress-downloads`](https://github.com/binarynoir/vitepress-downloads)                 | Downloadable files from a `downloads` folder (not yet wired in here) |
-| [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary)                           | Hover definitions from `docs/reference/glossary.md`                  |
-| [`@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)           |
+| Package                                                                                                | Role on this site                                          |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| [`@binarynoir/vitepress-auto-sidebar`](https://github.com/binarynoir/vitepress-auto-sidebar)           | Builds the sidebar from the folder tree                    |
+| [`@binarynoir/vitepress-auto-navbar`](https://github.com/binarynoir/vitepress-auto-navbar)             | Builds the top navbar from the folder tree                 |
+| [`@binarynoir/vitepress-markdown-tags`](https://github.com/binarynoir/vitepress-markdown-tags)         | Status badges and tagged-page lists                        |
+| [`@binarynoir/vitepress-reading-time-tag`](https://github.com/binarynoir/vitepress-reading-time-tag)   | `[[readingTime]]` tip blocks                               |
+| [`@binarynoir/vitepress-downloads`](https://github.com/binarynoir/vitepress-downloads)                 | Downloadable files from a `downloads` folder               |
+| [`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 |
+| [`@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) |
 
 ## Develop
 

docs/.vitepress/config.mts

@@ -10,6 +10,7 @@ import { imageFallbackPlugin } from '@binarynoir/vite-plugin-image-fallback';
 import { optimizeImagesPlugin } from '@binarynoir/vite-plugin-optimize-images';
 import { downloadsMarkdown, downloadsVitePlugin } from '@binarynoir/vitepress-downloads';
 import { downloadsSrcExclude } from '@binarynoir/vitepress-downloads/vitepress';
+import { markdownHtmlEscape } from '@binarynoir/vitepress-html-escape';
 
 // import.meta.dirname, not __dirname: VitePress configs are ESM.
 const docsRoot = path.resolve(import.meta.dirname, '..');
@@ -99,7 +100,7 @@ export default defineConfig({
       md.use(glossaryAbbr, {
         file: path.join(docsRoot, 'reference/glossary.md'),
         root: docsRoot,
-        // Not the default `glossary.md`: docs/plugins/glossary.md is a documentation page, not a glossary.
+        // Not the default `glossary.md`, so a page with that name is never read as a section glossary.
         scopedFile: 'section-glossary.md',
       });
       // @binarynoir/vitepress-reading-time-tag: [[readingTime]] becomes a tip block.
@@ -108,6 +109,9 @@ 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-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.
+      md.use(markdownHtmlEscape);
     },
   },
 

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

@@ -6,7 +6,7 @@ title: How this site works
 
 [[readingTime]]
 
-This site is plain VitePress 2 plus seven 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 nine 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
 
@@ -34,7 +34,9 @@ docs/
 | Left sidebar                    | [Auto Sidebar](/plugins/auto-sidebar)         | `themeConfig.sidebar` in `config.mts` |
 | Status badges                   | [Markdown Tags](/plugins/markdown-tags/)      | `markdown.config`, plus the theme     |
 | "Reading time" box              | [Reading Time Tag](/plugins/reading-time-tag) | `markdown.config`                     |
-| Dotted-underline hovers         | [Glossary Tooltips](/plugins/glossary)        | `markdown.config`                     |
+| Dotted-underline hovers         | [Glossary Tooltips](/plugins/glossary/)       | `markdown.config`                     |
+| File download links             | [Downloads](/plugins/downloads)               | `markdown.config` and `vite.plugins`  |
+| Stray `<tags>` shown as text    | [HTML Escape](/plugins/html-escape/)          | `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

@@ -90,6 +90,7 @@ npm install --save-dev \
   @binarynoir/vitepress-auto-navbar \
   @binarynoir/vitepress-markdown-tags \
   @binarynoir/vitepress-reading-time-tag \
+  @binarynoir/vitepress-html-escape \
   markdown-it-glossary
 ```
 

docs/plugins/.nav

@@ -3,9 +3,10 @@
 index.md:Overview
 auto-sidebar.md:Auto Sidebar
 auto-navbar.md:Auto Navbar
-markdown-tags.md:Markdown Tags
+markdown-tags:Markdown Tags
 reading-time-tag.md:Reading Time Tag
 downloads.md:Downloads
-glossary.md:Glossary Tooltips
+glossary:Glossary Tooltips
+html-escape:HTML Escape
 optimize-images.md:Optimize Images
 image-fallback.md:Image Fallback

docs/plugins/.sidebar

@@ -0,0 +1,2 @@
+index.md:Overview
+section-demo:Section Glossary Demo

docs/plugins/glossary/.sidebar

@@ -107,7 +107,7 @@ docs/
 └─ team-b/index.md
 ```
 
-See it working on the [live section glossary demo](/plugins/glossary-demo/).
+See it working on the [live section glossary demo](/plugins/glossary/section-demo/).
 
 To apply a section glossary to the whole site instead, set `glossary-scope: site` in that file's frontmatter. Section glossaries are found when the config loads, so adding or editing one needs a dev-server restart.
 

docs/plugins/glossary.md docs/plugins/glossary/index.mddocs/plugins/glossary.md renamed to docs/plugins/glossary/index.md

@@ -0,0 +1,2 @@
+# The glossary file holds this folder's terms; it is linked from the demo, not listed.
+-section-glossary.md

docs/plugins/glossary/section-demo/.sidebar

@@ -4,10 +4,10 @@ title: Section Glossary Demo
 
 # Section Glossary Demo
 
-A live example of [section glossaries](/plugins/glossary#section-glossaries). This folder has its own [glossary file](/plugins/glossary-demo/section-glossary), so its terms apply to this page and nowhere else on the site. Hover, click or tap a dotted word to read it.
+A live example of [section glossaries](/plugins/glossary/#section-glossaries). This folder has its own [glossary file](/plugins/glossary/section-demo/section-glossary), so its terms apply to this page and nowhere else on the site. Hover, click or tap a dotted word to read it.
 
 - **Gizmo** exists only in this folder's glossary.
 - **CI** is defined by both this folder's glossary and the site's master glossary. The closer one wins, so you see the demo's definition here.
 - **CLI** is defined only by the master glossary, so it still works. A section glossary adds to the master; it doesn't replace it.
 
-On the [plugin page](/plugins/glossary), CI shows the master's definition and Gizmo has no tooltip.
+On the [plugin page](/plugins/glossary/), CI shows the master's definition and Gizmo has no tooltip.