mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-17 19:55:34 +00:00
Lunny Xiaoandbircni
b137a0e0e1
Replace [#307](https://gitea.com/gitea/docs/issues/307) Closes [#237](https://gitea.com/gitea/docs/issues/237) ## Summary Rebuilds docs.gitea.com with [Astro](https://astro.build) and [Starlight](https://starlight.astro.build), replacing Docusaurus. Every published url keeps working and no content file was moved: the site is a new rendering layer over the existing `docs/`, `versioned_docs/`, `i18n/`, `runner-docs/` and `static/swagger-*.json` trees. For the first time the API reference is part of the site rather than a Redoc bundle: all seven swagger documents are rendered into real pages, one per operation, so they are linkable, crawlable and searchable. ## Why - the Docusaurus build needs an 8 GB heap and about 2 minutes for 2478 pages; the Astro build produces 5751 pages, API reference included, in about 100 seconds - the API reference was a single client rendered Redoc page per version, absent from the site search and from search engines - sidebars, version lists and language lists were configured in three different places and drifted apart ## What is in here - **`packages/content-loader`** — the product × version × language matrix (`products.ts`) and an Astro content loader that reads the existing markdown trees directly. The matrix is the single source of truth: content loading, sidebars, the version and language pickers, the version banner, the search facets and the API schemas are all derived from it. - **Content compatibility** — frontmatter `slug`, `sidebar_position` and `sidebar_label` keep working, `_category_.json` still drives sidebar labels, order and the generated category pages, `@version@` style release variables are still substituted, `:::note` admonitions become Starlight asides and the 2778 relative `*.md` links are rewritten to urls while the site is built. - **API reference** — `starlight-openapi` renders the seven swagger documents. Operation urls are hyphenated (`/api/operations/list-admin-workflow-jobs/`), the sidebar shows the operations of the version being read with a coloured HTTP method badge, and the overview page links to one page per tag instead of repeating all 484 operations. - **Navigation** — a version picker that follows the reader to the same page in another version, a language picker that only offers the languages the current product is published in, and product links for Docs, API, Runner and Enterprise. - **Theme** — the light and dark palettes of about.gitea.com, mapped onto the Starlight variables. - **Search** — Pagefind by default; Algolia DocSearch takes over when `PUBLIC_DOCSEARCH_APP_ID` and `PUBLIC_DOCSEARCH_API_KEY` are set. Every page carries `docsearch:product`, `docsearch:version` and `docsearch:language` meta tags, so a search stays inside what is being read. `cloudflare/docsearch-crawler.json` holds the crawler configuration. ## Bugs fixed along the way - `GET /user/applications/oauth2` and `GET /user/applications/oauth2/{id}` have operation ids that only differ in case, so they collapsed onto the same url and one of the two pages was silently dropped. They are now `user-get-oauth2-application` and `user-get-oauth2-application-by-id`. - The API overview and every tag page were all titled "Overview". ## Url compatibility The routes of both builds were compared page by page during the migration with `scripts/url-diff.mjs`: ``` identical: 2368, missing: 0, accepted: 110, added: 3292 ``` The 110 accepted ones are all redirected in `cloudflare/_redirects`: the localized copies of the English-only API and Runner docs, the Docusaurus search page, and `/1.27/`, `/runner/3/`, `/api/1.27/` which are aliases of the versions served at the product root. The added ones are the API operation and tag pages plus the routes the Starlight language fallback serves in English when a translation is missing — Docusaurus answered those with a 404. ## Workflows - `checks` builds the site and type checks it on every pull request - `Build and Publish Docs site` publishes `sites/docs/dist` to S3/CloudFront and to Cloudflare Pages, and copies `cloudflare/_headers` and `cloudflare/_redirects` into the deployment - `update swagger files` and `update runner reference` are unchanged, they only touch content - `make cut-version PRODUCT=docs VERSION=1.28` replaces `docusaurus docs:version` ## Removed `docusaurus.config.js`, the swizzled theme under `src/`, and the Docusaurus UI translations (`i18n/*/code.json`, `i18n/*/docusaurus-theme-classic/`). The strings those carried — the product names, the footer column titles and the outdated translation notice — were ported to `sites/docs/src/config/strings.ts`; Starlight ships the rest of its interface in both Chinese locales. The documentation content itself is untouched. ## Follow ups - nine relative links are broken in the sources and reported by every build, the same ones Docusaurus warned about; `GITEA_DOCS_STRICT_LINKS=true` turns them into an error once they are fixed - `cloudflare/worker.js` has to be deployed for `/enterprise/` to keep resolving - the Algolia index has to be created and crawled before the search credentials are set ## Testing ```shell make install make serve-fast # english, the version served at the root make serve # the whole matrix make build # 5751 pages make check # 0 errors make serve-built # build and serve, the only way to try the search locally ``` ## Screenshots <img width="1371" alt="image.png" src="attachments/69acdd77-cc89-4635-a8bd-1163a34afa86"> <img width="1810" alt="image.png" src="attachments/76212416-4825-4b4d-bf59-3e549900c96f"> <img width="1789" alt="image.png" src="attachments/7be84cda-5abe-48bd-8839-7ae1ee7806e7"> --------- Co-authored-by: bircni <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/496 Reviewed-by: bircni <[email protected]>
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# Gitea Docs 
|
|
|
|
The sources of [docs.gitea.com](https://docs.gitea.com), built with
|
|
[Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
|
|
|
|
The site covers three products, all served from this repository:
|
|
|
|
| Product | Content | Versions | Languages |
|
|
| --- | --- | --- | --- |
|
|
| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
|
|
| API | `static/swagger-*.json` | next, 1.27 … 1.22 | English |
|
|
| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
|
|
|
|
The enterprise documentation is built and deployed from its own repository and
|
|
reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
|
|
routes to that deployment.
|
|
|
|
## Development
|
|
|
|
```shell
|
|
make install # pnpm install
|
|
make serve-fast # english, the version served at the root, starts in seconds
|
|
make serve # the whole matrix, every version and language
|
|
make build # production build into sites/docs/dist
|
|
make check # type checks the site and its components
|
|
```
|
|
|
|
Search is built by Pagefind while the site is built, so it only answers on the
|
|
built site: use `make serve-built` to try it. With the Algolia credentials
|
|
(`PUBLIC_DOCSEARCH_APP_ID`, `PUBLIC_DOCSEARCH_API_KEY`) set, DocSearch is used
|
|
instead and works in `make serve` too.
|
|
|
|
`GITEA_DOCS_PRODUCTS`, `GITEA_DOCS_VERSIONS` and `GITEA_DOCS_LOCALES` (comma
|
|
separated) restrict what is built, which is what `make serve-fast` uses.
|
|
`GITEA_DOCS_STRICT_LINKS=true` turns the warnings about unresolved relative
|
|
markdown links into a build error.
|
|
|
|
`sites/docs/README.md` documents how the sources are mapped onto the site.
|
|
|
|
## Writing
|
|
|
|
Pages are plain markdown with the same frontmatter and admonitions as before:
|
|
frontmatter `slug`, `sidebar_position` and `sidebar_label` keep working, and so
|
|
do the `:::note` style admonitions and the `@version@` style release variables.
|
|
Relative `*.md` links are rewritten to urls while the site is built.
|
|
|
|
The order of the top level sidebar groups comes from `sidebars.js` (and
|
|
`versioned_sidebars/` for released versions), the label and order of every other
|
|
group from the `_category_.json` of its directory.
|
|
|
|
## Cutting a version
|
|
|
|
```shell
|
|
make cut-version PRODUCT=docs VERSION=1.28
|
|
make cut-version PRODUCT=runner VERSION=4
|
|
```
|
|
|
|
This freezes the current tree, its translations and its sidebar. The label of
|
|
the version, its release variables (`@version@`, `@dockerVersion@`, ...) and
|
|
which version is served at the root live in
|
|
`packages/content-loader/src/products.ts` and are edited by hand afterwards.
|
|
That file is the single source of truth for the product, version and language
|
|
matrix.
|
|
|
|
## API docs
|
|
|
|
The swagger definitions rendered under `/api/` live in
|
|
`static/swagger-latest.json` (gitea main) and `static/swagger-<minor>.json`
|
|
(released versions).
|
|
|
|
```shell
|
|
make update-api-docs # refresh latest + every released version
|
|
make update-api-docs-latest # refresh only static/swagger-latest.json
|
|
```
|
|
|
|
`static/swagger-latest.json` is refreshed automatically: the `update swagger
|
|
files` workflow runs every 12 hours and opens a pull request whenever gitea main
|
|
changed. Released versions are updated by hand when a new gitea version is
|
|
documented.
|
|
|
|
## Runner docs
|
|
|
|
| Version | Content | URL |
|
|
| --- | --- | --- |
|
|
| develop | `runner-docs/` | `/runner/develop/` |
|
|
| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
|
|
| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
|
|
|
|
A version directory covers a whole release series (`version-3` documents every
|
|
`3.x` release), so a patch release only needs a content update, not a new
|
|
folder. Use floating image tags (`gitea/runner:3`) and links to the runner's
|
|
`main` branch in those pages to keep them valid across patch releases.
|
|
|
|
Its sidebar is written by hand: `runner-sidebars.js` for develop, and
|
|
`runner-docs_versioned_sidebars/version-<version>-sidebars.json` per documented
|
|
version.
|
|
|
|
The pages under `reference/` are generated from the runner sources — the command
|
|
line reference from `--help`, the example configuration from `generate-config`:
|
|
|
|
```shell
|
|
make update-runner-docs # develop docs, from the main branch of gitea/runner
|
|
make update-runner-docs-released # every series, from its newest stable tag
|
|
./update_runner_docs.sh v3.0.2 runner-docs_versioned_docs/version-3/reference
|
|
```
|
|
|
|
These are refreshed automatically as well: the `update runner reference`
|
|
workflow runs weekly and opens a pull request whenever the runner's CLI or
|
|
example configuration changed. Generating them needs Go, since the script builds
|
|
the runner binary.
|
|
|
|
## Deployment
|
|
|
|
`main` is built and published by the `Build and Publish Docs site` workflow, to
|
|
S3/CloudFront and to Cloudflare Pages. `cloudflare/_headers` sets the cache
|
|
policy and `cloudflare/_redirects` keeps the urls the site used to serve; both
|
|
are copied next to the build output by that workflow.
|
|
`cloudflare/docsearch-crawler.json` is the Algolia crawler configuration.
|
|
|
|
`/enterprise/` is served by another deployment and routed to it by a Cloudflare
|
|
worker that lives outside this repository.
|