[docs] migrate to vitepress

.gitattributes

@@ -16,10 +16,20 @@
 *.ixx        text eol=crlf
 *.tlh        text eol=crlf
 *.tli        text eol=crlf
+*.css        text eol=crlf
+*.js         text eol=crlf
+*.json       text eol=crlf
+*.md         text eol=crlf
+*.po         text eol=crlf
+*.vue        text eol=crlf
 
 *.sh         text eol=lf
 
 *.gif        -text
 *.jpg        -text
+*.jpeg       -text
 *.png        -text
+*.webm       -text
+*.mp4        -text
 *.exe        -text
+*.ico        -text

.github/copilot-instructions.md

@@ -81,7 +81,7 @@ src/                    All Phobos source code
 └── Blowfish/           Blowfish encryption replacement
 YRpp/                   Game binary header definitions (git submodule)
 lib/                    Third-party headers (e.g. nameof)
-docs/                   Sphinx documentation (Markdown/MyST)
+docs/                   VitePress documentation site and source Markdown
 scripts/                Build and setup scripts
 .editorconfig           Code style enforcement (tabs, Allman braces, CRLF)
 .vsconfig               Required VS components
@@ -285,44 +285,66 @@ When the type or function you need is missing or incorrect in YRpp, add or fix i
 
 ## Documentation
 
-The docs live in `docs/` and are built with [Sphinx](https://sphinx-doc.org/) + [MyST parser](https://myst-parser.readthedocs.io/) (Markdown with Sphinx directives). They are hosted on [Read the Docs](https://readthedocs.io/).
+The docs live in `docs/` and are built with [VitePress](https://vitepress.dev/). Source pages are Markdown files in `docs/`; the VitePress config, theme, and build integration live under `docs/.vitepress/` and `docs/vitepress/build-scripts/`.
+
+Important documentation paths:
+
+| Path | Purpose |
+|---|---|
+| `docs/.vitepress/config.ts` | Main VitePress config, nav/sidebar, locales, rewrites, search, last-updated settings |
+| `docs/.vitepress/theme/` | Custom theme wrapper, CSS overrides, Vue components used by docs |
+| `docs/vitepress/build-scripts/` | Vite/VitePress plugins and offline export scripts |
+| `docs/_static/` | VitePress public directory (`publicDir` is `_static`) |
+| `docs/locale/<locale>/LC_MESSAGES/*.po` | Source translations for localized docs |
+| `docs/vitepress/generated/` | Generated root and locale pages; do not edit by hand |
+| `docs/.vitepress/.temp/`, `docs/.artifacts/` | Build artifacts; do not commit |
+
+`README.md`, `CREDITS.md`, `LICENSE.md`, `logo.png`, and `logo-mono.png` are sourced from the repository root by the VitePress root pages plugin. Do not create or edit duplicate copies under `docs/`; edit the root files instead. The home page is generated from the root `README.md`.
 
 ### Syntax and formatting
 
-Doc pages use **MyST-flavored Markdown** (`.md`), not reStructuredText. Key MyST features used in this project:
-- **Directives**: `` ```{directive} `` blocks (e.g., `{hint}`, `{note}`, `{warning}`, `{toctree}`, `{include}`).
-- **Colon fences**: `:::{directive}` / `:::` as an alternative to backtick fences.
-- **Dollar math**: `$inline$` and `$$block$$` via `dollarmath` and `amsmath` extensions.
-- **Heading anchors**: auto-generated up to depth 3 (`myst_heading_anchors = 3`).
-- **Cross-references**: `(target-label)=` above a heading, then `` {ref}`target-label` `` to link.
-- **sphinx-design components**: tabs (`{tab-set}`/`{tab-item}`), cards (`{card}`), grids (`{grid}`), badges (`` {bdg-primary}`text` ``), and icons (`` {octicon}`icon-name` ``).
+Doc pages use VitePress Markdown. Prefer VitePress-native syntax:
+- **Containers**: `::: tip`, `::: info`, `::: warning`, `::: danger`, and `::: details Click to show`.
+- **Code fences**: use language-tagged fenced blocks such as ` ```ini ` and ` ```cpp `.
+- **Links**: use normal Markdown links to source pages, e.g. `[what's new page](Whats-New.md)` or `[Credits](/CREDITS)`.
+- **Heading anchors**: VitePress generates anchors from headings. Link to headings with normal hash links such as `Fixed-or-Improved-Logics.md#target-scan-guard-range-customizations`.
+- **Vue components**: custom components registered in `docs/.vitepress/theme/index.ts` can be used directly in Markdown. For example, `CustomGameSpeedGenerator` is used in `docs/Miscellanous.md`.
 
 INI code snippets should use ` ```ini ` fenced blocks. See existing doc pages for the standard format of documenting INI keys (key name, default value, accepted types, explanatory comments).
 
+Do not introduce legacy MyST-style syntax such as `` ```{note} ``, `` ```{dropdown} ``, `{ref}` links, `toctree`, grid/card/tab directives, or `(target-label)=` labels. Convert old blocks to VitePress containers when editing nearby content.
+
 ### Building docs locally
 
 ```
-pip install -r docs/requirements.txt
 scripts\build_docs.bat
 ```
 
-Output goes to `docs/_build/html/`. Pull requests are automatically built and served by Read the Docs - check the PR status checks for a preview link.
+The batch script installs `docs/node_modules` if needed and runs `npm run build` from `docs/`. You can also run the npm scripts directly:
 
-### Translations
+```
+cd docs
+npm ci
+npm run dev        # local dev server
+npm run build      # production VitePress build
+npm run build:offline    # production build plus single-entry offline documentation export
+npm run lint            # ESLint for docs scripts/config/theme
+npm run format:check    # Prettier check for docs files
+```
 
-The project uses Sphinx internationalization with `.po` files. Currently only **zh_CN** (Chinese) is maintained. The translation workflow:
+Regular VitePress output goes to `docs/.artifacts/dist/`. Offline documentation output goes to `docs/.artifacts/offline-doc/`, with one top-level `offline-doc.htm` and supporting files under `offline-doc/`. Read the Docs publishes that offline output as an `htmlzip` download named `offline-doc.zip`.
 
-1. **Regenerate `.pot` templates and update `.po` files**:
-   ```
-   scripts\build_docs_locale.bat
-   ```
-   This runs `sphinx-build -b gettext` then `sphinx-intl update -p ./locale -l zh_CN`.
+### Translations
 
-2. **Edit translations** in `docs/locale/zh_CN/LC_MESSAGES/*.po` - each `.po` file corresponds to a doc page. Key translation conventions: translate "AI agent" as **智能体** (not 代理, which means "proxy").
+The project uses `.po` files as translation sources. VitePress localized pages are generated by `docs/vitepress/build-scripts/vitepress-po-locale-plugin.ts`. Currently only **zh_CN** (Chinese) is maintained, but the plugin is written to support additional locales in the future.
 
-3. **Build localized docs** with `sphinx-build -D language=zh_CN`.
+- English source pages live in `docs/*.md` and selected root files (`README.md`, `CREDITS.md`, `LICENSE.md`).
+- Chinese translations live in `docs/locale/zh_CN/LC_MESSAGES/*.po`.
+- `docs/locale/zh_CN/LC_MESSAGES/index.po` also provides localized labels for VitePress theme text such as nav/sidebar labels, "On this page", "Last updated", and language names.
+- Generated localized Markdown is written to `docs/vitepress/generated/locales/zh_CN/` during VitePress startup/build. Do not edit generated files.
+- Use `scripts\build_docs.bat` for the regular online documentation build and `scripts\build_docs_offline.bat` for the offline HTML documentation export. Locale pages are generated automatically by both builds.
 
-When editing English source docs, be aware that changes will invalidate corresponding `.po` entries (marked fuzzy), so translators will need to update them.
+When editing English source docs, update the matching `.po` entries when appropriate. Key translation convention: translate "AI agent" as **智能体** (not 代理, which means "proxy").
 
 ### English quality and style
 
@@ -343,6 +365,8 @@ For non-trivial changes (unless labeled `No Documentation Needed`):
 
 Use `[Minor]` in the PR title for small changes that don't need documentation updates.
 
+Use `[Docs]` at the start of the PR title for documentation-only changes that should skip the PR DLL build.
+
 ## Trust These Instructions
 
 Trust the information here and proceed directly with implementation. Only search the codebase if these instructions are incomplete or produce errors. The build scripts, project structure, and patterns described above have been validated against the current `develop` branch at commit `a67278ed95c9cdc611e659d677bd4c918a887d16`.

.github/workflows/pr-nightly.yml

@@ -16,6 +16,7 @@ env:
 
 jobs:
   build:
+    if: ${{ !startsWith(toLower(github.event.pull_request.title), '[docs]') }}
     runs-on: windows-latest
 
     steps:

.gitignore

@@ -14,11 +14,6 @@ Nightly/
 
 DevBuild/
 
-docs/_build/
-docs/locale/.doctrees/
-*.pot
-*.mo
-
 /.vscode
 
 build

.readthedocs.yaml

@@ -2,24 +2,26 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the version of Python and other tools you might need
-build:
-   os: ubuntu-24.04
-   tools:
-      python: "3.11"
-
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-   configuration: docs/conf.py
-
-# Optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+  - htmlzip
 
-# We recommend specifying your dependencies to enable reproducible builds:
-python:
-   install:
-   - requirements: docs/requirements.txt
+build:
+  os: ubuntu-24.04
+  apt_packages:
+    - zip
+  tools:
+    nodejs: "22"
+  jobs:
+    install:
+      - cd docs && npm ci
+    build:
+      html:
+        - cd docs && npm run build
+        - mkdir -p $READTHEDOCS_OUTPUT/html
+        - cp -r docs/.artifacts/dist/* $READTHEDOCS_OUTPUT/html/
+      htmlzip:
+        - cd docs && npm run build:offline
+        - mkdir -p $READTHEDOCS_OUTPUT/htmlzip
+        - cd docs/.artifacts && zip -r $READTHEDOCS_OUTPUT/htmlzip/offline-doc.zip offline-doc

CREDITS.md

@@ -21,7 +21,7 @@ This page lists all the individual contributions to the project by their author.
   - Non-ASCII input fix
   - Building Placement Preview Adjustment
   - Check for Changelog/Documentation/Credits in Pull Requests
-  - Docs dark theme switcher
+  - VitePress documentation migration
   - Fix position and layer of info tip and reveal production cameo on selected building
   - Fix a glitch related to incorrect target setting for missiles
   - Ability to disable shadow for debris & meteor animations

README.md

@@ -3,7 +3,6 @@
 [![Github All Releases](https://img.shields.io/github/downloads/Phobos-developers/Phobos/total.svg)](https://github.com/Phobos-developers/Phobos/releases)
 [![Docs status](https://readthedocs.org/projects/phobos/badge/?version=latest)](https://phobos.readthedocs.io/en/latest/?badge=latest)
 [![Workflow](https://img.shields.io/github/actions/workflow/status/Phobos-developers/Phobos/nightly.yml?branch=develop)](https://github.com/Phobos-developers/Phobos/actions)
-[![EditorConfig](https://github.com/Phobos-developers/Phobos/workflows/EditorConfig/badge.svg)](https://github.com/Phobos-developers/Phobos/actions?query=workflow%3AEditorConfig)
 [![license](https://img.shields.io/github/license/Phobos-developers/Phobos.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
 
 > **Warning**
@@ -59,7 +58,7 @@ Documentation
 - [Community Chinese docs](https://docs.qq.com/doc/p/dc3da1ce39a6e787b6e133f7d33d6aebef581cb4)
   - Because the Chinese translation of the official docs is currently underdeveloped, at the time it is recommended to use the community docs for Chinese users.
 
-You can switch between versions (displays latest develop nightly version by default) in the bottom right corner, as well as download a PDF version.
+You can switch between versions (displays latest develop nightly version by default) in the bottom right corner, as well as download a zipped offline HTML version.
 
 The documentation is split by a few major categories, each represented with a page on the sidebar. Each page has its contents grouped into multiple subcategories, be it buildings, technotypes, infantry, superweapons or something else.
 

docs/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*.{css,js,ts,json,md,po,vue}]
+charset = utf-8
+end_of_line = crlf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2

docs/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+
+.vitepress/cache/
+.vitepress/.temp/
+.vitepress/config.ts.*.mjs
+/vitepress/generated/
+
+/.artifacts/

docs/.prettierrc

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "quoteProps": "consistent",
+  "arrowParens": "avoid",
+  "endOfLine": "crlf"
+}

docs/.vitepress/config.ts

@@ -0,0 +1,104 @@
+import { defineConfig } from 'vitepress'
+import type { PluginOption } from 'vite'
+import {
+  generatePoLocalePages,
+  getPoLocaleRewrites,
+  poLocalePlugin,
+} from '../vitepress/build-scripts/vitepress-po-locale-plugin.ts'
+import {
+  generateRootPages,
+  getRootPageRewrites,
+  rootPagesPlugin,
+} from '../vitepress/build-scripts/vitepress-root-pages-plugin.ts'
+import { createLastUpdatedTransform } from '../vitepress/build-scripts/vitepress-last-updated.ts'
+import { offlineVitePressPlugin } from '../vitepress/build-scripts/vitepress-offline-plugin.ts'
+import { mediaDimensionsPlugin } from '../vitepress/build-scripts/media-dimensions-plugin.ts'
+import { artifactsDistDir, outputDir as offlineOutputDir } from '../vitepress/build-scripts/shared/offline.ts'
+import { getEditLink } from './edit-link.ts'
+import { sphinxDirectiveFencePlugin } from './markdown/sphinx-directive-fence-plugin.ts'
+import { staticPublicDirMarkdownPlugin } from './markdown/static-public-dir-markdown-plugin.ts'
+import { renderSearchContent } from './search/local-search-renderer.ts'
+import { createLocaleConfig, englishNav, englishSidebar } from './theme-config.ts'
+
+const isOfflineBuild = process.env.DOCS_VITEPRESS_OFFLINE === '1'
+const vitePressBase = process.env.READTHEDOCS_CANONICAL_URL
+  ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/u, '')
+  : '/'
+const rootPages = await generateRootPages()
+const poLocalePages = await generatePoLocalePages({ sourcePages: rootPages })
+const rootPageRewrites = getRootPageRewrites(rootPages)
+const poLocaleRewrites = await getPoLocaleRewrites(poLocalePages)
+const transformPageData = createLastUpdatedTransform({ rootPages, localePages: poLocalePages })
+const vitePlugins: PluginOption[] = [
+  staticPublicDirMarkdownPlugin,
+  mediaDimensionsPlugin(),
+  rootPagesPlugin(),
+  poLocalePlugin({
+    sourcePages: rootPages,
+    prepareSources: generateRootPages,
+  }),
+]
+
+if (isOfflineBuild) {
+  vitePlugins.push(offlineVitePressPlugin())
+}
+
+export default defineConfig({
+  title: 'Phobos Documentation',
+  description: 'Community documentation for Phobos YR engine extension',
+  base: vitePressBase,
+  outDir: isOfflineBuild ? offlineOutputDir : artifactsDistDir,
+  cleanUrls: false,
+  lastUpdated: true,
+  ignoreDeadLinks: true,
+  transformPageData,
+  markdown: {
+    config(md) {
+      md.use(sphinxDirectiveFencePlugin)
+    },
+  },
+  rewrites: {
+    ...rootPageRewrites,
+    ...poLocaleRewrites,
+  },
+  vite: {
+    publicDir: '_static',
+    plugins: vitePlugins,
+  },
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico', type: 'image/x-icon' }],
+    ['link', { rel: 'shortcut icon', href: '/favicon.ico' }],
+    ['link', { rel: 'icon', href: '/favicon.png', type: 'image/png' }],
+    ['link', { rel: 'apple-touch-icon', href: '/favicon.png' }],
+  ],
+  themeConfig: {
+    logo: '/favicon.png',
+    siteTitle: 'Phobos',
+    outline: {
+      level: [2, 3],
+      label: 'On this page',
+    },
+    nav: englishNav,
+    sidebar: englishSidebar,
+    search: {
+      provider: 'local',
+      options: {
+        _render: renderSearchContent,
+      },
+    },
+    editLink: {
+      pattern: getEditLink,
+      text: 'Edit this page',
+    },
+    socialLinks: [{ icon: 'github', link: 'https://github.com/Phobos-developers/Phobos' }],
+  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en-US',
+    },
+    zh_CN: {
+      ...(await createLocaleConfig('zh_CN', 'Simplified Chinese', 'zh-CN')),
+    },
+  },
+})

docs/.vitepress/edit-link.ts

@@ -0,0 +1,27 @@
+export function getEditLink({ filePath }: { filePath: string }) {
+  const repositoryEditRootUrl = 'https://github.com/Phobos-developers/Phobos/edit/develop/'
+  const getPoPathForGeneratedLocalePage = (locale: string, pagePath: string) => {
+    if (pagePath === 'README.md') {
+      return `docs/locale/${locale}/LC_MESSAGES/index.po`
+    }
+
+    if (pagePath.endsWith('/README.md')) {
+      return `docs/locale/${locale}/LC_MESSAGES/${pagePath.replace(/\/README\.md$/u, '/index.po')}`
+    }
+
+    return `docs/locale/${locale}/LC_MESSAGES/${pagePath.replace(/\.md$/u, '.po')}`
+  }
+
+  const rootPage = filePath.match(/^vitepress\/generated\/root\/(.+)$/u)
+  if (rootPage) {
+    const sourcePath = rootPage[1] === 'License.md' ? 'LICENSE.md' : rootPage[1]
+    return `${repositoryEditRootUrl}${sourcePath}`
+  }
+
+  const localePage = filePath.match(/^vitepress\/generated\/locales\/([^/]+)\/(.+)$/u)
+  if (localePage) {
+    return `${repositoryEditRootUrl}${getPoPathForGeneratedLocalePage(localePage[1], localePage[2])}`
+  }
+
+  return `${repositoryEditRootUrl}docs/${filePath}`
+}