Docs Overhaul

.github/workflows/deploy-docs.yml

@@ -0,0 +1,89 @@
+name: 'docs'
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    types:
+      - 'ready_for_review'
+      - 'opened'
+      - 'synchronize'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  check-and-build:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      # Python (needed for generate-docs-data)
+      - name: setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: '0.6.10'
+          enable-cache: true
+          python-version: '3.11'
+
+      - name: setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: install python dependencies
+        run: uv pip install --editable .[test]
+
+      # Node (needed for docs build)
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: install docs dependencies
+        run: pnpm install --prefer-frozen-lockfile
+        working-directory: docs-new
+
+      # Checks
+      - name: verify generated docs data
+        run: pnpm run check-docs-data
+        working-directory: docs-new
+
+      - name: build docs
+        run: pnpm build
+        working-directory: docs-new
+
+      # Upload artifact for deploy (main branch only)
+      - name: upload pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-new/dist
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: check-and-build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/translations.yml

@@ -0,0 +1,78 @@
+name: Crowdin Translations
+
+on:
+  # Allow manual runs from the Actions tab
+  workflow_dispatch:
+    inputs:
+      upload_sources:
+        description: 'Upload source strings to Crowdin'
+        type: boolean
+        default: true
+      download_translations:
+        description: 'Download translations from Crowdin'
+        type: boolean
+        default: true
+
+  # Upload sources & download translations when source files change on main
+  push:
+    branches:
+      - main
+    paths:
+      - 'invokeai/frontend/web/public/locales/en.json'
+      - 'docs/src/content/i18n/en.json'
+      - 'docs/src/content/docs/**/*.md'
+      - 'docs/src/content/docs/**/*.mdx'
+      - '!docs/src/content/docs/[a-z][a-z]/**'
+      - '!docs/src/content/docs/[a-z][a-z]-*/**'
+      - 'crowdin.yml'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  crowdin-sync:
+    name: Sync with Crowdin
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Crowdin Sync
+        uses: crowdin/github-action@v2
+        with:
+          # Upload sources on push to main or when manually requested
+          upload_sources: ${{ github.event_name != 'workflow_dispatch' || inputs.upload_sources }}
+          upload_translations: false
+
+          # Download translations on push to main or when manually requested
+          download_translations: ${{ github.event_name != 'workflow_dispatch' || inputs.download_translations }}
+
+          # PR settings for downloaded translations
+          create_pull_request: true
+          pull_request_title: 'i18n: update translations from Crowdin'
+          pull_request_body: |
+            Automated pull request from [Crowdin](https://crowdin.com).
+
+            This PR updates translations for:
+            - **Web App UI** (`invokeai/frontend/web/public/locales/`)
+            - **Documentation UI Strings** (`docs/src/content/i18n/`)
+            - **Documentation Content** (`docs/src/content/docs/<locale>/`)
+          pull_request_base_branch_name: main
+          pull_request_labels: 'i18n'
+
+          # Commit settings
+          localization_branch_name: crowdin/translations
+          commit_message: 'i18n: update translations from Crowdin'
+
+          # Use the config file at the repo root
+          config: crowdin.yml
+
+          # Skip untranslated strings/files to keep partial translations clean
+          download_translations_args: '--skip-untranslated-strings'
+
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.gitignore

@@ -179,6 +179,7 @@ cython_debug/
 
 # Scratch folder
 .scratch/
+worktrees/
 .vscode/
 .zed/
 

crowdin.yml

@@ -0,0 +1,30 @@
+# Crowdin Configuration
+# https://developer.crowdin.com/configuration-file/
+
+project_id_env: CROWDIN_PROJECT_ID
+api_token_env: CROWDIN_PERSONAL_TOKEN
+
+preserve_hierarchy: true
+
+# Map Crowdin's zh-TW to zh-Hant to match the existing file convention
+languages_mapping:
+  locale:
+    zh-TW: zh-Hant
+
+files:
+  # Web App UI Translations
+  - source: /invokeai/frontend/web/public/locales/en.json
+    translation: /invokeai/frontend/web/public/locales/%locale%.json
+
+  # Documentation - Starlight UI Strings
+  - source: /docs/src/content/i18n/en.json
+    translation: /docs/src/content/i18n/%locale%.json
+
+  # Documentation - Content Pages (MD and MDX)
+  - source: /docs/src/content/docs/**/*.{md,mdx}
+    translation: /docs/src/content/docs/%locale%/**/%original_file_name%
+    # Exclude translations directory to avoid re-uploading them as source files
+    ignore:
+      - /docs/src/content/docs/%locale%/**/*
+    # Translate full paragraphs rather than splitting into sentences
+    content_segmentation: 0

docs-new/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs-new/README.md

@@ -0,0 +1 @@
+# Invoke AI Documentation

docs-new/astro.config.mjs

@@ -0,0 +1,131 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// Plugins
+import starlightLinksValidator from 'starlight-links-validator';
+import starlightLlmsText from 'starlight-llms-txt';
+import starlightChangelogs, { makeChangelogsSidebarLinks } from 'starlight-changelogs';
+// import starlightContextualMenu from 'starlight-contextual-menu';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://invoke.ai',
+  // base is only needed if no custom domain is available, or if the site is hosted in a subdirectory
+  // base: '/InvokeAI',
+  integrations: [
+    starlight({
+      // Content
+      title: {
+        en: 'InvokeAI Documentation',
+      },
+      logo: {
+        src: './src/assets/invoke-icon-wide.svg',
+        alt: 'InvokeAI Logo',
+        replacesTitle: true,
+      },
+      favicon: './src/assets/invoke-icon.svg',
+      editLink: {
+        baseUrl: 'https://github.com/invoke-ai/InvokeAI/edit/main/docs',
+      },
+      defaultLocale: 'root',
+      locales: {
+        root: {
+          label: 'English',
+          lang: 'en',
+        },
+      },
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/invoke-ai/InvokeAI',
+        },
+        {
+          icon: 'discord',
+          label: 'Discord',
+          href: 'https://discord.gg/ZmtBAhwWhy',
+        },
+        {
+          icon: 'youtube',
+          label: 'YouTube',
+          href: 'https://www.youtube.com/@invokeai',
+        },
+      ],
+      tableOfContents: {
+        maxHeadingLevel: 4,
+      },
+      customCss: [
+        '@fontsource-variable/inter',
+        '@fontsource-variable/roboto-mono',
+        './src/styles/custom.css',
+      ],
+      sidebar: [
+        {
+          label: 'Start Here',
+          autogenerate: { directory: 'start-here' },
+        },
+        {
+          label: 'Configuration',
+          autogenerate: { directory: 'configuration' },
+        },
+        {
+          label: 'Concepts',
+          autogenerate: { directory: 'concepts' },
+        },
+        {
+          label: 'Features',
+          autogenerate: { directory: 'features' },
+        },
+        {
+          label: 'Workflows',
+          autogenerate: { directory: 'workflows' },
+          collapsed: true,
+        },
+        {
+          label: 'Development',
+          autogenerate: { directory: 'development', collapsed: true },
+          collapsed: true,
+        },
+        {
+          label: 'Contributing',
+          autogenerate: { directory: 'contributing' },
+          collapsed: true,
+        },
+        {
+          label: 'Troubleshooting',
+          autogenerate: { directory: 'troubleshooting' },
+          collapsed: true,
+        },
+        {
+          label: 'Releases',
+          collapsed: true,
+          items: [
+            ...makeChangelogsSidebarLinks([
+              {
+                type: 'recent',
+                base: 'releases',
+              }
+            ])
+          ]
+        }
+      ],
+      components: {
+        ThemeProvider: './src/lib/components/ForceDarkTheme.astro',
+        ThemeSelect: './src/lib/components/EmptyComponent.astro',
+        Footer: './src/lib/components/Footer.astro',
+        PageFrame: './src/layouts/PageFrameExtended.astro',
+      },
+      plugins: [
+        starlightLinksValidator(),
+        starlightLlmsText(),
+        starlightChangelogs(),
+        // starlightContextualMenu({
+        //   actions: [
+        //     'copy', 'view', 'chatgpt', 'claude'
+        //   ]
+        // }),
+      ],
+    }),
+  ],
+});

docs-new/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "generate-docs-data": "uv run python ../scripts/generate_docs_json.py",
+    "check-docs-data": "pnpm run generate-docs-data && git diff --exit-code -- src/generated",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/markdoc": "^1.0.0",
+    "@astrojs/starlight": "^0.38.1",
+    "@astrojs/starlight-markdoc": "^0.6.0",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource-variable/roboto-mono": "^5.2.8",
+    "astro": "^6.0.4",
+    "mermaid": "^11.12.3",
+    "rehype-external-links": "^3.0.0",
+    "sharp": "^0.34.2",
+    "starlight-changelogs": "^0.5.0",
+    "starlight-contextual-menu": "^0.1.5",
+    "starlight-links-validator": "^0.20.1",
+    "starlight-llms-txt": "^0.8.0"
+  },
+  "devDependencies": {
+    "node-addon-api": "^8.5.0",
+    "node-gyp": "^12.2.0"
+  },
+  "packageManager": "pnpm@10.12.4"
+}