mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-17 19:55:34 +00:00
main
3
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Lunny Xiao
|
362878dfba |
Redirect the legacy docs urls the s3 bucket used to serve (#507)
## Problem `https://docs.gitea.com/help/seek-help` returns 404. It is still linked as the *Support* item of the blog.gitea.com navbar, and it is not the only url in that state: `/usage/webhooks`, `/usage/agit`, `/usage/protected-tags` and `/usage/repo-mirror` are linked from gitea itself and 404 as well. ## Root cause Not a rendering problem of the new site: those pages were moved years ago. `docs/help/seek-help.md` became `docs/help/support.md` in 2023 (`slug: support`), and the flat `/usage/<page>`, `/advanced/<page>`, `/developers/<page>` layout of 1.19 and 1.20 was reorganized into `usage/repository/`, `administration/` and `development/`. The old urls kept working because the site was published to S3 with `aws s3 sync` **without** `--delete`: every page built before a move stayed in the bucket and CloudFront kept serving it. The archived copy of `/help/seek-help` still carries `last-modified: Wed, 12 Jul 2023` - the file was six years stale but reachable. The Astro deployment publishes to Cloudflare Pages, which only serves what the current build emits, so all of those leftovers disappeared at once. I crawled the urls the Wayback Machine has for `docs.gitea.com` and checked them against the live site: 335 non-removed-version urls 404 today, and they are all of this kind. ## Fix 301s in `cloudflare/_redirects`, from every legacy url that has a current equivalent to that page, generated for the root, the `zh-cn` and `zh-tw` prefixes and the `next` (develop) version. Also the runner docs that were published under a full version number (`/runner/0.2.11/`, `/runner/1.0.8/`) and `/runner/next/`, which is `/runner/develop/` now. Checked while generating them, against a full local build: - no rule shadows a page that exists today - the zh translations of `usage/agit` and `usage/profile-readme` were never moved, so they are still served at the old path and are left alone - every target resolves to a page that exists, in the language and version the rule redirects within - no duplicated source, 417 static and 10 dynamic rules, well inside the Cloudflare Pages limits (2100 / 100) ## Out of scope - `/contributing/*`, `/developers/guidelines-*` and `/developers/hacking-on-gitea` 404 too, but those pages moved to the gitea repository, there is nothing on docs.gitea.com to point them at. - The `aliases:` frontmatter of the sources (`/en-us/seek-help`, `/webhooks`, ...) is a leftover of the Hugo site. Docusaurus ignored it and so does the Astro build; those urls have been 404 for years and are not resurrected here. - The blog.gitea.com navbar should link to `/help/support` directly, that needs a pull request against gitea/blog. Reviewed-on: https://gitea.com/gitea/docs/pulls/507 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]> |
||
|
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]> |
||
|
Lunny Xiao
|
31c6782d0c |
Add Cloudflare Pages cache headers for static assets (gitea/docs#473)
Co-authored-by: Lunny Xiao <[email protected]> |