feat: excluded pages (#22)

.changeset/light-candles-divide.md

@@ -0,0 +1,9 @@
+---
+'starlight-sidebar-topics': minor
+---
+
+Adds a new [`exclude`](https://starlight-sidebar-topics.netlify.app/docs/configuration#exclude) plugin configuration option to exclude pages from any topic.
+
+This options can be useful for custom pages that use a custom site navigation sidebar which do not belong to any topic. Excluded pages will use the built-in Starlight sidebar and not render a list of topics.
+
+See the [“Excluded Pages”](https://starlight-sidebar-topics.netlify.app/docs/guides/excluded-pages) guide to learn more about how to exclude content pages from any topic.

docs/astro.config.ts

@@ -11,44 +11,49 @@ export default defineConfig({
         baseUrl: 'https://github.com/HiDeoo/starlight-sidebar-topics/edit/main/docs/',
       },
       plugins: [
-        starlightSidebarTopics([
-          {
-            label: 'Documentation',
-            link: '/docs/getting-started/',
-            icon: 'open-book',
-            items: [
-              { label: 'Start Here', items: ['docs/getting-started', 'docs/configuration'] },
-              { label: 'Guides', autogenerate: { directory: 'docs/guides' } },
-              { label: 'Resources', items: [{ label: 'Plugins and Tools', slug: 'docs/resources/starlight' }] },
-            ],
-          },
-          {
-            id: 'demo',
-            label: {
-              en: 'Demo',
-              fr: 'Démo',
+        starlightSidebarTopics(
+          [
+            {
+              label: 'Documentation',
+              link: '/docs/getting-started/',
+              icon: 'open-book',
+              items: [
+                { label: 'Start Here', items: ['docs/getting-started', 'docs/configuration'] },
+                { label: 'Guides', autogenerate: { directory: 'docs/guides' } },
+                { label: 'Resources', items: [{ label: 'Plugins and Tools', slug: 'docs/resources/starlight' }] },
+              ],
             },
-            link: '/demo/',
-            icon: 'puzzle',
-            items: [
-              { label: 'API', autogenerate: { directory: 'demo/api' } },
-              { label: 'Components', autogenerate: { directory: 'demo/components' } },
-              { label: 'Commands', autogenerate: { directory: 'demo/commands' }, collapsed: true },
-            ],
-            badge: {
-              text: {
-                en: 'Stub',
-                fr: 'Ébauche',
+            {
+              id: 'demo',
+              label: {
+                en: 'Demo',
+                fr: 'Démo',
+              },
+              link: '/demo/',
+              icon: 'puzzle',
+              items: [
+                { label: 'API', autogenerate: { directory: 'demo/api' } },
+                { label: 'Components', autogenerate: { directory: 'demo/components' } },
+                { label: 'Commands', autogenerate: { directory: 'demo/commands' }, collapsed: true },
+              ],
+              badge: {
+                text: {
+                  en: 'Stub',
+                  fr: 'Ébauche',
+                },
+                variant: 'caution',
               },
-              variant: 'caution',
             },
-          },
+            {
+              label: 'Starlight Docs',
+              link: 'https://starlight.astro.build/',
+              icon: 'starlight',
+            },
+          ],
           {
-            label: 'Starlight Docs',
-            link: 'https://starlight.astro.build/',
-            icon: 'starlight',
+            exclude: ['/demo/excluded/**/*', '/*/demo/excluded/**/*'],
           },
-        ]),
+        ),
       ],
       social: {
         blueSky: 'https://bsky.app/profile/hideoo.dev',

docs/src/content/docs/demo/excluded/page.mdx

@@ -0,0 +1,13 @@
+---
+title: Excluded with sidebar
+pagefind: false
+---
+
+This page is not listed in any topic sidebar configuration, is not associated any topic through the `topic` frontmatter field, and is also excluded in the plugin configuration.
+
+See the [“Excluded Pages”](/docs/guides/excluded-pages) guide to learn how to exclude content pages from any topic.
+
+:::note
+This page exists solely for demonstration purposes and contains no useful information.
+See the Starlight Sidebar Topics plugin [documentation](/docs/getting-started/) for more information.
+:::

docs/src/content/docs/demo/excluded/splash.mdx

@@ -0,0 +1,11 @@
+---
+title: Excluded without sidebar
+pagefind: false
+---
+
+This page using the `splash` template is not listed in any topic sidebar configuration, is not associated with any topic through the `topic` frontmatter field, and is also excluded in the plugin configuration.
+
+:::note
+This page exists solely for demonstration purposes and contains no useful information.
+See the Starlight Sidebar Topics plugin [documentation](/docs/getting-started/) for more information.
+:::

docs/src/content/docs/demo/secrets/page.mdx → docs/src/content/docs/demo/unlisted/page.mdx

@@ -1,5 +1,5 @@
 ---
-title: Secrets with sidebar
+title: Unlisted with sidebar
 topic: demo
 pagefind: false
 ---

docs/src/content/docs/demo/secrets/splash.mdx → docs/src/content/docs/demo/unlisted/splash.mdx

@@ -1,5 +1,5 @@
 ---
-title: Secrets without sidebar
+title: Unlisted without sidebar
 template: splash
 pagefind: false
 ---

docs/src/content/docs/docs/configuration.mdx

@@ -5,7 +5,7 @@ description: An overview of the configuration options supported by the Starlight
 
 The Starlight Sidebar Topics can be configured inside the `astro.config.mjs` configuration file of your project:
 
-```js {12}
+```js {13,16}
 // astro.config.mjs
 // @ts-check
 import starlight from '@astrojs/starlight'
@@ -16,9 +16,14 @@ export default defineConfig({
   integrations: [
     starlight({
       plugins: [
-        starlightSidebarTopics([
-          // Topics configuration goes here.
-        ]),
+        starlightSidebarTopics(
+          [
+            // Topics configuration goes here.
+          ],
+          {
+            // Plugin configuration goes here (optional).
+          },
+        ),
       ],
       title: 'My Docs',
     }),
@@ -180,3 +185,42 @@ starlightSidebarTopics([
   },
 ])
 ```
+
+## Plugin configuration
+
+The Starlight Sidebar Topics plugin accepts an optional configuration object as the second argument.
+
+The configuration object can be used to customize the plugin global behavior and the following options are available:
+
+### `exclude`
+
+**type:** `string[]`  
+**default:** `[]`
+
+A list of pages or [glob patterns](https://github.com/micromatch/picomatch#globbing-features) that should be excluded from any topic.
+
+This options can be useful for [custom pages](https://starlight.astro.build/guides/pages/#custom-pages) that use a [custom site navigation sidebar](https://starlight.astro.build/guides/pages/#sidebar) which do not belong to any topic.
+Excluded pages will use the built-in Starlight sidebar and not render a list of topics.
+
+The following example excludes all pages under the `/blog` directory from any topic:
+
+```js {10}
+starlightSidebarTopics(
+  [
+    {
+      label: 'Guides',
+      link: '/guides/',
+      items: ['guides/concepts', 'guides/courses'],
+    },
+  ],
+  {
+    exclude: ['/blog', '/blog/**/*'],
+  },
+)
+```
+
+See the [“Excluded Pages”](/docs/guides/excluded-pages) guide to learn how to exclude content pages from any topic.
+
+:::tip
+You can use this [webpage](https://www.digitalocean.com/community/tools/glob) to generate and test glob patterns.
+:::

docs/src/content/docs/docs/getting-started.mdx

@@ -78,4 +78,4 @@ import { PackageManagers } from '@hideoo/starlight-plugins-docs-components'
 
 </Steps>
 
-The Starlight Sidebar Topics plugin behavior can be tweaked using various [topic configuration options](/docs/configuration/#topic-configuration).
+The Starlight Sidebar Topics plugin behavior can be tweaked using various [configuration options](/docs/configuration/).

docs/src/content/docs/docs/guides/excluded-pages.mdx

@@ -0,0 +1,82 @@
+---
+title: Excluded Pages
+description: Learn how to exclude content pages from any topic.
+---
+
+By default, the Starlight Sidebar Topics plugin expect that every pages in your project is associated with a topic.
+This is done by including the page in a [topic sidebar configuration](/docs/configuration#items) or using the `topic` frontmatter field for [unlisted pages](/docs/guides/unlisted-pages/).
+
+However, there are cases where you may have [custom pages](https://starlight.astro.build/guides/pages/#custom-pages) that use a [custom site navigation sidebar](https://starlight.astro.build/guides/pages/#sidebar) which do not belong to any topic.
+Excluding these pages from any topic will prevent the plugin from rendering a list of topics in the sidebar and use the built-in Starlight sidebar instead.
+
+## Exclude pages
+
+To exclude some pages from any topic, you can use the [`exclude`](/docs/configuration#exclude) plugin configuration option.
+
+```js {20}
+// astro.config.mjs
+// @ts-check
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import starlightSidebarTopics from 'starlight-sidebar-topics'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightSidebarTopics(
+          [
+            {
+              label: 'Guides',
+              link: '/guides/',
+              items: ['guides/concepts', 'guides/courses'],
+            },
+          ],
+          {
+            exclude: ['/changelog', '/changelog/**/*'],
+          },
+        ),
+      ],
+      title: 'My Docs',
+    }),
+  ],
+})
+```
+
+For example, given the above configuration and following file structure:
+
+import { FileTree } from '@astrojs/starlight/components'
+
+<FileTree>
+
+- src/
+  - content/
+    - docs/
+      - guides/
+        - concepts.md
+        - courses.md
+  - pages/
+    - changelog.astro
+    - …
+
+</FileTree>
+
+And the `changelog.astro` page content rendering the following custom page with a custom site navigation sidebar:
+
+```astro title="src/pages/changelog.astro" {3-7}
+<StarlightPage
+  frontmatter={{ title: 'Changelog' }}
+  sidebar={[
+    { label: 'v3.0.0', link: '/changelog/v3-0-0/' },
+    { label: 'v2.0.0', link: '/changelog/v2-0-0/' },
+    { label: 'v1.0.0', link: '/changelog/v1-0-0/' },
+  ]}
+>
+  …
+</StarlightPage>
+```
+
+Visiting the `guides/concepts` and `guides/courses` pages will display the sidebar of the "Guides" topic while the `changelog` page will use the custom site navigation sidebar defined in the `changelog.astro` page using the built-in Starlight sidebar.
+
+- `guides/concepts` and `guides/courses` are explicitly listed in the "Guides" topic sidebar configuration under the [`items`](/docs/configuration#items) key.
+- `changelog` is excluded from any topic using the [`exclude`](/docs/configuration#exclude) plugin configuration option.

docs/src/content/docs/docs/guides/unlisted-pages.mdx

@@ -1,6 +1,8 @@
 ---
 title: Unlisted Pages
 description: Learn how to associate content pages that are not listed in any topic sidebar configuration with a specific topic.
+sidebar:
+  order: 1
 ---
 
 By default, the Starlight Sidebar Topics plugin expect that every [content pages](https://starlight.astro.build/guides/pages/#content-pages) in your project is associated with a topic.

docs/src/pages/demo/excluded/custom-no-sidebar.astro

@@ -0,0 +1,16 @@
+---
+import { Aside } from '@astrojs/starlight/components'
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
+---
+
+<StarlightPage frontmatter={{ title: 'Custom - Excluded without sidebar' }} sidebar={[]} hasSidebar={false}>
+  <p>
+    This custom page with <code>hasSidebar</code> set to <code>false</code> is not listed in any topic sidebar configuration,
+    is not associated with any topic through the <code>topic</code> frontmatter field, and is also excluded in the plugin
+    configuration.
+  </p>
+  <Aside>
+    This page exists solely for demonstration purposes and contains no useful information. See the Starlight Sidebar
+    Topics plugin <a href="/docs/getting-started/">documentation</a> for more information.
+  </Aside>
+</StarlightPage>

docs/src/pages/demo/excluded/custom-page.astro

@@ -0,0 +1,29 @@
+---
+import { Aside } from '@astrojs/starlight/components'
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
+---
+
+<StarlightPage
+  frontmatter={{ title: 'Custom - Excluded without sidebar' }}
+  sidebar={[
+    { label: 'Home', link: '/' },
+    {
+      label: 'Start Here',
+      items: ['docs/getting-started', 'docs/configuration'],
+    },
+    { label: 'Demo', link: '/demo/' },
+  ]}
+>
+  <p>
+    This custom page with a custom <code>sidebar</code> is not listed in any topic sidebar configuration, is not associated
+    with any topic through the <code>topic</code> frontmatter field, and is also excluded in the plugin configuration.
+  </p>
+  <p>
+    See the <a href="/docs/guides/excluded-pages/">“Excluded Pages”</a> guide to learn how to exclude content pages from
+    any topic.
+  </p>
+  <Aside>
+    This page exists solely for demonstration purposes and contains no useful information. See the Starlight Sidebar
+    Topics plugin <a href="/docs/getting-started/">documentation</a> for more information.
+  </Aside>
+</StarlightPage>

docs/src/pages/demo/excluded/custom-splash.astro

@@ -0,0 +1,15 @@
+---
+import { Aside } from '@astrojs/starlight/components'
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
+---
+
+<StarlightPage frontmatter={{ title: 'Custom - Excluded without sidebar', template: 'splash' }}>
+  <p>
+    This custom page using the <code>splash</code> template is not listed in any topic sidebar configuration, is not associated
+    with any topic through the <code>topic</code> frontmatter field, and is also excluded in the plugin configuration.
+  </p>
+  <Aside>
+    This page exists solely for demonstration purposes and contains no useful information. See the Starlight Sidebar
+    Topics plugin <a href="/docs/getting-started/">documentation</a> for more information.
+  </Aside>
+</StarlightPage>

docs/src/pages/demo/secrets/custom-no-sidebar.astro → docs/src/pages/demo/unlisted/custom-no-sidebar.astro

@@ -3,7 +3,7 @@ import { Aside } from '@astrojs/starlight/components'
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
 ---
 
-<StarlightPage frontmatter={{ title: 'Custom - Secrets without sidebar' }} sidebar={[]} hasSidebar={false}>
+<StarlightPage frontmatter={{ title: 'Custom - Unlisted without sidebar' }} sidebar={[]} hasSidebar={false}>
   <p>
     This custom page with <code>hasSidebar</code> set to <code>false</code> is not listed in any topic sidebar configuration
     and is not associated with any topic through the <code>topic</code> frontmatter field.

docs/src/pages/demo/secrets/custom-page.astro → docs/src/pages/demo/unlisted/custom-page.astro

@@ -3,7 +3,7 @@ import { Aside } from '@astrojs/starlight/components'
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
 ---
 
-<StarlightPage frontmatter={{ title: 'Custom - Secrets without sidebar', topic: 'demo' }}>
+<StarlightPage frontmatter={{ title: 'Custom - Unlisted without sidebar', topic: 'demo' }}>
   <p>
     This custom page is not listed in any topic sidebar configuration but is associated with the "Demo" topic through
     the <code>topic: demo</code> frontmatter entry.

docs/src/pages/demo/secrets/custom-splash.astro → docs/src/pages/demo/unlisted/custom-splash.astro

@@ -3,7 +3,7 @@ import { Aside } from '@astrojs/starlight/components'
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
 ---
 
-<StarlightPage frontmatter={{ title: 'Custom - Secrets without sidebar', template: 'splash' }}>
+<StarlightPage frontmatter={{ title: 'Custom - Unlisted without sidebar', template: 'splash' }}>
   <p>
     This custom page using the <code>splash</code> template is not listed in any topic sidebar configuration and is not associated
     with any topic through the <code>topic</code> frontmatter field.