Merge pull request #9 from trueberryless-org/docs

Write documentation

.changeset/cuddly-nails-change.md

@@ -0,0 +1,5 @@
+---
+"starlight-spell-checker-docs": minor
+---
+
+Write initial documentation

docs/astro.config.ts

@@ -1,6 +1,7 @@
 import starlight from "@astrojs/starlight";
 import { defineConfig } from "astro/config";
 import starlightSpellChecker from "starlight-spell-checker";
+import starlightPluginsDocsComponents from "@trueberryless-org/starlight-plugins-docs-components";
 
 export default defineConfig({
   integrations: [
@@ -9,33 +10,32 @@ export default defineConfig({
         baseUrl:
           "https://github.com/trueberryless-org/starlight-spell-checker/edit/main/docs/",
       },
-      locales: {
-        root: {
-          lang: "en",
-          label: "English",
-        },
-        de: {
-          lang: "de",
-          label: "Deutsch",
-        },
+      logo: {
+        light: "./src/assets/logo-light.png",
+        dark: "./src/assets/logo-dark.png",
+        replacesTitle: true,
       },
+      defaultLocale: "en",
       plugins: [
-        starlightSpellChecker({
-          spell: {
-            ignore: ["astro.config.mjs"],
-          },
+        starlightSpellChecker(),
+        starlightPluginsDocsComponents({
+          pluginName: "starlight-spell-checker",
         }),
       ],
       sidebar: [
         {
           label: "Start Here",
-          items: [{ slug: "getting-started" }],
+          items: [{ slug: "getting-started" }, { slug: "configuration" }],
+        },
+        {
+          label: "Guides",
+          items: [{ slug: "conditional-validation" }],
         },
       ],
       social: {
         github: "https://github.com/trueberryless-org/starlight-spell-checker",
       },
-      title: "starlight-spell-checker",
+      title: "Starlight Spell Checker",
     }),
   ],
 });

docs/package.json

@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "@astrojs/starlight": "^0.30.3",
+    "@trueberryless-org/starlight-plugins-docs-components": "^0.3.0",
     "astro": "^5.1.2",
     "sharp": "^0.33.5",
     "starlight-spell-checker": "workspace:*"

docs/src/content/docs/conditional-validation.mdx

@@ -0,0 +1,43 @@
+---
+title: Conditional Validation
+description: Learn how to run the Starlight Spell Checker plugin conditionally to avoid unnecessary cache invalidation.
+---
+
+When using the Starlight Spell Checker plugin with the [Content Layer API](https://docs.astro.build/en/guides/content-collections), the plugin will automatically invalidate the content layer cache so that all words can be properly validated.
+To avoid unnecessary cache invalidation, it is recommended to conditionally use the plugin only when necessary.
+
+## Run the plugin conditionally
+
+By default, when adding the plugin to your Starlight configuration in the [`plugins`](https://starlight.astro.build/reference/configuration/#plugins) array, the plugin will run for every build.
+
+Instead of running the plugin for every build, you can conditionally use the plugin based on an environment variable.
+In the following example, the plugin will only run when the `CHECK_SPELLING` environment variable is set.
+
+```diff lang="js"
+// astro.config.mjs
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import starlightSpellChecker from 'starlight-spell-checker'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+-      plugins: [starlightSpellChecker()],
++      plugins: process.env.CHECK_SPELLING ? [starlightSpellChecker()] : [],
+      title: 'My Docs',
+    }),
+  ],
+})
+```
+
+To run the plugin only when the `CHECK_SPELLING` environment variable is set, you can add the following script to your `package.json` file:
+
+```json title="package.json"
+{
+  "scripts": {
+    "spellcheck": "CHECK_SPELLING=true astro build"
+  }
+}
+```
+
+The spell check script can be used on CI pipelines to validate internal words in a dedicated workflow while deployment builds can skip the link validation step.