nprasad2077/docs

mirror of https://gitea.com/gitea/docs.git synced 2026-09-17 19:55:34 +00:00

Files

T

Lunny Xiaoandbircni b137a0e0e1 Rebuild the site with Astro and Starlight (#496 )

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]>

2026-08-12 20:03:29 +00:00

2.5 KiB

Raw Blame History

date, slug, sidebar_position, aliases

date

slug

sidebar_position

aliases

2018-06-01T19:00:00+02:00

pull-request

/zh-cn/pull-request

合并请求

合并请求(PR)是一种提出对仓库进行更改的方式。它是一种将一个分支合并到另一个分支的请求，附带有对所做更改的描述。合并请求通常用作贡献者对仓库贡献代码的方式，仓库的维护者可以通过对合并请求进行审查来决定是否接受这些更改。

创建合并请求

要创建合并请求，您需要遵循以下步骤：

Fork 仓库 - 如果您没有直接对仓库进行更改的权限，您需要将仓库 fork 到您自己的账户中。这将创建一个您可以对其进行更改的仓库副本。
创建分支（可选） - 在 fork 的仓库中创建一个新分支，该分支包含您要提出的更改。给分支取一个描述性的名称，以指示更改的内容。
进行更改 - 进行您想要的更改，提交并将其推送到 fork 的仓库中。
创建合并请求 - 转到原始仓库并转到“合并请求”选项卡。单击“新建合并请求”按钮，并将您的新分支选择为源分支。为您的合并请求输入描述性标题和描述，然后单击“创建合并请求”。

评审合并请求

创建合并请求后，将触发评审流程。仓库的维护者将收到合并请求的通知，并可以审查所做的更改。他们可以留下评论、请求更改或批准更改。

如果维护者请求更改，您需要在分支中进行这些更改，并将更改推送到 fork 的仓库中。合并请求将自动使用新更改进行更新。

如果维护者批准更改，他们可以将合并请求合并到仓库中。

关闭合并请求

如果您不接受该合并请求，您可以关闭它。要关闭合并请求，请转到打开的合并请求并单击“关闭合并请求”按钮。这将关闭合并请求并且不会将其合并。

使用“Work In Progress”标记

在合并请求中使用“Work In Progress”标记可以防止合并请求被意外合并。要将合并请求标记为“Work In Progress”，您必须在其标题中添加前缀WIP:或[WIP]（不区分大小写）。标记前缀可以在您的app.ini文件中进行配置：

[repository.pull-request]
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]

列表的第一个值将用于 helpers 程序。

合并请求模板

有关合并请求模板的更多信息请您移步 : 工单与合并请求模板

2.5 KiB Raw Blame History