@ 农地/ 农地

官方的 Farm.js 运行时间适配器 @farming-labs/docs。 。 。 .

安装

npm install @farming-labs/docs @farming-labs/farmjs @farming-labs/theme

配置农场

将文档设置保存在 docs.config.ts,然后启用适配器 farm.config.ts数字 :

import { defineConfig } from "@farm.js/core";
import { withDocs } from "@farming-labs/farmjs/config";

export default withDocs(
  defineConfig({
    preset: "vercel",
  }),
);

农场发现 docs.config.ts 从应用程序根。 包装员写道: 一个适配器运行时间描述符 输入农场 docs 配置 。 农用 装入页面渲染、服务器行为和MDX集成的版本合同 从 @farming-labs/farmjs 不选择文件主题本身。 不同的路径可以 明确规定:

export default withDocs(defineConfig({}), {
  configPath: "config/docs.config.ts",
});

代码突出化由适配器的MDX管道来编译. 选择一个特定的 该边界的Shiki调色板没有替换其他适配器:

export default withDocs(defineConfig({}), {
  codeBlockThemes: {
    light: "github-light-default",
    dark: "vesper",
  },
});

添加应用程序自己的 MDX 插件 mdx 内 docs.config.ts。每个插件都是 包名或相对于应用程序根的路径,带有可选 JSON 选项:

export default defineDocs({
  entry: "docs",
  mdx: {
    remarkPlugins: ["./lib/remark-docs.mjs"],
    rehypePlugins: [["rehype-katex", { strict: false }]],
    codeHighlighter: "./lib/rehype-docs-code.mjs",
  },
});

• remarkPlugins 财务报告和审定财务报表 rehypePlugins 在内置插件之后运行.
• codeHighlighter 仅替换语法亮点;元数据和表格 内容保留.
• 节点和边缘目标与它们一起编译页面.
• 制作时会编译每一页 mdx 已经设定,以及 buildCache: true 和它一起掷出.
• withDocs(config, { config: { mdx } }) 替换文件 mdx。 。 。 .

从应用程序拥有的全球样式表导入选中的主题 。 这个 并给予应用程序用于特定项目覆盖的正常位置:

/* src/app/globals.css */
@import "@farming-labs/theme/pixel-border/css";

:root {
  --color-fd-primary: #8b5cf6;
}

主题工厂 docs.config.ts 和中央支助系统入境点必须说明 同样的主题。 这是Next.js使用的 CSS 统一入口, TanStack Start, SvelteKit, Astro, 和 Nuxt 的集成. 克克勒斯特公司(Nuxt). 适配器没有 飞船或注入第二个针对农场的主题样式表.

重复生产建筑

适配器重复使用 Markdown/MDX 编译和语法突出 在生产建设中。 它将编译的代码和源地图存储在 <Vite cacheDir>/farming-docs/mdx-v1.json; Vite 通常设置 cacheDir 内 node_modules/.vite。保存您 CI 中的目录建立缓存以重新使用 跨行业工作。 删除它只会使编译再次运行.

缓存条目按源、模块路径、模式键,突出主题, 节点版本,以及编译器执行和内容指纹 它的依赖性。 Vite仍然发现并构建进口,组件,CSS, 路径和部署输出通常。 开发与瞭望建筑不 使用此缓存。 缺少、腐败、不兼容或无法写入缓存文件 返回编译;编译器出错仍会使构建失败.

缓存最多保留了1 024个模块和大约32个米B有效载荷. 它不缓存生成 HTML 或更改客户端的导航或前置. 要诊断一个没有 MDX 缓存再利用的构建 :

export default withDocs(defineConfig({}), { buildCache: false });

下级 docsMdx({ buildCache: false }) 选项有相同的行为.

预发页

设定 docs.prerender: true 内 farm.config.ts 拥有 farm build 使每个 在节点和无服务器目标上输入静态文件的docs页面 :

export default withDocs(defineConfig({ docs: { prerender: true } }));

Farm 向适配器的服务器条目询问其页面列表(listFarmDocsPages) (中文(简体) ). 预发页面将其Markdown副本与页面相接,或在 配置 sitemap, (中文(简体) ), llmsTxt,或 robots baseUrl,所以社会卡需要 该基址保持绝对。 客户端导航读取一个静态页面的数据 从它的 HTML。 静态文件不能谈判 Accept: text/markdown所以探员们 使用该 .md URL 页面链接到 。 马克德,搜索, llms.txt,并保留 MCP 根据请求进行翻译.

守护页面

守护一个文件页, 当您守护应用程序页: a middleware.ts 在其文件夹中,a 配置介质匹配器, 或 Auth 集成的保护路径 。 这个 适配器声明 guarded-pages 因此,农场为这些页面服务 用它把应用程序的守卫传到运行时间 一个页,一个警卫覆盖 远离搜索, llms.txt, (中文(简体) ), llms-full.txt,网站地图,MCP,问AI 内容种子, 它在不运行守护的情况下回答 。 它的 Markdown 答案 在其自己的 URL 中 (Accept: text/markdown)和a时 .md 仅当守护时 URL 也覆盖那个URL. 边缘目标提供一个没有警卫的快照,所以农场 停止守护文件页的边缘建筑.

边际部署

农场边缘目标自动使用适配器的构建时间编译器. 这个 预编译页面,客户端导航数据,CSS,Markdown,搜索,站点地图, 机器人 和特工发现反应 这样部署的工人就不会导入 节点服务器运行时间 .

该快照无法保存需要实时服务器调用或 可变会. 禁用默认的 MCP 和生产遥测表面 边缘特定文件配置 :

import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  mcp: false,
  telemetry: false,
});

当询问AI,反馈时,边缘结构也会以可操作错误而停止, 分析、可观察性、i18n或功能支持的自定义搜索提供者是 启用 。 当需要这些运行时使用节点目标 .

服务器包装器

withDocs() 是正常的整合。 下级服务器包装器是 可用于自定义运行时间、路由测试和框架开发:

import docsConfig from "./docs.config";
import { createDocsServer } from "@farming-labs/farmjs/server";

const docs = createDocsServer({
  ...docsConfig,
  rootDir: process.cwd(),
});

const response = await docs.handle(request);

handle() 返回时 null 对于非文件请求,可以运行 在农场的请求 输油管而不接管应用路线。 服务器也会曝光 load, (中文(简体) ), GET, (中文(简体) ), POST,以及 MCP 用于定制路由.

入境点

许可证

麻省理工学院