docs: document titleCase option and upgrade auto-sidebar / auto-navbar

Author: jsmith3rd

docs/plugins/auto-navbar.md

@@ -56,6 +56,7 @@ Each top-level folder becomes a navbar entry: a dropdown if it has several pages
 | `flattenSinglePage` | `true`         | A folder with one entry becomes a plain link.                         |
 | `activeMatch`       | `true`         | Keep items highlighted on every page beneath them.                    |
 | `titleReplacements` | `{}`           | Words to replace in titles made from file and folder names.           |
+| `titleCase`         | `true`         | Title-case titles made from file and folder names.                    |
 | `stripTags`         | `true`         | Remove Markdown Tags syntax (`((tag\|draft))`) from titles.           |
 | `transformTitle`    | none           | A function that gets every title before truncation.                   |
 | `verbose`           | `false`        | Log each folder as it is processed.                                   |
@@ -68,7 +69,9 @@ A folder's landing page is its `index.md`, or its `README.md`. VitePress serves
 
 This site passes the same title options to both menus. See them working in the [Sidebar Titles Demo](/plugins/auto-sidebar/titles-demo/), and in this site's [config](https://github.com/binarynoir/binarynoir.github.io/blob/main/docs/.vitepress/config.mts).
 
-A title made from a file or folder name is formatted: `getting-started.md` becomes "Getting Started". Only first letters are capitalised, so use `titleReplacements` for words with other casing. Keys match whole words, ignoring case:
+A title made from a file or folder name is formatted: `getting-started.md` becomes "Getting Started". It is title-cased, so articles, short conjunctions and prepositions (`a`, `the`, `and`, `of`, `to`, …) stay lowercase unless they are the first or last word: `guide-to-the-cli.md` becomes "Guide to the Cli". Set `titleCase: false` to capitalise every word instead.
+
+Only first letters change case, so use `titleReplacements` for words with other casing. Keys match whole words, ignoring case:
 
 ```ts
 generateNav(docsRoot, {

docs/plugins/auto-sidebar/index.md

@@ -72,6 +72,7 @@ Files need their `.md` extension in these lines. A `.exclude` file removes draft
 | `collapsed`           | `false`        | Initial collapsed state for section headers.                          |
 | `flattenSinglePage`   | `true`         | A folder with one page becomes a plain link instead of its own group. |
 | `titleReplacements`   | `{}`           | Words to replace in titles made from file and folder names.           |
+| `titleCase`           | `true`         | Title-case titles made from file and folder names.                    |
 | `stripTags`           | `true`         | Remove Markdown Tags syntax (`((tag\|draft))`) from titles.           |
 | `transformTitle`      | none           | A function that gets every title before truncation.                   |
 | `groupTitleFromIndex` | `false`        | Label a folder's group with its landing page's title.                 |
@@ -83,7 +84,9 @@ Files need their `.md` extension in these lines. A `.exclude` file removes draft
 The [Sidebar Titles Demo](./titles-demo/) folder, in the sidebar under **Auto Sidebar**, uses each option below on this site's real sidebar.
 :::
 
-A title made from a file or folder name is formatted: `getting-started.md` becomes "Getting Started". Only first letters are capitalised, so use `titleReplacements` for words with other casing. Keys match whole words, ignoring case:
+A title made from a file or folder name is formatted: `getting-started.md` becomes "Getting Started". It is title-cased, so articles, short conjunctions and prepositions (`a`, `the`, `and`, `of`, `to`, …) stay lowercase unless they are the first or last word: `guide-to-the-cli.md` becomes "Guide to the Cli". Set `titleCase: false` to capitalise every word instead.
+
+Only first letters change case, so use `titleReplacements` for words with other casing. Keys match whole words, ignoring case:
 
 ```ts
 generateSidebar(docsRoot, {

docs/plugins/auto-sidebar/titles-demo/.sidebar

@@ -3,6 +3,7 @@
 # after a space.
 index.md
 github-actions-setup.md
+guide-to-the-cli.md
 draft-notes.md
 example-renamed-page.md
 https://vitepress.dev: 'VitePress docs'

docs/plugins/auto-sidebar/titles-demo/guide-to-the-cli.md

@@ -0,0 +1,13 @@
+This page has no `title` frontmatter and no `# Heading`, so [Auto Sidebar](/plugins/auto-sidebar/) titles it from its file name, `guide-to-the-cli.md`.
+
+## With `titleCase`
+
+`titleCase` is on by default. Articles, short conjunctions and prepositions such as `a`, `the`, `and`, `of` and `to` stay lowercase unless they are the first or last word, so the sidebar shows **Guide to the Cli**.
+
+## Without `titleCase`
+
+With `titleCase: false`, every word is capitalised: "Guide To The Cli".
+
+Only first letters change case, so "Cli" stays "Cli". Add `{ cli: 'CLI' }` to `titleReplacements` to write it as "CLI". Titles an author wrote are never re-cased.
+
+[Back to the demo](./)

docs/plugins/auto-sidebar/titles-demo/index.md

@@ -23,6 +23,7 @@ generateSidebar(docsRoot, {
 | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Sidebar Titles Demo**, the group label       | This page's `title`, with `groupTitleFromIndex`. The folder is `titles-demo`, and its parent `.sidebar` doesn't name it, so without the option the label would be "Titles Demo".                                        |
 | [GitHub Actions Setup](./github-actions-setup) | The file name `github-actions-setup.md`, since the page has no title or `# Heading`. `titleReplacements` turns "Github" into "GitHub".                                                                                  |
+| [Guide to the Cli](./guide-to-the-cli)         | The file name `guide-to-the-cli.md`. `titleCase` (on by default) keeps "to" and "the" lowercase mid-title.                                                                                                              |
 | [Draft notes](./draft-notes)                   | The page's heading, `# Draft notes ((tag\|draft\|orange))`. `stripTags` (on by default) removes the tag from the sidebar, and the page still shows the badge.                                                           |
 | [Renamed page](./example-renamed-page)         | The page's heading, `# Example: Renamed page`. `transformTitle` removes the "Example: " prefix from page titles.                                                                                                        |
 | [VitePress docs](https://vitepress.dev)        | The `.sidebar` line `https://vitepress.dev: 'VitePress docs'`. A single-quoted title after a space works, and so does a double-quoted one. A line that can't be parsed logs a warning naming the file and line instead. |

package-lock.json

@@ -24,8 +24,8 @@
   "devDependencies": {
     "@binarynoir/vite-plugin-image-fallback": "^0.4.0",
     "@binarynoir/vite-plugin-optimize-images": "^0.1.9",
-    "@binarynoir/vitepress-auto-navbar": "^0.4.1",
-    "@binarynoir/vitepress-auto-sidebar": "^0.6.1",
+    "@binarynoir/vitepress-auto-navbar": "^0.5.0",
+    "@binarynoir/vitepress-auto-sidebar": "^0.7.0",
     "@binarynoir/vitepress-broken-links": "^0.1.2",
     "@binarynoir/vitepress-downloads": "^0.1.3",
     "@binarynoir/vitepress-exclude": "^0.1.1",