nprasad2077/docs
1
1
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-04 09:15:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: drop the remaining docusaurus names from identifiers and comments (#589)

Browse Source 
Follow-up to #588.

- rename `DocusaurusSidebarItem` -> `SidebarSourceItem`, `fromDocusaurus` -> `fromSidebarSource`, `docusaurusSidebars` -> `sidebarSources`
- reword comments and READMEs that described behaviour by comparison with docusaurus; fix the stale note in `sites/docs/src/config/api.ts`
- drop `.docusaurus/` from `.gitignore`

No functional change. `pnpm check` has 0 errors and `pnpm build` still builds 6690 pages.

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

Reviewed-on: https://gitea.com/gitea/docs/pulls/589
Reviewed-by: silverwind <[email protected]>
This commit is contained in:
Lunny Xiao
2026-10-15 17:39:24 +00:00
parent 2275bef3bd
commit b555a247e0
15 changed files with 46 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/content-loader/src/categories.ts
+2 -2
View File
@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
import path from 'node:path';
import type { Segment } from './segments.js';
/** `_category_.json`, the docusaurus per directory sidebar metadata. */
/** `_category_.json`, the per directory sidebar metadata. */
export interface CategoryMeta {
label?: string;
position?: number;
@@ -41,7 +41,7 @@ export function slugifyLabel(label: string): string {
}
/**
* Route id of the index page docusaurus generates for a category.
* Route id of the index page generated for a category.
*
* Top level categories are declared by `sidebars.js` without a slug and end up
* under `/category/<label>`; nested ones keep the slug of their
packages/content-loader/src/index.ts
+4 -4
View File
@@ -74,7 +74,7 @@ const transformVersion = '2';
/**
* Loads the gitea documentation straight out of the content directories, which
* keep the layout the docusaurus site used, instead of copying them into
* keep their original layout, instead of copying them into
* `src/content/docs`. Every source file is mapped to its final route by the
* product matrix, so the release and translation workflows are untouched.
*/
@@ -190,7 +190,7 @@ async function parseFile(
const substituted = applyVariables(contents, segment.version.variables);
const { frontmatter, body: rawBody } = splitFrontmatter(substituted);
// a translated `slug` moves the page, exactly like it did under docusaurus
// a `slug` moves the page
const id = routeIdOf(segment, routeSuffix(segment, file, asString(frontmatter.slug)));
const { title: headingTitle, body } = extractTitle(rawBody);
const title = asString(frontmatter.title) ?? headingTitle;
@@ -289,7 +289,7 @@ async function renderPage(
return broken;
}
/** The index page docusaurus generated for a category. */
/** The index page generated for a category. */
interface ParsedCategory {
segment: Segment;
id: string;
@@ -301,7 +301,7 @@ interface ParsedCategory {
}
/**
* Recreates the index pages docusaurus generated from `_category_.json`, so
* Recreates the index pages generated from `_category_.json`, so
* that `/category/installation/` and `/usage/actions/` keep resolving.
*/
async function resolveCategories(
packages/content-loader/src/links.ts
+2 -2
View File
@@ -1,6 +1,6 @@
/**
* Rewrites the relative markdown links of the sources to the urls of the built
* site. Docusaurus resolved `../administration/config-cheat-sheet.md` against
* site. A link such as `../administration/config-cheat-sheet.md` is resolved against
* the directory of the file it appeared in; astro serves urls, so the target
* has to be looked up in the route table of the version.
*/
@@ -35,7 +35,7 @@ function rewriteTarget(target: string, context: LinkContext): string {
const [pathname = '', hash = ''] = splitHash(target);
if (!/\.mdx?$/.test(pathname)) return target;
// docusaurus resolved a link against the directory of the file first and
// a link is resolved against the directory of the file first and
// against the root of the version second, both spellings are in the sources
const route =
context.resolve(normalize(`${context.dir}/${pathname}`)) ?? context.resolve(normalize(pathname));
packages/content-loader/src/markdown.ts
+3 -3
View File
@@ -16,8 +16,8 @@ export function splitFrontmatter(contents: string): ParsedFile {
}
/**
* Replaces the `@name@` placeholders with the values of the version, the same
* substitution the docusaurus markdown preprocessor did.
* Replaces the `@name@` placeholders with the values of the version, which
* is how the versioned docs reference release specific values.
*/
export function applyVariables(contents: string, variables?: VersionVariables): string {
if (!variables) return contents;
@@ -45,7 +45,7 @@ export function extractTitle(body: string): { title?: string; body: string } {
}
/**
* Docusaurus admonitions to starlight asides. The two vocabularies overlap for
* Admonitions (`:::note`) to starlight asides. The two vocabularies overlap for
* `note`, `tip`, `caution` and `danger`; `warning` and `info` have to be mapped
* and titles move from `:::note Title` to `:::note[Title]`.
*/
packages/content-loader/src/products.ts
+1 -1
View File
@@ -60,7 +60,7 @@ export interface ProductDef {
/** Languages the product is published in, in display order. */
locales: LocaleId[];
versions: VersionDef[];
/** Recreate the docusaurus `_category_.json` index pages for the product. */
/** Recreate the `_category_.json` index pages for the product. */
categoryPages?: boolean;
/** Set for products served by another deployment (enterprise). */
externalBaseUrl?: string;
packages/content-loader/src/segments.ts
+2 -3
View File
@@ -84,7 +84,7 @@ export function segmentOf(segments: Segment[], file: string): Segment | undefine
}
/**
* Route id of a source file, mirroring the docusaurus routing rules:
* Route id of a source file, following these rules:
* `index` files address their directory, a relative `slug` replaces the last
* path segment and `slug: /` addresses the root of the version.
*/
@@ -106,8 +106,7 @@ export function routeSuffix(segment: Segment, file: string, slug?: string): stri
/**
* Route id of a source file. Translations follow the route of their english
* counterpart, a translated `slug` never moves a page, which is how docusaurus
* treated the localized trees as well.
* counterpart, a translated `slug` never moves a page.
*/
export function routeIdOf(segment: Segment, suffix: string[]): string {
// the data store rejects empty ids, starlight maps `index` to the root
packages/content-loader/src/sidebar.ts
+15 -15
View File
@@ -1,6 +1,6 @@
/**
* Builds one sidebar per (product, version, language) out of the loaded pages,
* reproducing what docusaurus derived from `_category_.json` and from the
* deriving it from `_category_.json` and from the
* handwritten sidebar files of the runner docs.
*/
@@ -44,12 +44,12 @@ export interface SidebarGroup {
export type SidebarEntry = SidebarLink | SidebarGroup;
/** A docusaurus sidebar file, as used by the runner docs. */
export type DocusaurusSidebarItem =
/** A hand written sidebar file, as used by the runner docs. */
export type SidebarSourceItem =
| string
| { type: 'doc'; id: string; label?: string }
| { type: 'autogenerated'; dirName: string }
| { type: 'category'; label: string; collapsed?: boolean; items: DocusaurusSidebarItem[] };
| { type: 'category'; label: string; collapsed?: boolean; items: SidebarSourceItem[] };
const last = Number.MAX_SAFE_INTEGER;
@@ -66,11 +66,11 @@ function labelFromDirname(name: string): string {
/**
* Builds the sidebars of every group of pages, keyed by the route prefix of the
* group. `manual` provides the docusaurus sidebar of the groups that ship one.
* group. `manual` provides the hand written sidebar of the groups that ship one.
*/
export function buildSidebars(
pages: SidebarPage[],
manual: Map<string, DocusaurusSidebarItem[]> = new Map(),
manual: Map<string, SidebarSourceItem[]> = new Map(),
): Map<string, SidebarEntry[]> {
const groups = new Map<string, SidebarPage[]>();
for (const page of pages) {
@@ -84,19 +84,19 @@ export function buildSidebars(
const key = `${groupPages[0]!.meta.product}@${groupPages[0]!.meta.version}`;
const items = manual.get(key);
const tree = treeOf(groupPages);
sidebars.set(prefix, items ? fromDocusaurus(items, groupPages, tree) : tree.build(''));
sidebars.set(prefix, items ? fromSidebarSource(items, groupPages, tree) : tree.build(''));
}
return sidebars;
}
interface Tree {
/** Entries of a directory, ordered as docusaurus ordered them. */
/** Entries of a directory, ordered by their position. */
build(dir: string): SidebarEntry[];
/** Localized label of a directory, from its `_category_.json`. */
label(dir: string): string;
}
/** Sidebar of a directory tree, ordered by `sidebar_position` as docusaurus did. */
/** Sidebar of a directory tree, ordered by `sidebar_position`. */
function treeOf(pages: SidebarPage[]): Tree {
const categories = new Map<string, SidebarPage>();
for (const page of pages) {
@@ -148,9 +148,9 @@ function treeOf(pages: SidebarPage[]): Tree {
return { build, label };
}
/** Sidebar described by a docusaurus sidebar file, used by the runner docs. */
function fromDocusaurus(
items: DocusaurusSidebarItem[],
/** Sidebar described by a hand written sidebar file, used by the runner docs. */
function fromSidebarSource(
items: SidebarSourceItem[],
pages: SidebarPage[],
tree: Tree,
): SidebarEntry[] {
@@ -159,7 +159,7 @@ function fromDocusaurus(
byDocId.set([page.meta.dir, page.meta.name].filter(Boolean).join('/'), page);
}
const convert = (item: DocusaurusSidebarItem): SidebarEntry | undefined => {
const convert = (item: SidebarSourceItem): SidebarEntry | undefined => {
if (typeof item === 'string') {
const page = byDocId.get(item);
return page && link(page);
@@ -167,7 +167,7 @@ function fromDocusaurus(
if (item.type === 'doc') {
const page = byDocId.get(item.id);
// the label of the sidebar file is english, the title of a translated
// page is already localized (docusaurus translated it from the json)
// page is already localized (translated from the json)
return page && link(page, page.meta.locale === defaultLocale ? (item.label ?? page.title) : page.title);
}
if (item.type === 'autogenerated') {
@@ -182,7 +182,7 @@ function fromDocusaurus(
}
// a category whose only child is an autogenerated directory keeps the
// translated label of the directory, like the docusaurus sidebars did
// translated label of the directory, like the sidebar files do
const single =
item.items.length === 1 && typeof item.items[0] === 'object' && 'dirName' in item.items[0]
? item.items[0]