---
title: "公开 API"
description: "查阅 svedocs 对外提供的稳定导出。"
---

> Documentation Index
> Fetch the complete documentation index at: https://svedocs.pwp.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 公开 API

请从下面列出的包路径导入公开 API。即使内部实现以后在子目录间调整，这些入口也会保持精简和稳定。

## Config

```ts
import { defineConfig, loadSvedocsConfig } from 'svedocs/config';
```

`defineConfig` 用来拿类型提示，`loadSvedocsConfig` 用来读解析后的默认值。

## Vite

```ts
import { svedocs } from 'svedocs/vite';
```

这个插件提供虚拟模块、内容刷新、MDX/SVX 组件编译、注入式作者组件和命名布局注册。

编译期 Markdown 钩子放在 `svedocs.config.ts` 中：

```ts
export default defineConfig({
  markdown: {
    remarkPlugins: [],
    rehypePlugins: [],
    shiki: {
      transformers: []
    }
  }
});
```

这些钩子会在 svedocs 构建页面列表并渲染兼容 Svelte 的 `.svx/.mdx` 文件时运行，不会被序列化进浏览器虚拟模块。

虚拟模块：

| 模块 | 内容 |
| --- | --- |
| `virtual:svedocs/config` | 解析后的配置 |
| `virtual:svedocs/pages` | 完整页面列表 |
| `virtual:svedocs/page-index` | 用于客户端路由匹配的轻量页面索引 |
| `virtual:svedocs/page-loaders` | 完整单页数据的动态加载器 |
| `virtual:svedocs/tree` | 侧栏树 |
| `virtual:svedocs/search` | 搜索记录 |
| `virtual:svedocs/search-loader` | 客户端搜索记录的动态加载器 |
| `virtual:svedocs/component-loaders` | 按页面 ID 索引的 Svelte 正文动态加载器 |
| `virtual:svedocs/layout-loaders` | 按布局名称索引的动态加载器 |
| `virtual:svedocs/components` | 编译后的 `.svx/.mdx` 组件 |
| `virtual:svedocs/layouts` | 注册的自定义布局 |
| `virtual:svedocs/theme-components` | 注册的主题组件替换 |

`loadSvedocsPage(page, { pages, components, layouts })` 并行加载当前页数据、正文组件和布局，返回 `{ page, content, layout }`。在通用 `+page.ts` 中使用；组件函数不能通过 `+page.server.ts` 序列化。旧的 `components` 和 `layouts` 虚拟模块仍保留，但会立即导入全部组件。

## Core

```ts
import {
  loadSvedocsContent,
  createPageTree,
  createSearchRecords,
  checkSvedocsContent,
  createAbsoluteUrl,
  createCanonicalUrl,
  createPageCanonicalUrl
} from 'svedocs/core';
import { resolveSvedocsPageRoute, resolveSvedocsHref, loadSvedocsPage, createSvedocsHtmlHandle, getSvedocsDocumentAttributes } from 'svedocs/routes';
```

核心 API 包含内容加载、导航、链接、检查和搜索记录。浏览器安全的 `svedocs/routes` 入口提供 `resolveSvedocsPageRoute`，用于加载 canonical 路由并处理默认语言重定向；`resolveSvedocsHref` 对链接应用同一套语言规则。

`createAbsoluteUrl(config, value)` 解析 HTTP(S) 资源/接口 URL，不应用页面尾斜杠规则。`createCanonicalUrl(config, value)` 规范化同源页面 URL，保留 query、移除 fragment；外部路径保持不变。`createPageCanonicalUrl(config, page)` 使用页面 canonical 或路由，没有站点 URL 和显式 canonical 时返回 undefined。

`createSvedocsHtmlHandle({ config, pages })` 是 SvelteKit 服务端 Handle，在 SSR 和预渲染时设置 `<html lang dir>`。`getSvedocsDocumentAttributes({ config, pages }, pathname)` 返回 `{ lang, dir }`，可用于自定义 app shell。

## Theme

```ts
import {
  DocsApp,
  RootLayout,
  Seo,
  LayoutShell,
  DocsLayout,
  DocsShell,
  DocPage,
  Article,
  PageLayout,
  PageShell,
  ErrorPage,
  RenderError,
  Navbar,
  TableOfContents,
  Footer,
  PageTools,
  HomePage,
  ThemeInit,
  FormField,
  Input,
  Select,
  Textarea,
  Checkbox,
  Button,
  LocalizedLink,
  Integrations,
  GoogleAd,
  GoogleAdsConversion
} from 'svedocs/theme';
import 'svedocs/theme/styles.css';
import 'svedocs/theme/base.css';
import { createSearchController, createAskAiController } from 'svedocs/theme/headless';
import type { SvedocsThemeComponentMap, SvedocsNavbarProps, SvedocsSeoProps } from 'svedocs/theme/types';
```

完整的路由外壳可以直接使用 `DocsApp`，也可以组合更底层的组件构建自定义站点。
自定义页面和布局中的表单可以使用这些基础控件，以继承 svedocs 默认主题。
开发完整的自定义主题时，可以通过 `themeComponents` 替换默认组件，并复用无样式控制器。每个组件的属性见[组件](/docs/zh/reference/theme-components)。

## Cloudflare

```ts
import { createCloudflarePreset, createWranglerJsonc, createCloudflareEnvDts } from 'svedocs/cloudflare';
```

这些辅助函数会协调 SvelteKit 构建模式、`wrangler.toml` 或 `wrangler.jsonc`，以及平台绑定类型。

## Search 和 AI

```ts
import { createConfiguredSearchResponse, createSearchResponse, searchRecords } from 'svedocs/search';
import { createConfiguredAskResponse, createAskResponse, createMemoryRateLimiter } from 'svedocs/ai';
```

搜索和 Ask AI 支持本地、Algolia、Typesense、Cloudflare 和 OpenAI 兼容服务。本地搜索可以按语言和内容类型过滤结果。

生成的路由应优先使用配置感知的响应函数。只有需要自定义路由或服务选择时，才直接导入 `createAlgoliaSearchProvider`、`createTypesenseSearchProvider`、`createCloudflareAiSearchProvider`、`createWorkersAiProvider` 或 `createOpenAiCompatibleProvider`。

## 服务集成

```ts
import {
  createIntegrationAssets,
  createIndexNowPayloads,
  submitIndexNow,
  trackGoogleAdsConversion
} from 'svedocs/integrations';
import type { IndexNowPayload, IndexNowResult, SvedocsIntegrationsConfig } from 'svedocs/integrations';
```

| API | 行为 |
| --- | --- |
| `createIntegrationAssets(config)` | 返回 IndexNow 验证文件与 AdSense `ads.txt` 的文件名到内容映射，不读写文件。Vite 插件负责输出，并保留用户已有的 `ads.txt`。 |
| `createIndexNowPayloads(config, pages)` | 返回 `IndexNowPayload[]`，只包含可发现、同源的 canonical URL，去重后按每批最多 10,000 个拆分。未启用 IndexNow 时抛错，不发起请求。 |
| `submitIndexNow(config, pages, options?)` | 先验证已部署的 key 文件，再逐批提交，返回包含 `submitted`、`batches` 和 `statuses` 的 `Promise<IndexNowResult>`。提交响应不是 200/202 时抛错。`options.fetch` 可替换请求实现；`verifyKey: false` 可跳过部署检查。应在部署工具完成发布后调用。 |
| `trackGoogleAdsConversion(integrations, name, development?, transactionId?)` | 发送 `config.integrations.googleAds.conversions` 中的命名转化。传入 `config.integrations` 与 SvelteKit 的 `dev` 标志。遵守服务开关与 Do Not Track，SSR 期间不执行。 |

该入口还导出 `SvedocsAdSlot`、`SvedocsGoogleAdsConversion` 和 `SvedocsResolvedIntegrations` 类型。输入配置与解析后的集成类型也可从 `svedocs/config` 导入。

仅使用配置接入服务与自动页面统计时，参阅[集成指南](/docs/zh/integrations/analytics-ads-indexnow)。`Integrations`、`GoogleAd` 和 `GoogleAdsConversion` 是 `svedocs/theme` 导出的 Svelte 组件，其属性见[主题组件](/docs/zh/reference/theme-components)。

## OG

```ts
import {
  createPageMetadata,
  createPageAlternates,
  createSitemapXml,
  createSitemapResponse,
  createRobotsTxt,
  createRssXml,
  createRssResponse,
  createPageOgImageResponse,
  createOgImageInput,
  createOgImage
} from 'svedocs/og';
```

这些 API 可用于自定义路由处理函数、布局和构建期 OG 图片生成。

## 虚拟模块类型

在 `src/app.d.ts` 中添加 `/// <reference types="svedocs/virtual" />`，为 `virtual:svedocs/*` 导入提供类型。此入口仅包含 TypeScript 声明，不能作为运行时模块导入。

Source: https://svedocs.pwp.sh/docs/zh/reference/api