Add documentation for gt, the Gitea CLI (#603)

Adds a CLI product for gt (https://gitea.com/gitea/cli), set up like the runner, with short guides for installation, logging in, CI and scripting. Each command's details stay in gt <command> --help. Until the first release, the docs are served at /cli/; make cut-version PRODUCT=cli VERSION=0.1 adds the release series.

Closes https://gitea.com/gitea/cli/issues/16

<!-- cloudflare-preview --> Preview: https://pr-603.docs-gitea-com.pages.dev

---------

Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/603
Reviewed-by: Lunny Xiao <[email protected]>
Reviewed-by: silverwind <[email protected]>

sites/docs/README.md

@@ -1,14 +1,15 @@
 # Astro + Starlight site
 
 Renders the gitea documentation with [Starlight](https://starlight.astro.build):
-the docs (6 versions x 3 languages), the runner docs (4 series) and the api
-reference (7 swagger documents). The enterprise docs stay in their own
-deployment and are linked from the header.
+the docs (6 versions x 3 languages), the runner docs (4 series), the cli docs
+and the api reference (7 swagger documents). The enterprise docs stay in their
+own deployment and are linked from the header.
 
 The content directories are the ones the site has always used — `docs/`,
 `versioned_docs/`, `i18n/`, `runner-docs/`, `runner-docs_versioned_docs/` and
 `static/swagger-*.json` (plus `static/openapi3-*.json` since gitea 1.27) — so
-the release scripts and the translation workflow stay unchanged.
+the release scripts and the translation workflow stay unchanged. The cli docs
+in `cli-docs/` follow the layout of the runner docs.
 
 ## Running it
 
@@ -40,6 +41,7 @@ pickers, the version banner, the search facets and the api schemas.
 | `i18n/zh-cn/docs/version-1.27/` | `/zh-cn/` |
 | `runner-docs_versioned_docs/version-3/` | `/runner/` |
 | `runner-docs/` | `/runner/develop/` |
+| `cli-docs/` | `/cli/`, until a cli series is released |
 | `static/openapi3-27.json` | `/api/` |
 | `static/openapi3-latest.json` | `/api/next/` |
 | `static/swagger-26.json` | `/api/1.26/` |
@@ -60,8 +62,9 @@ of every file, the second normalizes and renders it:
 
 Sidebars are built per (product, version, language) from `_category_.json` and
 from the sidebar files (`sidebars.js`, `versioned_sidebars/`,
-`runner-sidebars.js`, `runner-docs_versioned_sidebars/`), and selected in
-`src/routeData.ts`, since starlight only supports a single static sidebar.
+`runner-sidebars.js`, `runner-docs_versioned_sidebars/`, `cli-sidebars.js`),
+and selected in `src/routeData.ts`, since starlight only supports a single
+static sidebar.
 
 Set `GITEA_DOCS_STRICT_LINKS=true` to fail the build on a broken internal link
 instead of warning.
@@ -69,12 +72,12 @@ instead of warning.
 ## Products and languages
 
 The docs are the site itself, so their language comes first: `/zh-cn/1.26/`.
-The runner and the api are separate products and keep their language inside the
-product, `/runner/zh-cn/3/`, which is reserved: both are published in english
-only today. Starlight builds a fallback page in every configured language for
-every english page, so `/zh-cn/runner/` would exist; the post build integration
-removes those directories and `cloudflare/_redirects` sends them to the
-english page.
+The runner, the cli and the api are separate products and keep their language
+inside the product, `/runner/zh-cn/3/`, which is reserved: all are published in
+english only today. Starlight builds a fallback page in every configured
+language for every english page, so `/zh-cn/runner/` would exist; the post build
+integration removes those directories and `cloudflare/_redirects` sends them to
+the english page.
 
 The version served at the root of a product has no number in its url: docs 1.27
 is `/`, runner 3 is `/runner/` and api 1.27 is `/api/`. `/1.27/`, `/runner/3/`

sites/docs/src/config/strings.ts

@@ -23,7 +23,7 @@ type Strings = {
 const en: Strings = {
   versionLabel: 'Version',
   languageLabel: 'Language',
-  products: { docs: 'Docs', api: 'API', runner: 'Runner', enterprise: 'Enterprise' },
+  products: { docs: 'Docs', api: 'API', runner: 'Runner', cli: 'CLI', enterprise: 'Enterprise' },
   footer: { Community: 'Community', Code: 'Code', More: 'More' },
   signIn: 'Sign In',
   translationNotice: 'This translation may be behind the english original.',
@@ -41,7 +41,7 @@ const strings: Record<string, Strings> = {
   'zh-cn': {
     versionLabel: '版本',
     languageLabel: '语言',
-    products: { docs: '文档', api: 'API', runner: 'Runner', enterprise: '企业版' },
+    products: { docs: '文档', api: 'API', runner: 'Runner', cli: 'CLI', enterprise: '企业版' },
     footer: { Community: '社区', Code: '开源代码', More: '更多' },
     signIn: '登录',
     translationNotice: '当前中文文档翻译不是最新版，访问英文版本查看最新内容，或',
@@ -56,7 +56,7 @@ const strings: Record<string, Strings> = {
   'zh-tw': {
     versionLabel: '版本',
     languageLabel: '語言',
-    products: { docs: '文件', api: 'API', runner: 'Runner', enterprise: '企業版' },
+    products: { docs: '文件', api: 'API', runner: 'Runner', cli: 'CLI', enterprise: '企業版' },
     footer: { Community: '社區', Code: '開源程式碼', More: '更多' },
     signIn: '登入',
     translationNotice: '當前中文文檔翻譯不是最新版，訪問英文版本查看最新內容，或',

sites/docs/src/integrations/postbuild.ts

@@ -11,9 +11,9 @@ import { defaultLocale, locales, products, type LocaleId } from '@gitea-docs/con
  *   generated as `/api/126/`. The directories are renamed and the links inside
  *   the build are rewritten.
  * - starlight builds a fallback page in every configured language for every
- *   english page. That is what we want for the docs, but the runner and the api
- *   are separate products with their own language list, so `/zh-cn/runner/` has
- *   to go; `cloudflare/_redirects` sends it to the english page.
+ *   english page. That is what we want for the docs, but the other products
+ *   have their own language list, so `/zh-cn/runner/` has to go;
+ *   `cloudflare/_redirects` sends it to the english page.
  */
 export function giteaPostBuild(): AstroIntegration {
   return {

sites/docs/src/lib/pagefind-ui.ts

@@ -90,7 +90,7 @@ function addScopeToggle(root: HTMLElement, onChange: (allVersions: boolean) => v
 
 /**
  * While all versions are searched the same page shows up once per version, so
- * the version (and the product, for the api and the runner) is appended to the
+ * the version (and the product, for every product but the docs) is appended to the
  * title of a result.
  */
 function labelResult(result: PagefindResult): void {

sites/docs/src/lib/sidebars.ts

@@ -12,9 +12,9 @@ import { getCollection } from 'astro:content';
 import { repoRoot } from '../config/paths';
 
 /**
- * Sidebar files: the top level order of the docs and the
- * handwritten sidebars of the runner, one per version. Read as is, so cutting a
- * version keeps needing no change here.
+ * Sidebar files: the top level order of the docs and the handwritten sidebars
+ * of the runner and the cli, one per version. Read as is, so cutting a version
+ * keeps needing no change here.
  */
 function sidebarSources(): Map<string, SidebarSourceItem[]> {
   const sidebars = new Map<string, SidebarSourceItem[]>();
@@ -42,11 +42,11 @@ function sidebarSources(): Map<string, SidebarSourceItem[]> {
           version.id === 'next'
             ? 'sidebars.js'
             : `versioned_sidebars/version-${version.id}-sidebars.json`;
-      } else if (product.id === 'runner') {
-        files[`runner@${version.id}`] =
+      } else if (product.id === 'runner' || product.id === 'cli') {
+        files[`${product.id}@${version.id}`] =
           version.id === 'develop'
-            ? 'runner-sidebars.js'
-            : `runner-docs_versioned_sidebars/version-${version.id}-sidebars.json`;
+            ? `${product.id}-sidebars.js`
+            : `${product.id}-docs_versioned_sidebars/version-${version.id}-sidebars.json`;
       }
     }
   }

sites/docs/src/schema.ts

@@ -7,7 +7,7 @@ import { z } from 'astro:content';
  * per version sidebars, the version and language pickers and the search facets.
  */
 export const giteaMeta = z.object({
-  product: z.enum(['docs', 'api', 'runner', 'enterprise']),
+  product: z.enum(['docs', 'api', 'runner', 'cli', 'enterprise']),
   version: z.string(),
   locale: z.string(),
   prefix: z.string(),