feat: add a cli product for the gt documentation

gt, the Gitea CLI, gets its own product next to the runner: the CLI entry
in the header, its own sidebars, search scope, crawler start url and
redirects, and `make cut-version PRODUCT=cli`. Until a release series is
listed, the develop docs are served at /cli/ without the unreleased banner.

A directory with an index page and no _category_.json now takes its
sidebar label and position from that page, which leads the group, so the
generated reference can be grouped by command.

Signed-off-by: bircni <[email protected]>

sites/docs/README.md

@@ -1,12 +1,13 @@
 # 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
+the docs (6 versions x 3 languages), the runner docs (4 series), the gt (Gitea
+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
+`versioned_docs/`, `i18n/`, `runner-docs/`, `runner-docs_versioned_docs/`,
+`cli-docs/` and
 `static/swagger-*.json` (plus `static/openapi3-*.json` since gitea 1.27) — so
 the release scripts and the translation workflow stay unchanged.
 
@@ -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,10 @@ 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. A directory without `_category_.json` takes the label and the
+position of its `index` page, which the generated cli reference relies on.
 
 Set `GITEA_DOCS_STRICT_LINKS=true` to fail the build on a broken internal link
 instead of warning.
@@ -69,9 +73,9 @@ 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
+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.

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/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,18 +42,18 @@ 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`;
       }
     }
   }
 
   for (const [key, file] of Object.entries(files)) {
     const config = read(file);
-    const items = config && (config.docs ?? config.runner ?? Object.values(config)[0]);
+    const items = config && (config.docs ?? config.runner ?? config.cli ?? Object.values(config)[0]);
     if (items) sidebars.set(key, items);
   }
   return sidebars;

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(),