|
1 | | -# Website |
| 1 | +# GoZen website |
2 | 2 |
|
3 | | -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. |
| 3 | +The project site for [gozen.dev](https://gozen.dev): a home page and the |
| 4 | +documentation, in eleven languages. |
4 | 5 |
|
5 | | -## Installation |
| 6 | +Built with React 19 and Vite, on the same architecture as the other dopejs |
| 7 | +sites. Routes are language-neutral and pre-rendered to static HTML; every |
| 8 | +translation ships in the page payload and the visitor's language is resolved on |
| 9 | +the client. |
6 | 10 |
|
7 | | -```bash |
8 | | -yarn |
9 | | -``` |
| 11 | +## Develop |
10 | 12 |
|
11 | | -## Local Development |
| 13 | +Prerequisites: Node.js 22+, pnpm 10+. |
12 | 14 |
|
13 | 15 | ```bash |
14 | | -yarn start |
| 16 | +pnpm install |
| 17 | +pnpm dev # http://localhost:5173 |
| 18 | +pnpm typecheck # must stay at zero errors |
| 19 | +pnpm build # static output in dist/ |
| 20 | +pnpm preview |
15 | 21 | ``` |
16 | 22 |
|
17 | | -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. |
18 | | - |
19 | | -## Build |
| 23 | +`pnpm build` runs the client build, then an SSR build, then renders each route |
| 24 | +to static HTML with its payload embedded, and finally writes the sitemap. |
20 | 25 |
|
21 | | -```bash |
22 | | -yarn build |
23 | | -``` |
| 26 | +## Content |
24 | 27 |
|
25 | | -This command generates static content into the `build` directory and can be served using any static contents hosting service. |
| 28 | +Documents live in `content/`: English at the root, every other locale in |
| 29 | +`content/<locale>/`. Order and grouping in the sidebar come from |
| 30 | +`src/sidebar.ts`, not from the file system. Markdown is compiled by |
| 31 | +`content.mjs` with markdown-it, and code fences are highlighted at build time by |
| 32 | +Shiki, so no highlighter is shipped to the browser. |
26 | 33 |
|
27 | | -## Deployment |
| 34 | +Interface strings live in `src/i18n/<locale>.json`, keyed the same way across |
| 35 | +locales; English is the source and any missing key falls back to it. |
28 | 36 |
|
29 | | -Using SSH: |
| 37 | +To translate a document, use the helper rather than editing by hand: |
30 | 38 |
|
31 | 39 | ```bash |
32 | | -USE_SSH=true yarn deploy |
| 40 | +python3 tools/translate-doc.py <slug> <locale> <map.json> |
33 | 41 | ``` |
34 | 42 |
|
35 | | -Not using SSH: |
| 43 | +It copies code fences verbatim and fails if any prose line is missing from the |
| 44 | +map, so a file cannot ship half-translated by accident. |
36 | 45 |
|
37 | | -```bash |
38 | | -GIT_USER=<Your GitHub username> yarn deploy |
39 | | -``` |
| 46 | +> Translations are machine-generated and have not been reviewed by native |
| 47 | +> speakers. Replacing any file under `content/<locale>/` with a reviewed |
| 48 | +> translation needs no code change. |
| 49 | +
|
| 50 | +## Language preference |
| 51 | + |
| 52 | +There are no per-language URLs. `src/language-preference.ts` resolves the |
| 53 | +language from `localStorage["dopejs.locale"]`, then the `dopejs_locale` cookie, |
| 54 | +then `navigator.languages`. The module is shared with the dopejs.com sites, but |
| 55 | +gozen.dev is a different registrable domain, so the cookie stays host-only here |
| 56 | +and the preference does not follow visitors between the two. |
| 57 | + |
| 58 | +## Deploy |
40 | 59 |
|
41 | | -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. |
| 60 | +Pushing to `main` runs `.github/workflows/pages.yml`, which type-checks, builds |
| 61 | +and publishes `dist/` to GitHub Pages. |
0 commit comments