Agenetix 文档

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

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

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

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

预览

使用被打磨过的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

安装

npm install @agenetix/docs

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

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

快开始

1. 创建文件来源

创建 lib/docs.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数字 :

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数字 :

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数字 :

---
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]] 页面:

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 文件夹并获取路径、导航、标题、元数据以及检索.

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 当您想要运行时间切换器, 坚持偏好, 或者主题工作室.

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

地方发展

npm install
npm run dev

开始 :

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

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

有用的脚本

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

SqlOS 的狗食

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

{
  "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数字 :

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