Merge remote-tracking branch 'origin/master' into issue_3959_gateway_replica_pipeline

Author: jvstme

.github/workflows/build-docs.yml

@@ -1,4 +1,8 @@
-name: Build Docs
+name: Build Site
+
+# Reusable build of the full site: the React landing (website/) overlaid onto the
+# MkDocs docs + blog build, via scripts/docs/build_site.sh. Produces the `site` artifact
+# consumed by docs.yaml (deploy) and build.yml (PR build check).
 
 on:
   workflow_call:
@@ -11,13 +15,18 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           python-version: 3.11
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
       - name: Install dstack
         run: |
           uv sync --extra server
       - name: Build
         run: |
           sudo apt-get update && sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
-          uv run mkdocs build -s
+          ./scripts/docs/build_site.sh
       - uses: actions/upload-artifact@v4
         with:
           name: site

.github/workflows/docs.yaml

@@ -1,4 +1,7 @@
-name: Build & Deploy Docs
+name: Build & Deploy Site
+
+# Builds the full site (React landing + MkDocs docs + blog, see build-docs.yml) and
+# cross-repo deploys it to the GitHub Pages repo serving dstack.ai.
 
 on:
   workflow_dispatch:

.justfile

@@ -8,6 +8,7 @@
 # * runner/.justfile – Building and uploading dstack runner and shim
 # * frontend/.justfile – Building and running the frontend
 # * mkdocs/.justfile – Building and previewing the docs site
+# * website/.justfile – Building and previewing the React landing page
 
 default:
     @just --list
@@ -19,3 +20,5 @@ import "runner/.justfile"
 import "frontend/.justfile"
 
 import "mkdocs/.justfile"
+
+import "website/.justfile"

contributing/DOCS.md

@@ -1,5 +1,11 @@
 # Documentation setup
 
+> **The dstack.ai site has three parts on one origin:** the **landing** page (`/`) is a React
+> app in [`website/`](../website); the **docs** (`/docs`) and **blog** (`/blog`) are built with
+> MkDocs from `mkdocs/`. This guide covers the **docs and blog** (MkDocs). For the landing and
+> for building everything together, see [The landing page](#the-landing-page-website) and
+> [Building the whole site](#building-the-whole-site) below.
+
 ## 1. Clone the repo:
 
 ```shell
@@ -36,20 +42,52 @@ uv run pre-commit install
 
 ## 5. Preview documentation
 
-To preview the documentation, run the follow command:
+To preview the **docs and blog** (MkDocs), run the follow command:
 
 ```shell
 uv run mkdocs serve --livereload -s
 ```
 
 The `--livereload` flag is required to work around live-reload bugs in recent `mkdocs` versions.
 
+This serves the docs and blog only. The landing page (`/`) is a separate React app — when you
+run `mkdocs serve` on its own, `/` simply redirects to `/docs/`. To work on the landing, see
+[The landing page](#the-landing-page-website) below.
+
 If you want to build static files, you can use the following command:
 
 ```shell
 uv run mkdocs build -s
 ```
 
+## The landing page (website/)
+
+The landing page at `/` is a React (Vite) app in [`website/`](../website), not MkDocs. It has
+its own `package.json`/`node_modules`. Preview it on its own (requires Node 20+):
+
+```shell
+just website-dev            # Vite dev server on http://127.0.0.1:5173
+```
+
+Docs/blog links on the landing resolve same-origin (`/docs`, `/blog`), which 404 in standalone
+dev. Point them at a live site while iterating: `just website-dev https://dstack.ai`.
+
+The `/old` route is kept as a template for building future product pages (reachable in dev; not
+part of the production deploy). Google Analytics and the social/OG image reuse the same property
+and MkDocs-generated card as the rest of the site.
+
+## Building the whole site
+
+CI builds the landing and the MkDocs docs/blog and overlays them into a single `site/`:
+
+```shell
+just site-build             # website/dist + `mkdocs build` -> ./site (scripts/docs/build_site.sh)
+just site-serve             # preview the combined site on http://127.0.0.1:8001
+```
+
+In the combined build the React `index.html` owns `/`, while MkDocs serves `/docs`, `/blog`, and
+the shared `/assets`. This is what the `Build & Deploy Site` workflow deploys.
+
 ## Documentation build system
 
 The documentation uses a custom build system with MkDocs hooks to generate various files dynamically.
@@ -141,7 +179,7 @@ we should not reintroduce per-tag OpenAPI files unless there is a concrete reaso
 
 ```
 mkdocs/                         # docs_dir for the mkdocs site
-├── index.md                    # Homepage
+├── index.md                    # Redirects to /docs/ (the landing "/" is the React app in website/)
 ├── docs/                       # /docs/ URL section
 │   ├── index.md                # Getting started
 │   ├── installation.md
@@ -157,7 +195,13 @@ mkdocs/                         # docs_dir for the mkdocs site
 ├── layouts/                    # Social card layouts
 └── assets/                     # Stylesheets, images, fonts
 
+website/                        # React (Vite) landing page — served at "/"
+├── index.html                  # Entry; title, OG/meta, Google Analytics
+├── src/                        # App, pages (Home, Old), components, routes
+└── public/static/              # Landing assets (namespaced to avoid clashing with /assets)
+
 scripts/docs/
+├── build_site.sh               # Build landing + docs/blog and overlay into ./site
 ├── hooks.py                    # MkDocs build hooks
 ├── gen_llms_files.py           # llms.txt generation
 ├── gen_schema_reference.py     # Schema expansion

mkdocs.yml

@@ -11,7 +11,7 @@ repo_name: dstackai/dstack
 edit_uri: edit/master/mkdocs/
 
 #Copyright
-copyright: © 2026 dstack Inc.
+copyright: © 2026, dstack Inc. All rights reserved.
 
 # Source directory for site content
 docs_dir: mkdocs
@@ -32,21 +32,23 @@ theme:
   font:
     text: Source Sans Pro
     code: IBM Plex Mono
+  # Light (default) + dark (slate) schemes WITH toggles — Material needs the toggle radios so its
+  # palette JS honors the stored __palette and applies it during parse (flash-free). We HIDE the
+  # toggle buttons via CSS (cloudscape-docs.css) and drive the choice from the shared `dstack-theme`
+  # localStorage key (website/src/theme.ts), translated into __palette in main.html's extrahead.
   palette:
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
+    - scheme: default
       primary: white
       accent: lilac
-  #        toggle:
-  #          icon: material/weather-night
-  #          name: Switch to dark mode
-  #      - media: "(prefers-color-scheme: dark)"
-  #        scheme: slate
-  #        primary: black
-  #        accent: light blue
-  #        toggle:
-  #          icon: material/weather-sunny
-  #          name: Switch to light mode
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - scheme: slate
+      primary: white
+      accent: lilac
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
   features:
     - content.tooltips
     - navigation.path
@@ -60,7 +62,7 @@ theme:
     - navigation.sections
     #    - navigation.expand
     - navigation.top
-    - announce.dismiss
+    # announce.dismiss removed — /old's banner has no dismiss (×) button
     - navigation.tracking
     - navigation.footer
 
@@ -252,6 +254,7 @@ extra_css:
   - assets/stylesheets/termynal.css
   - assets/stylesheets/landing.css
   - assets/stylesheets/pricing.css
+  - assets/stylesheets/cloudscape-docs.css
 extra_javascript:
   - https://unpkg.com/swagger-ui-dist@5.32.0/swagger-ui-bundle.js
   - assets/javascripts/swagger.js