docs(site): point install URLs at the deploy origin on preview builds

Preview deploys (main.viteplus.dev, PR staging) serve their own install
scripts, but the docs hardcode the production https://vite.plus
shortcuts. The deploy-docs composite now passes a site-origin input to
the build as DOCS_SITE_ORIGIN. When set, a markdown-it rule rewrites the
install URLs in markdown content, and the homepage install command and
AI copy prompt read __DOCS_*__ define constants from the same origin
(including the llms-full.txt link). The build:site task tracks the
variable in env so each deploy target keeps its own Vite Task cache
entry. Production builds are unchanged.

Known gap: the llms dumps copy raw markdown and keep production URLs on
previews.

Author: fengmk2

.github/actions/deploy-docs/action.yml

@@ -22,6 +22,14 @@ inputs:
     description: 'Commit sha that scopes the primary cache key.'
     required: false
     default: ${{ github.sha }}
+  site-origin:
+    description: >-
+      Origin of this deploy when it is not production viteplus.dev
+      (e.g. https://main.viteplus.dev). When set, the docs build rewrites the
+      https://vite.plus installer URLs to this origin's install scripts.
+      Leave empty for production.
+    required: false
+    default: ''
 
 runs:
   using: 'composite'
@@ -62,6 +70,8 @@ runs:
     - run: vp run build
       shell: bash
       working-directory: docs
+      env:
+        DOCS_SITE_ORIGIN: ${{ inputs.site-origin }}
 
     - name: Save docs Vite Task cache
       if: success() && steps.vite-task-cache.outputs.cache-hit != 'true'

.github/workflows/deploy-docs-main.yml

@@ -37,3 +37,4 @@ jobs:
         with:
           void-project: viteplus-main
           void-token: ${{ secrets.VOID_TOKEN }}
+          site-origin: https://main.viteplus.dev

.github/workflows/deploy-docs-preview.yml

@@ -39,6 +39,7 @@ jobs:
           void-token: ${{ secrets.VOID_TOKEN }}
           cache-ref: pr-${{ github.event.pull_request.number }}
           cache-sha: ${{ github.event.pull_request.head.sha }}
+          site-origin: https://viteplus-staging.void.app
 
       - name: Comment on PR
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9

docs/.vitepress/config.mts

@@ -7,6 +7,26 @@ import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-i
 import llmstxt from 'vitepress-plugin-llms';
 import { withMermaid } from 'vitepress-plugin-mermaid';
 
+// Non-production deploys (the main preview, PR staging) serve their own
+// copies of the install scripts and llms dumps, so the https://vite.plus
+// installer shortcuts and absolute site URLs must point at the deploy's
+// origin instead of production. The deploy workflows set DOCS_SITE_ORIGIN via
+// the deploy-docs composite action; markdown content is rewritten through
+// markdown-it below, and Vue components read the __DOCS_*__ define constants.
+const siteOrigin = process.env.DOCS_SITE_ORIGIN;
+const docsOrigin = siteOrigin || 'https://viteplus.dev';
+const installShUrl = siteOrigin ? `${siteOrigin}/install.sh` : 'https://vite.plus';
+const installPs1Url = siteOrigin ? `${siteOrigin}/install.ps1` : 'https://vite.plus/ps1';
+
+function rewriteInstallUrls(text: string): string {
+  if (!siteOrigin) {
+    return text;
+  }
+  return text
+    .replaceAll('https://vite.plus/ps1', installPs1Url)
+    .replaceAll('https://vite.plus', installShUrl);
+}
+
 const taskRunnerGuideItems = [
   {
     text: 'Run',
@@ -113,6 +133,11 @@ export default extendConfig(
         ['meta', { name: 'twitter:site', content: '@voidzerodev' }],
       ],
       vite: {
+        define: {
+          __DOCS_ORIGIN__: JSON.stringify(docsOrigin),
+          __DOCS_INSTALL_SH_URL__: JSON.stringify(installShUrl),
+          __DOCS_INSTALL_PS1_URL__: JSON.stringify(installPs1Url),
+        },
         optimizeDeps: {
           include: ['mermaid > @braintree/sanitize-url'],
         },
@@ -258,6 +283,31 @@ export default extendConfig(
       markdown: {
         config(md) {
           md.use(groupIconMdPlugin);
+          if (siteOrigin) {
+            md.core.ruler.push('rewrite-install-urls', (state) => {
+              const walk = (tokens: typeof state.tokens) => {
+                for (const token of tokens) {
+                  if (
+                    token.type === 'fence' ||
+                    token.type === 'code_inline' ||
+                    token.type === 'text'
+                  ) {
+                    token.content = rewriteInstallUrls(token.content);
+                  }
+                  if (token.type === 'link_open') {
+                    const href = token.attrGet('href');
+                    if (href) {
+                      token.attrSet('href', rewriteInstallUrls(href));
+                    }
+                  }
+                  if (token.children) {
+                    walk(token.children);
+                  }
+                }
+              };
+              walk(state.tokens);
+            });
+          }
         },
       },
     }),

docs/.vitepress/env.d.ts

@@ -1,3 +1,13 @@
+// Build-time constants injected via vite.define in config.mts. They point at
+// the current deploy's origin (production, main preview, or PR staging). The
+// dunder names follow the Vite convention for compile-time replaced globals.
+// oxlint-disable-next-line no-underscore-dangle
+declare const __DOCS_ORIGIN__: string;
+// oxlint-disable-next-line no-underscore-dangle
+declare const __DOCS_INSTALL_SH_URL__: string;
+// oxlint-disable-next-line no-underscore-dangle
+declare const __DOCS_INSTALL_PS1_URL__: string;
+
 // Vue SFC module declaration
 declare module '*.vue' {
   import type { DefineComponent } from 'vue';

docs/.vitepress/theme/components/CopyPrompt.vue

@@ -7,25 +7,28 @@ import { onBeforeUnmount, ref } from 'vue';
 // live llms-full.txt docs dump.
 const DEFAULT_PROMPT = `I want to use Vite+ in my project. Vite+ is the unified toolchain for the web behind the \`vp\` CLI — one tool combining Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task, plus runtime and package-manager management.
 
-First, read https://viteplus.dev/llms-full.txt to learn Vite+'s commands and configuration.
+First, read ${__DOCS_ORIGIN__}/llms-full.txt to learn Vite+'s commands and configuration.
 
 Install the \`vp\` CLI if it's not already on the system:
-- macOS / Linux: curl -fsSL https://vite.plus | bash
-- Windows (PowerShell): irm https://vite.plus/ps1 | iex
+- macOS / Linux: curl -fsSL ${__DOCS_INSTALL_SH_URL__} | bash
+- Windows (PowerShell): irm ${__DOCS_INSTALL_PS1_URL__} | iex
 
 Then open a new terminal and run \`vp help\`. To scaffold a new project run \`vp create\`; to move an existing Vite project onto Vite+ run \`vp migrate\`.
 
 Day-to-day commands: \`vp install\` (dependencies), \`vp dev\` (dev server), \`vp check\` (format + lint + type-check), \`vp test\` (tests), and \`vp build\` (production build).
 
 Help me get set up and explain anything I should know.`;
 
+// DEFAULT_PROMPT interpolates the __DOCS_*__ define constants, so it is not a
+// static literal and cannot be a withDefaults() default (defineProps is
+// hoisted out of setup). Resolve the fallback at use sites instead.
 const props = withDefaults(
   defineProps<{
     prompt?: string;
     label?: string;
   }>(),
   {
-    prompt: DEFAULT_PROMPT,
+    prompt: '',
     label: 'Copy Prompt',
   },
 );
@@ -55,7 +58,7 @@ const copyPrompt = async (event: MouseEvent) => {
     (event.currentTarget as HTMLElement | null)?.blur();
   }
   try {
-    await navigator.clipboard.writeText(props.prompt);
+    await navigator.clipboard.writeText(props.prompt || DEFAULT_PROMPT);
     flash('copied');
   } catch {
     flash('error');

docs/.vitepress/theme/components/home/InstallCommand.vue

@@ -12,12 +12,12 @@ const commandCards: CommandCard[] = [
   {
     id: 'unix',
     label: 'macOS / Linux',
-    command: 'curl -fsSL https://vite.plus | bash',
+    command: `curl -fsSL ${__DOCS_INSTALL_SH_URL__} | bash`,
   },
   {
     id: 'windows',
     label: 'Windows (PowerShell)',
-    command: 'irm https://vite.plus/ps1 | iex',
+    command: `irm ${__DOCS_INSTALL_PS1_URL__} | iex`,
   },
 ];
 

docs/vite.config.ts

@@ -3,6 +3,9 @@ export default {
     tasks: {
       'build:site': {
         command: 'vitepress build',
+        // The install-URL rewrite in .vitepress/config.mts depends on this
+        // variable, so different deploy targets must not share cached output.
+        env: ['DOCS_SITE_ORIGIN'],
         input: [
           { auto: true },
           '!.vitepress/.temp/**',

rfcs/deploy-docs-on-release.md

@@ -208,6 +208,30 @@ jobs:
 target, and its PR comment step, and now runs the same composite. Per-PR
 staging deploys remain the place to review docs changes before merge.
 
+### Origin-aware install URLs in the docs
+
+The docs hardcode the production installer shortcuts (`https://vite.plus`,
+`https://vite.plus/ps1`) in markdown code blocks and in the homepage Vue
+components. A preview deploy must point them at its own install scripts
+instead (for example `https://main.viteplus.dev/install.sh`), or readers of
+unreleased install docs run the production installer.
+
+The composite action passes its `site-origin` input to the docs build as
+`DOCS_SITE_ORIGIN`. When the variable is set:
+
+- A markdown-it rule in `.vitepress/config.mts` rewrites the install URLs in
+  fenced code, inline code, text, and link hrefs. Other `viteplus.dev`
+  subdomains (`setup.`, `registry-bridge.`) stay untouched.
+- The Vue components (homepage install command, AI copy prompt) read
+  `__DOCS_*__` define constants computed from the same origin. The AI prompt
+  also points at the deploy's own `llms-full.txt`.
+- The `build:site` run task lists `DOCS_SITE_ORIGIN` in `env`, so each deploy
+  target keeps its own Vite Task cache entry.
+
+Production builds leave the content untouched: the variable is unset there.
+Known gap: the llms dumps (`llms.txt`, `llms-full.txt`, per-page `.md`) copy
+raw markdown, so on previews they keep the production install URLs.
+
 ### Manual deploys
 
 `workflow_dispatch` covers urgent updates outside the release cycle: