A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
Building the Estella Docs Site
The published documentation site (estellaengine.com/docs)
is built with Astro Starlight (guides), TypeDoc (TypeScript API reference,
generated at build time from the SDK's public barrels via starlight-typedoc —
the pages land in docs/astro/src/content/docs/api-ts/, which is gitignored) and
Doxygen (C++ API reference), merged into a single static bundle.
The Starlight site lives in docs/astro/ and the landing page in docs/landing/.
The Doxygen API version (PROJECT_NUMBER) is injected at build time from
desktop/package.json (the single app-version source) via the ESTELLA_VERSION
environment variable — see build.sh, build.ps1, and
.github/workflows/docs.yml.
Structure
docs/
├── astro/ # Astro Starlight documentation site
│ ├── src/content/ # MDX documentation files
│ ├── src/assets/ # Images and assets
│ └── package.json # Node dependencies
├── landing/ # Landing page + static site assets
├── api/ # Doxygen output (generated)
├── Doxyfile # Doxygen configuration
├── build.sh # Build script (Linux/macOS)
├── build.ps1 # Build script (Windows)
└── dist/ # Final merged output (generated)
Prerequisites
- Node.js 18+ (for Astro)
- Doxygen (for API docs)
Installing Doxygen
Windows:
choco install doxygen.install
# or download from https://www.doxygen.nl/download.html
macOS:
brew install doxygen
Linux:
sudo apt install doxygen # Debian/Ubuntu
sudo dnf install doxygen # Fedora
Quick Start
Development (Hot Reload)
# Windows
.\build.ps1 dev
# Linux/macOS
./build.sh dev
Opens http://localhost:4321 with live reload.
Full Build
# Windows
.\build.ps1 build
# Linux/macOS
./build.sh build
This will:
- Build Doxygen API documentation →
docs/api/ - Build Astro site →
docs/astro/dist/ - Merge everything →
docs/dist/
Writing Documentation
The one structural rule
A page's directory path is its sidebar path is its URL. A sidebar group is a
directory (editor/, scripting/, graphics/, …); a subgroup inside one is a
directory inside it (gameplay/ai/); and a group's general page is
<dir>/overview.mdx, labelled Overview in the sidebar because the group
header already says the topic — its title stays descriptive, since that is the
page's own heading. Nothing else decides where a file goes.
Depth is free: images are referenced through the @/ alias
(), not by counting ../, so a page can move
between levels without its pictures going dark.
Adding a New Guide
- Create the
.mdxunder the group it belongs to — sections today aregetting-started,editor,core-concepts,scripting,graphics,animation,gameplay,ui,world,assets,publishing,performance,extendingandreference. - Add frontmatter:
--- title: My Guide description: A brief description --- Your content here... - Add it to the matching sidebar group in
astro/astro.config.mjs, and write the Simplified Chinese page atastro/src/content/docs/zh-cn/<same path>.mdx. - If you move or rename a page, append its old path to
MOVEDinastro/astro.config.mjs. That map is append-only — a URL published once keeps resolving.
The gates
Three checks keep the site honest; all three run in CI, and all three are worth running locally before a docs PR.
| Check | Run from | Catches |
|---|---|---|
npm run verify:imports |
docs/astro |
A guide importing a symbol the SDK does not export — a renamed or invented API. Runs before the build. |
npm run verify:structure |
docs/astro |
The rule above going soft: a page in no sidebar group, a sidebar entry with no page, a group page not labelled Overview, or a page that exists in only one language. Runs before the build. |
npm run verify:links |
docs/astro |
Any in-site link or #anchor that does not resolve against the pages the build emitted, including a root-relative link that forgot the /docs base. Runs after the build. |
node tools/component-reference.mjs --check |
repo root | The component reference disagreeing with the engine's component registry, or a component with no entry in src/data/componentDocs.ts. Part of pnpm run verify. Refresh with --update after building the SDK. |
Available Components
Starlight provides several built-in components:
import { Tabs, TabItem, Card, CardGrid, Aside, Steps } from '@astrojs/starlight/components';
<Aside type="tip">
Helpful tip here
</Aside>
<Tabs>
<TabItem label="Tab 1">Content 1</TabItem>
<TabItem label="Tab 2">Content 2</TabItem>
</Tabs>
<Steps>
1. First step
2. Second step
</Steps>
Code Blocks
```cpp title="example.cpp" {3-5}
int main() {
// This line is highlighted
Application app;
app.run();
return 0;
}
```
Deployment
GitHub Actions (Automatic)
The site is built and deployed by .github/workflows/docs.yml when a docs-v*
tag is pushed or the workflow is dispatched manually. The workflow:
- Builds Doxygen API documentation
- Builds the Astro site
- Merges and deploys to GitHub Pages
Setting up GitHub Pages:
- Go to repository Settings → Pages
- Set Source to "GitHub Actions"
- Push a
docs-v*tag (or run the workflow manually) to trigger deployment
Manual Deployment
Build locally and deploy anywhere:
./build.sh build # or .\build.ps1 build on Windows
Copy docs/dist/ to any static host:
- Vercel
- Netlify
- Cloudflare Pages
- Any web server
Updating API Docs
API documentation is generated from source-code comments. To update:
- Add or update Doxygen comments in the source (see CODE_COMMENTS.md)
- Run
./build.sh doxygen
Doxygen Comment Format
/**
* @brief Brief description
* @details Longer description with more details.
*
* @param paramName Description of parameter
* @return Description of return value
*
* @code
* // Example usage
* MyClass obj;
* obj.method();
* @endcode
*/
void MyClass::method(int paramName);