From 706a3d32b5b7db243444d06170179cbfc01b2063 Mon Sep 17 00:00:00 2001
From: HiDeoo <494699+HiDeoo@users.noreply.github.com>
Date: Sun, 26 May 2024 11:34:44 +0200
Subject: [PATCH] docs: add deployment guide

---
 docs/astro.config.ts                       |  1 +
 docs/src/content/docs/configuration.md     |  4 ++-
 docs/src/content/docs/guides/deployment.md | 34 ++++++++++++++++++++++
 3 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/content/docs/guides/deployment.md

diff --git a/docs/astro.config.ts b/docs/astro.config.ts
index 5c4875b..02cc3a8 100644
--- a/docs/astro.config.ts
+++ b/docs/astro.config.ts
@@ -34,6 +34,7 @@ export default defineConfig({
             { label: 'Project Structure', link: '/guides/project-structure/' },
             { label: 'Ignoring Content', link: '/guides/ignoring-content/' },
             { label: 'Features', link: '/guides/features/' },
+            { label: 'Deployment', link: '/guides/deployment/' },
           ],
         },
         obsidianSidebarGroup,
diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md
index 8071ddc..3d3fcc6 100644
--- a/docs/src/content/docs/configuration.md
+++ b/docs/src/content/docs/configuration.md
@@ -58,7 +58,9 @@ The name of the output directory containing the generated Obsidian vault pages r
 Whether the Starlight Obsidian plugin should skip the generation of the Obsidian vault pages.
 
 This is useful to disable generating the Obsidian vault pages when deploying on platforms that do not have access to the Obsidian vault.
-This will require you to build and commit the pages locally ahead of time.
+This will require you to [build](https://docs.astro.build/en/reference/cli-reference/#astro-build) and commit vault pages before deploying your site.
+
+Read more about deploying your site in the [“Deployment”](/guides/deployment/) guide.
 
 ### `sidebar`
 
diff --git a/docs/src/content/docs/guides/deployment.md b/docs/src/content/docs/guides/deployment.md
new file mode 100644
index 0000000..f43794d
--- /dev/null
+++ b/docs/src/content/docs/guides/deployment.md
@@ -0,0 +1,34 @@
+---
+title: Deployment
+description: Learn how to deploy your Obsidian vault pages with the Starlight Obsidian plugin.
+---
+
+When building your documentation, the Starlight Obsidian plugin will generate pages from your Obsidian vault.
+
+## Deploying your vault pages
+
+When deploying your Starlight project, the target platform may not have access to the Obsidian vault or it would be impractical to include the vault in the deployment.
+In such cases, you can use the [`skipGeneration` configuration option](/configuration/#skipgeneration) to disable the generation of vault pages on specific platforms.
+
+When using this option, you will need to [build](https://docs.astro.build/en/reference/cli-reference/#astro-build) and commit the generated vault pages before deploying your site.
+
+```js {11-12}
+// astro.config.mjs
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import starlightObsidian from 'starlight-obsidian'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightObsidian({
+          // Disable generating vault pages when deploying on Vercel.
+          skipGeneration: !!process.env['VERCEL'],
+        }),
+      ],
+      title: 'My Docs',
+    }),
+  ],
+})
+```