fix(docs): urls respect baseurl + better deployment scheduling (#9069)

* fix(docs): avoid relative link urls, fix homepage title

* fix(docs): better deployment run scheduling

* fix(docs): remove crowdin

---------

Co-authored-by: joshistoast <me@joshcorbett.com>

Author: joshistoast

.github/workflows/deploy-docs.yml

@@ -21,15 +21,51 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
+  pull-requests: read
 
 concurrency:
-  group: 'pages'
+  group: ${{ github.workflow }}-${{ github.ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      docs: ${{ steps.manual.outputs.docs || steps.filter.outputs.docs }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: mark manual run
+        if: github.event_name == 'workflow_dispatch'
+        id: manual
+        run: echo "docs=true" >> "$GITHUB_OUTPUT"
+
+      - name: detect docs-related changes
+        if: github.event_name != 'workflow_dispatch'
+        id: filter
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            docs:
+              - '.github/workflows/deploy-docs.yml'
+              - 'docs/**'
+              - 'scripts/generate_docs_json.py'
+              - 'invokeai/app/**'
+              - 'invokeai/backend/**'
+              - 'pyproject.toml'
+              - 'uv.lock'
+
   check-and-build:
+    needs: changes
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+        github.event.pull_request.draft == false &&
+        needs.changes.outputs.docs == 'true') ||
+      (github.event_name == 'push' && needs.changes.outputs.docs == 'true')
     runs-on: ubuntu-22.04
     timeout-minutes: 20
     steps:
@@ -49,8 +85,10 @@ jobs:
         with:
           python-version: '3.11'
 
+      # generate_docs_json.py only needs the invokeai package importable
+      # (pydantic + invokeai.app/backend). Skip the [test] extra to keep CI fast.
       - name: install python dependencies
-        run: uv pip install --editable .[test]
+        run: uv pip install --editable .
 
       # Node (needed for docs build)
       - name: setup node
@@ -90,6 +128,10 @@ jobs:
     if: github.ref == 'refs/heads/main'
     needs: check-and-build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/mkdocs-material.yml

@@ -29,7 +29,7 @@ export default defineConfig({
         alt: 'InvokeAI Logo',
         replacesTitle: true,
       },
-      favicon: '/favicon.svg',
+      favicon: 'favicon.svg',
       editLink: {
         baseUrl: 'https://github.com/invoke-ai/InvokeAI/edit/main/docs',
       },
@@ -122,17 +122,10 @@ export default defineConfig({
         PageFrame: './src/layouts/PageFrameExtended.astro',
       },
       plugins: [
-        // The links validator is skipped for the ghpages target because content uses
-        // root-absolute links (e.g. /concepts/...) that don't include the /InvokeAI base.
-        // Production (custom domain) still enforces link validation.
-        ...(isGhPages
-          ? []
-          : [
-              starlightLinksValidator({
-                errorOnRelativeLinks: false,
-                errorOnLocalLinks: false,
-              }),
-            ]),
+        starlightLinksValidator({
+          errorOnRelativeLinks: false,
+          errorOnLocalLinks: false,
+        }),
         starlightLlmsText(),
         starlightChangelogs(),
         // starlightContextualMenu({

crowdin.yml

@@ -130,4 +130,4 @@ In the current UI, the `Seed Behaviour` setting controls how seeds are reused ac
 - Be careful with multiple groups, because the number of combinations grows quickly.
 - Review the expanded prompt list before launching a large batch.
 - Use dynamic prompting for variation, not to avoid thinking through the base prompt.
-- When one specific term needs more emphasis, use [Prompting Syntax](/concepts/prompt-syntax) instead of adding more dynamic groups.
+- When one specific term needs more emphasis, use [Prompting Syntax](../prompt-syntax) instead of adding more dynamic groups.

docs/astro.config.mjs

@@ -43,17 +43,17 @@ There are two prompt boxes: **Positive Prompt** & **Negative Prompt**.
   <LinkCard
     title="Prompting Guide"
     description="Learn how to structure prompts, use positive and negative prompts well, and iterate toward better results."
-    href="/concepts/prompting-guide"
+    href="../prompting-guide"
   />
   <LinkCard
     title="Prompting Syntax"
     description="Learn InvokeAI's advanced prompt weighting and composition syntax, including `+`, `-`, `.blend()`, and `.and()`."
-    href="/concepts/prompt-syntax"
+    href="../prompt-syntax"
   />
   <LinkCard
     title="Dynamic Prompting"
     description="Expand one prompt into many prompt variations with curly-brace syntax."
-    href="/concepts/dynamic-prompting"
+    href="../dynamic-prompting"
   />
 </CardGrid>
 
@@ -78,7 +78,7 @@ Invoke offers a number of different workflows for interacting with models to pro
 <Steps>
   1. **Fine-tuning your prompt:**
 
-      The more specific you are, the closer the image will turn out to what is in your head. Adding more details in the Positive or Negative Prompt can help add or remove parts of the image. You can also use advanced techniques like upweighting and downweighting to control the influence of specific words. Learn more in the [Prompting Guide](/concepts/prompting-guide) and [Prompting Syntax](/concepts/prompt-syntax).
+      The more specific you are, the closer the image will turn out to what is in your head. Adding more details in the Positive or Negative Prompt can help add or remove parts of the image. You can also use advanced techniques like upweighting and downweighting to control the influence of specific words. Learn more in the [Prompting Guide](../prompting-guide) and [Prompting Syntax](../prompt-syntax).
 
       :::tip
         If you're seeing poor results, try adding the things you don't like about the image to your negative prompt. E.g. *distorted, low quality, unrealistic, etc.*
@@ -99,7 +99,7 @@ Invoke offers a number of different workflows for interacting with models to pro
 
   5. **Explore Advanced Settings:**
 
-      InvokeAI has a full suite of tools available to allow you complete control over your image creation process. Check out our [docs if you want to learn more](https://invoke-ai.github.io/InvokeAI/features/).
+      InvokeAI has a full suite of tools available to allow you complete control over your image creation process. Check out our [features docs](../../features/gallery) if you want to learn more.
 </Steps>
 
 ## Terms & Concepts

docs/src/content/docs/concepts/dynamic-prompting.mdx

@@ -53,4 +53,4 @@ In this situation, you may need to provide some additional information to identi
   Add `:v2` to the repo ID and use that when installing the model: `monster-labs/control_v1p_sd15_qrcode_monster:v2`
 :::
 
-[set up in the config file]: /configuration/invokeai-yaml
+[set up in the config file]: ../../configuration/invokeai-yaml

docs/src/content/docs/concepts/image-generation.mdx

@@ -10,18 +10,18 @@ import { Card, LinkCard, CardGrid } from '@astrojs/starlight/components';
 <CardGrid>
   <LinkCard
     title="Prompting Guide"
-    href="/concepts/prompting-guide"
+    href="../prompting-guide"
     description="Learn how to write effective prompts for InvokeAI."
   />
 
   <LinkCard
     title="Dynamic Prompting"
-    href="/concepts/dynamic-prompting"
+    href="../dynamic-prompting"
     description="Learn how to create many prompt variations from a single template."
   />
 </CardGrid>
 
-InvokeAI supports Compel-style prompt weighting and prompt functions for `SD 1.5` and `SDXL` text conditioning workflows. Recent model families, including `FLUX`, `Z-Image`, `CogView4`, and `Qwen Image`, bypass Compel and do not use the syntax documented on this page. This page documents syntax for those Compel-based workflows only. If you want general advice on writing better prompts, start with [Prompting Guide](/concepts/prompting-guide).
+InvokeAI supports Compel-style prompt weighting and prompt functions for `SD 1.5` and `SDXL` text conditioning workflows. Recent model families, including `FLUX`, `Z-Image`, `CogView4`, and `Qwen Image`, bypass Compel and do not use the syntax documented on this page. This page documents syntax for those Compel-based workflows only. If you want general advice on writing better prompts, start with [Prompting Guide](../prompting-guide).
 
 :::note[Compatibility note]
   If a weighted prompt seems to be ignored, check whether you are using an `SD 1.5` or `SDXL` workflow. Compel syntax on this page does not apply to newer model families such as `FLUX`, `Z-Image`, `CogView4`, and `Qwen Image`.
@@ -134,5 +134,5 @@ Use unescaped parentheses only when you mean grouping or weighting.
 
 ## Related pages
 
-- For practical prompt-writing advice, read [Prompting Guide](/concepts/prompting-guide).
-- For prompt expansion and permutations, read [Dynamic Prompting](/concepts/dynamic-prompting).
+- For practical prompt-writing advice, read [Prompting Guide](../prompting-guide).
+- For prompt expansion and permutations, read [Dynamic Prompting](../dynamic-prompting).

docs/src/content/docs/concepts/models.mdx

@@ -10,13 +10,13 @@ import { Card, CardGrid, Steps, LinkCard } from '@astrojs/starlight/components';
 <CardGrid>
   <LinkCard
     title="Prompting Syntax"
-    href="/concepts/prompt-syntax"
+    href="../prompt-syntax"
     description="Learn how to weight prompt terms, blend concepts, and use prompt conjunctions for more control."
   />
 
   <LinkCard
     title="Dynamic Prompting"
-    href="/concepts/dynamic-prompting"
+    href="../dynamic-prompting"
     description="Learn how to create many prompt variations from a single template."
   />
 </CardGrid>
@@ -82,7 +82,7 @@ Good negative prompts usually name specific failure modes: `blurry`, `distorted
 
   5. Escalate only when needed
 
-      If the result is close but one element is too weak or too strong, move to [Prompting Syntax](/concepts/prompt-syntax) for weighting. If you want lots of variations, use [Dynamic Prompting](/concepts/dynamic-prompting).
+      If the result is close but one element is too weak or too strong, move to [Prompting Syntax](../prompt-syntax) for weighting. If you want lots of variations, use [Dynamic Prompting](../dynamic-prompting).
 </Steps>
 
 Here is the same idea refined in stages:
@@ -108,10 +108,10 @@ The same prompt can behave very differently across models.
 
 Reach for advanced syntax when a normal comma-separated prompt is almost right, but you need more control.
 
-- Use [Prompting Syntax](/concepts/prompt-syntax) when one term needs more or less influence.
+- Use [Prompting Syntax](../prompt-syntax) when one term needs more or less influence.
 - Use `.blend()` when you want to mix concepts or styles deliberately.
 - Use `.and()` when you want separate prompt clauses encoded individually.
-- Use [Dynamic Prompting](/concepts/dynamic-prompting) when you want many prompt variations from one template.
+- Use [Dynamic Prompting](../dynamic-prompting) when you want many prompt variations from one template.
 
 ## Common mistakes
 

docs/src/content/docs/concepts/prompt-syntax.mdx

@@ -14,7 +14,7 @@ import SystemRequirementsLink from '@components/SystemRequirmentsLink.astro'
       Docker Desktop on Windows [includes GPU support](https://www.docker.com/blog/wsl-2-gpu-support-for-docker-desktop-on-nvidia-gpus/).
     </TabItem>
     <TabItem label="MacOS" icon="apple">
-      Docker can not access the GPU on macOS, so your generation speeds will be slow. Use the [launcher](/start-here/installation) instead.
+      Docker can not access the GPU on macOS, so your generation speeds will be slow. Use the [launcher](../../start-here/installation) instead.
     </TabItem>
     <TabItem label="Linux" icon="linux">
       Configure Docker to access your machine's GPU.