# SEO与搜索

搜索由 Fumadocs 提供。Onedocs 为站点地图、robots.txt 和 llms.txt 文件提供辅助功能，这些功能都配置为 Next.js App Router 路由。有关页面元数据和 Open Graph 图像，请参阅 [API参考](https://onedocs.inline0.dev/zh/docs/api-reference#metadata)中的 `onedocs/metadata` 和 `onedocs/og`。

## 搜索

Onedocs 使用 Fumadocs 内置的 Orama 搜索。创建一个 API 路由：

```ts title="src/app/api/search/route.ts"
import { source } from "@/lib/source";
import { createFromSource } from "fumadocs-core/search/server";

export const { GET } = createFromSource(source);
```

`RootProvider` 添加的搜索对话框默认会查询 `/api/search`，因此无需其他设置。

## 站点地图

在 `/sitemap.xml` 生成站点地图：

```ts title="src/app/sitemap.ts"
import { generateSitemap } from "onedocs/seo";
import meta from "../../content/docs/meta.json";

const baseUrl = "https://yourdomain.com";

export default function sitemap() {
  return generateSitemap({
    baseUrl,
    pages: meta.pages ?? [],
  });
}
```

`generateSitemap`会列出站点根目录，并为`/docs`下`pages`中的每个条目列出一个URL。以`---`（侧边栏分隔符）开头的条目会被跳过，`index`会映射到其自身`/docs`。它会按给定顺序读取条目，因此子文件夹中的页面需要单独列出，例如`"guides/setup"`。

## Robots.txt

在 `/robots.txt` 生成 robots.txt：

```ts title="src/app/robots.ts"
import { generateRobots } from "onedocs/seo";

const baseUrl = "https://yourdomain.com";

export default function robots() {
  return generateRobots({ baseUrl });
}
```

这会创建：

```
User-Agent: *
Allow: /

Host: https://yourdomain.com
Sitemap: https://yourdomain.com/sitemap.xml
```

## LLMs.txt

[LLMs.txt](https://llmstxt.org/) 可帮助 AI 助手理解你的文档。Onedocs 可生成摘要版和完整内容版。

### 摘要版

创建 `/llms.txt`，其中包含页面标题和描述：

```ts title="src/app/llms.txt/route.ts"
import { createLLMsSource, generateLLMsText } from "onedocs/llms";
import { source } from "@/lib/source";
import config from "../../../onedocs.config";

export async function GET() {
  const llmsSource = createLLMsSource(source);
  const text = await generateLLMsText(llmsSource, {
    title: config.title,
    description: config.description,
  });

  return new Response(text, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

文件以标题和描述开头，将每个页面列为带有描述的 `- Title: URL`，最后附上指向 `/llms-full.txt` 的指引。这两个函数都接收来自 `createLLMsSource` 的封装后源，而不是 Fumadocs 源本身，并返回一个 promise。

### 完整内容版

创建包含完整文档的 `/llms-full.txt`：

```ts title="src/app/llms-full.txt/route.ts"
import { createLLMsSource, generateLLMsFullText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const llmsSource = createLLMsSource(source);
  const text = await generateLLMsFullText(llmsSource);

  return new Response(text, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

每个页面按标题、URL、描述和处理后的 Markdown 写入，页面之间以 `---` 分隔。

页面文本来自 Fumadocs MDX 处理后的 Markdown，默认处于关闭状态。未启用时，`llms-full.txt` 仅包含标题、URL 和描述（[问题 #3](https://github.com/inline0/onedocs/issues/3)）。在 `source.config.ts` 中启用：

```ts title="source.config.ts"
import { defineDocs } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "content/docs",
  docs: {
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
});
```

## 配置选项

### 站点地图选项

```ts
generateSitemap({
  baseUrl: "https://yourdomain.com",
  pages: ["index", "getting-started", "configuration"],
  docsPath: "/docs", // Default: "/docs"
});
```

### Robots 选项

```ts
generateRobots({
  baseUrl: "https://yourdomain.com",
  sitemapPath: "/sitemap.xml", // Default: "/sitemap.xml"
});
```

## 你将获得

设置好这些路由后：

| URL | 功能 |
|-----|--------------|
| `/api/search?query=...` | 搜索 API 端点 |
| `/sitemap.xml` | 面向搜索引擎的 XML 站点地图 |
| `/robots.txt` | 带有站点地图引用的 Robots 文件 |
| `/llms.txt` | 面向 AI 助手的摘要 |
| `/llms-full.txt` | 面向 AI 助手的完整文档 |