# @agenetix/docs 中文文档

规范地址：https://npmcn.com/package/%40agenetix/docs/

版本：1\.4\.0
npm 元数据更新时间：2026-10-27T02:56:04.459Z
中文译文更新时间：2026-11-09T21:31:16.097Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agenetix/docs
原文对照：https://npmcn.com/package/%40agenetix/docs/?lang=original
项目主页：https://github.com/agenetix/docs
源码仓库：https://github.com/agenetix/docs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：470 kB，193 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：28 个
- peer 依赖：next \>=15\.5\.0 \<17\.0\.0，react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2026-08-02T04:49:51.733Z
- 最新版本发布：2026-10-27T02:56:04.100Z
- 近 30 天下载量：1717（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

App Router-native MDX文档 Next.js 具有可再使用布局,搜索,TOC,以及地语意识路由.

## 安装

```sh
npm install @agenetix/docs
```

也可以使用：`pnpm add @agenetix/docs`、`yarn add @agenetix/docs`、`bun add @agenetix/docs`

## README

# Agenetix 文档

`@agenetix/docs` 是 Next.js 的 App 路由器- 本地 MDX 文档库.

它是为那些想要文件内容在repo中同时仍然获得SEO友好预发路线,本地化知文件常规,搜索,标题提取,移动友好的docs UX,以及可配置的docs shell的团队而建造的,既可以保持简单,也可以插入更丰富的app chrome.

此寄存器既包含已发布的软件包, 也包含狗食网站:

-   `src` 包含库源
-   `tests` 包含 Vitest 覆盖
-   `site` 是示例 Next.js 应用程序和软件包本身的docs/showcase

## 预览

![Agenetix Docs docs page screenshot](https://npmcn.com/package/%40agenetix/docs/.github/assets/docs-page.png) ![Agenetix Docs theme studio screenshot](https://npmcn.com/package/%40agenetix/docs/.github/assets/theme-studio.png)

使用被打磨过的docs shell和可选实时主题工作室进行调制预设,密度,地表风格,口音行为等实例的站点船.

## 为什么用它

-   将 Docs 保留为 repo- 本地 MDX 而不是单独的 CMS
-   构建导航、路由解析、元数据、标题和搜索 `createDocsSource(...)` 调用
-   组合页面为相撞侧边栏部分,可选嵌入组和 `sidebar: false` 在导航中保留一个页面
-   带有 App 路由器友好原始语的 Render Docs `DocsLayout`, (中文(简体) ), `DocsPage`,以及 `DocsHomePage`
-   装有抛光基线的船舶 `DocsSearch`, (中文(简体) ), `DocsSidebar`, (中文(简体) ), `DocsToc`, (中文(简体) ), `HeadingLinks`,以及 `MobileDocsChrome`
-   支持本地化文件, 如 `getting-started/en.mdx`, (中文(简体) ), `getting-started/es.mdx`,以及 `getting-started/zh.mdx`
-   以嵌入式主题对象或活式主题提供者重塑 shell 样式
-   使用捆绑的 MDX 构件, 如横幅、 点名、 牌、 标签、 台阶、 文件、 手风琴和代码块

## 所需资源

-   节点.js `>=20`
-   下一个.js `>=15.5.0 <17`
-   反应 `^19`
-   反应 DOM `^19`

## 安装

```bash
npm install @agenetix/docs
```

然后在文档布局中导入共享样式表 :

```tsx
import "@agenetix/docs/styles.css";
```

## 快开始

### 1\. 创建文件来源

创建 `lib/docs.ts`数字 :

```ts
import path from "node:path";
import { createDocsSource } from "@agenetix/docs";

export const docsSource = createDocsSource({
  contentDir: path.join(process.cwd(), "content/docs"),
  basePath: "/docs",
  defaultLocale: "en",
  locales: ["en", "es", "zh"],
  hideDefaultLocaleInUrl: true,
  sectionOrder: ["", "guides", "guides/search", "reference"],
  groupLabels: {
    "guides/search": "Search",
  },
});
```

`docsSource` 成为路由解析、导航、元数据、标题和搜索的单一真理源.

### 2\. 创建文件布局

创建 `app/docs/layout.tsx`数字 :

```tsx
import { DocsLayout } from "@agenetix/docs";
import "@agenetix/docs/styles.css";
import { docsSource } from "@/lib/docs";
import { searchDocsAction } from "@/app/doc-actions";

export default function Layout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <DocsLayout
      navigation={docsSource.getNavigation()}
      searchAction={searchDocsAction}
    >
      {children}
    </DocsLayout>
  );
}
```

### 3\. 创建文件路径

创建 `app/docs/[[...slug]]/page.tsx`数字 :

```tsx
import { notFound, redirect } from "next/navigation";
import { DocsHomePage, DocsPage } from "@agenetix/docs";
import { docsSource } from "@/lib/docs";

interface PageProps {
  params: Promise<{ slug?: string[] }>;
}

export function generateStaticParams() {
  return docsSource.getStaticParams();
}

export async function generateMetadata({ params }: PageProps) {
  const { slug } = await params;
  return docsSource.getMetadata(slug);
}

export default async function DocsRoutePage({ params }: PageProps) {
  const { slug } = await params;
  const resolved = docsSource.resolveRoute(slug);

  if (resolved.type === "redirect" && resolved.href) {
    redirect(resolved.href);
  }

  if (resolved.type !== "entry" || !resolved.entry) {
    notFound();
  }

  if (resolved.entry.isHome) {
    return (
      <DocsHomePage
        entry={resolved.entry}
        navigation={docsSource.getNavigation()}
      />
    );
  }

  return (
    <DocsPage
      entry={resolved.entry}
      previousEntry={resolved.previousEntry}
      nextEntry={resolved.nextEntry}
      backHref={docsSource.getHref()}
    />
  );
}
```

### 4\. 添加您的第一个医生

创建 `content/docs/getting-started/en.mdx`数字 :

```mdx
---
title: "Getting Started"
description: "Your first Agenetix Docs page"
order: 0
---

Welcome to your docs.
```

此时,您的应用程序可以在 Repo- local MDX 下制作一个静态的 Docs 部分 `/docs`。 。 。 .

### 可选:更快的路由转换

`DocsPage` 向内流出 MDX 天体 `Suspense` 因此,贝壳和标题可以先画出。 对于大型 Doc 集中的快活导航, 添加一个路由级别 `loading.tsx` 在你的旁边 `[[...slug]]` 页面:

```tsx
export default function DocsLoading() {
  return <div className="emcydocs-prose emcydocs-mdx-loading" aria-busy="true" />;
}
```

导航传递至 `DocsLayout` 应该来自 `docsSource.getNavigation()` ——它返回只包含元数据的项目(没有MDX机构).

## 下一个. js : `@agenetix/docs/source`

图书馆的内容方面没有附加框架. `@agenetix/docs/source` 出口 `createDocsSource`, (中文(简体) ), `createBlogSource`, (中文(简体) ), `extractHeadings`, (中文(简体) ), `searchEntries`,href和sult 帮助器和内容类型,且其导入图中没有任何内容触及到Next.js,React DOM或一个组件(一个测试针。 任何运行节点的服务器都可以读取相同的内容 `content/docs/<slug>/<locale>.mdx` 文件夹并获取路径、导航、标题、元数据以及检索.

```ts
import path from "node:path";
import { createDocsSource } from "@agenetix/docs/source";

export const docsSource = createDocsSource({
  contentDir: path.join(process.cwd(), "content/docs"),
  basePath: "/docs",
  defaultLocale: "en",
  locales: ["en"],
});

// In an Expo Router loader, an Express handler or a build script:
const route = docsSource.resolveRoute(slugs);          // "entry" | "redirect" | "notFound"
const navigation = docsSource.getNavigation();          // sidebar sections, metadata only
const metadata = docsSource.getMetadata(slugs);         // title, description, canonical
```

`next` 是可选的对等依赖,所以只使用此条目的消费者不会安装Next.js. 画画是你的了: `route.entry.content` 是MDX机构,和 `route.entry.headings` 目录。 根项 `DocsMdx`,布局和组件仅保留 Next.js .

## 主题系统

`DocsLayout` 接受嵌入 `theme` 对象用于静态主题,它也可以从 `DocsThemeProvider` 当您想要运行时间切换器, 坚持偏好, 或者主题工作室.

```tsx
import {
  DocsLayout,
  DocsThemeProvider,
  type DocsThemeConfig,
} from "@agenetix/docs";
import { docsSource } from "@/lib/docs";

const docsTheme: DocsThemeConfig = {
  color: {
    preset: "ocean",
    mode: "dark",
    accentHue: 188,
    accentStrength: "bold",
    surfaceStyle: "elevated",
  },
  layout: {
    density: "compact",
    layoutWidth: "1480px",
    contentWidth: "50rem",
    sidebarWidth: "272px",
    tocWidth: "232px",
  },
  shape: {
    radius: "xl",
  },
};

export default function Layout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <DocsThemeProvider initialTheme={docsTheme}>
      <DocsLayout navigation={docsSource.getNavigation()}>
        {children}
      </DocsLayout>
    </DocsThemeProvider>
  );
}
```

如果您不需要实时编辑, 请直接通过同一对象到 `DocsLayout` 通过 `theme={docsTheme}` 并完全跳过提供者.

## 今天的什么战舰

-   源创建者 : `createDocsSource`, (中文(简体) ), `extractHeadings`
-   Docs shell 原始语: `DocsLayout`, (中文(简体) ), `DocsPage`, (中文(简体) ), `DocsHomePage`, (中文(简体) ), `DocsSearch`, (中文(简体) ), `DocsSidebar`, (中文(简体) ), `DocsToc`, (中文(简体) ), `HeadingLinks`, (中文(简体) ), `MobileDocsChrome`
-   主题原始: `DocsThemeProvider`, (中文(简体) ), `useDocsTheme()`, (中文(简体) ), `resolveDocsTheme(theme)`
-   MDX 帮助器和组件 : `DocsMdx`, (中文(简体) ), `getDefaultMdxComponents()`,加上横幅,点名,牌,分页,台阶,文件树,手风琴和代码块
-   博客原始人: `createBlogSource`, (中文(简体) ), `BlogDirectoryPage`, (中文(简体) ), `BlogPostPage`, (中文(简体) ), `BlogSearch`和相关组件
-   共享样式表 : `@agenetix/docs/styles.css`

## 地方发展

```bash
npm install
npm run dev
```

开始 :

-   库类型脚本以监视模式构建
-   实例 `site` 时间 `http://localhost:4003`

例子网站既是一个开发沙盒,也是软件包如何被接入真实的"Next.js"app的犬科参考.

## 有用的脚本

```bash
npm run build:lib
npm run build:site
npm run lint
npm run test
npm run typecheck
```

## SqlOS 的狗食

从 `sqlos/web`,使用本地文件依赖:

```json
{
  "dependencies": {
    "@agenetix/docs": "file:../../emcydocs"
  }
}
```

SqlOS repo还包括在本地文件依赖和已出版的npm版本之间切换的帮助脚本.

## 出版

`publish-npm.yml` 是 npm 唯一的发布入口。 合并为 `main` 不发布 `latest`。 。 。 .

-   **反对 `main`** ——发布预览分栏等内容 `@agenetix/docs@pr-12`。工作流程与精确的软件包注释.
-   **`v*` 标签** (例如 `v1.1.3`)——出版 `latest`弹出 `package.json` 首先; npm 将不会覆盖已经发布的版本 .

npm出处被省略,因为此出处寄存器是私有的. 该套件本身仍然通过可信赖的出版公开出版.

要尝试在平台 PR 中预览,请添加参考到 `infra/preview-packages.json`数字 :

```json
{
  "@agenetix/docs": "@agenetix/docs@pr-12"
}
```

## 常见问题

### @agenetix/docs 是什么？

App Router-native MDX文档 Next\.js 具有可再使用布局,搜索,TOC,以及地语意识路由\.

### 如何安装 @agenetix/docs？

在项目目录运行 npm install @agenetix/docs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agenetix/docs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agenetix/docs 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agenetix/docs 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agenetix/docs 可以商用吗？

@agenetix/docs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agenetix/docs 的下载量有多少？

根据 npm 官方下载统计，@agenetix/docs 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,717 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agenetix/docs 还在维护吗？

最新版本 1\.4\.0 发布于 2026/10/27（13 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/08/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。