文档 | MkSaaS - 快速构建 AI SaaS 产品

MkSaaS 内置一个基于 Fumadocs 构建的强大文档系统。文档系统支持多语言内容、自定义组件和丰富的内容格式，非常适合产品文档、教程和知识库文章。

Docs

文档系统架构

文档系统使用 Fumadocs 构建，这是一个用于构建文档站点的框架，并已实现国际化。

page.tsx

layout.tsx

loading.tsx

index.tsx

lazy.ts

wrapper.tsx

dynamic-codeblock.tsx

i18n.ts

source.ts

source.config.ts

数据源配置

文档系统在 source.config.ts 文件中使用 Fumadocs MDX 配置数据源：

source.config.ts

import { defineDocs, frontmatterSchema, metaSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';

// 文档集合
export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    schema: frontmatterSchema.extend({
      preview: z.string().optional(),
      index: z.boolean().default(false),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      description: z.string().optional(),
    }),
  },
});

然后在 src/lib/source.ts 中加载数据源：

src/lib/source.ts

import { type InferPageType, loader } from 'fumadocs-core/source';
import * as LucideIcons from 'lucide-react';
import { createElement } from 'react';
import { docs } from '../../../.source';
import { docsI18nConfig } from './i18n';

/**
 * 将内容源转换为统一接口
 * .source 文件夹由 `fumadocs-mdx` 生成
 */
export const source = loader({
  baseUrl: '/docs',
  i18n: docsI18nConfig,
  source: docs.toFumadocsSource(),
  icon(iconName) {
    if (!iconName) {
      return undefined;
    }

    const IconComponent = (LucideIcons as Record<string, any>)[iconName];
    if (IconComponent) {
      return createElement(IconComponent);
    }

    console.warn(`Icon not found: ${iconName}`);
    return undefined;
  },
});

创建文档内容

添加新文档页面

在 content/docs 目录中创建新的 MDX 文件：

content/docs/getting-started.mdx

---
title: 入门文档
description: 设置 MkSaaS 项目的快速入门文档
icon: Rocket
---

# 入门文档

这是一个帮助您开始使用 MkSaaS 的文档。

## 安装

首先，您需要安装依赖项...

前言中的 icon 属性支持所有 Lucide 图标，并将显示在文档标题旁边。

组织文档

Fumadocs 允许您使用分层结构组织文档：

content/
  docs/
    getting-started.mdx
    features/
      auth.mdx
      database.mdx
    deployment/
      hosting.mdx
      ci-cd.mdx

您可以使用元文件自定义侧边栏顺序和分组：

content/docs/meta.json

{
  "title": "文档",
  "pages": [
    "getting-started",
    {
      "title": "功能特性",
      "pages": ["features/auth", "features/database"]
    },
    {
      "title": "部署",
      "pages": ["deployment/hosting", "deployment/ci-cd"]
    }
  ],
  "description": "项目的完整文档",
  "root": true,
  "icon": "BookOpen"
}

嵌套文档结构

对于嵌套文档，创建特定于文件夹的元文件：

content/docs/features/meta.json

{
  "title": "功能特性",
  "pages": ["auth", "database"],
  "description": "了解关键功能",
  "root": false,
  "icon": "Star"
}

多语言支持

MkSaaS 文档系统完全支持国际化。您可以使用以下文件命名约定创建多语言内容：

默认语言（例如英语）：filename.mdx
其他语言（例如中文）：filename.zh.mdx

多语言文档示例

英语文档页面：

content/docs/getting-started.mdx

---
title: Getting Started
description: Quick start guide for setting up your MkSaaS project
icon: Rocket
---

英语内容...

同一页面的中文版本：

content/docs/getting-started.zh.mdx

---
title: 入门文档
description: MkSaaS项目的快速设置文档
icon: Rocket
---

中文内容...

多语言元文件

元文件也支持多语言：

content/docs/meta.zh.json

{
  "title": "文档",
  "pages": [
    "getting-started",
    {
      "title": "功能特性",
      "pages": ["features/auth", "features/database"]
    }
  ],
  "description": "完整的项目文档",
  "root": true,
  "icon": "BookOpen"
}

文档组件

MkSaaS 包含由 Fumadocs 提供支持的各种文档组件：

创建自定义组件

要为您的文档创建自定义组件，您可以修改 src/components/docs/index.tsx 中的 MDX 组件。以下是使用 YoutubeVideo 组件的示例：

src/components/docs/mdx-components.tsx

import { YoutubeVideo } from '@/components/docs/youtube-video';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  const baseComponents: Record<string, any> = {
    ...defaultMdxComponents,
    // 用于嵌入 YouTube 视频的自定义 YoutubeVideo 组件
    YoutubeVideo,
    // 在这里添加更多自定义组件
  };

  return {
    ...baseComponents,
    ...components,
  };
}

YoutubeVideo 组件在 src/components/docs/youtube-video.tsx 中定义：

src/components/docs/youtube-video.tsx

interface YoutubeVideoProps {
  url: string;
  width?: number;
  height?: number;
}

/**
 * YoutubeVideo 组件
 *
 * 如何获取 YouTube 视频的 URL？
 * 1. 进入到您想要嵌入的 YouTube 视频
 * 2. 点击分享按钮并复制嵌入 URL
 * 3. 将 URL 粘贴到 url 属性中
 *
 * @param {string} url - YouTube 视频的 URL
 * @param {number} width - 视频的宽度
 * @param {number} height - 视频的高度
 */
export const YoutubeVideo = ({
  url,
  width = 560,
  height = 315,
}: YoutubeVideoProps) => {
  return (
    <div className="my-4">
      <iframe
        width={width}
        height={height}
        src={url}
        title="YouTube video player"
        frameBorder="0"
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
        referrerPolicy="strict-origin-when-cross-origin"
        allowFullScreen
        className="w-full aspect-video"
      />
    </div>
  );
};

将组件添加到 MDX 组件后，您可以直接在 MDX 文件中使用它：

content/docs/themes.mdx

---
title: 主题
description: 学习如何在MkSaaS 模板中自定义主题
icon: Palette
---

# 主题教程

视频教程：

<YoutubeVideo url="https://www.youtube.com/embed/jHzdo1Bm9Lk?si=unAfwFdnRCvDXdGu" />

上面的视频演示了如何在MkSaaS 模板中自定义主题。

YoutubeVideo 组件示例：

自定义文档布局

您可以通过编辑 src/app/[locale]/docs/layout.tsx 来自定义文档布局。此文件控制导航、侧边栏和文档页面的整体结构。

构建过程

文档系统使用 Fumadocs MDX 的构建过程：

开发：在开发过程中按需处理内容
构建：运行 pnpm run content 生成优化的文档源
生成的文件：.source 目录包含生成的 TypeScript 文件和您的内容

高级配置

有关文档系统的更高级自定义，您可以参考 Fumadocs 文档：

Fumadocs UI

了解文档布局自定义

Fumadocs 组件

改善文档的其他组件

国际化

文档的高级 i18n 功能

Markdown

了解 Markdown 功能和语法

最佳实践

一致的结构：在文档页面中保持一致的结构
清晰的标题：使用遵循逻辑层次结构的描述性标题
代码示例：在适当的地方包含实用的代码示例
视觉效果：使用图表、截图或交互式组件来解释复杂概念
交叉链接：链接相关的文档页面以帮助用户导航您的内容
版本控制：考虑为不同的软件版本进行文档版本控制
可访问性：确保您的文档对所有用户都是可访问的
搜索优化：使用清晰的标题和描述使内容可被发现
元文件：使用 meta.json 文件来组织和构建您的文档侧边栏
图标一致性：在整个文档中使用一致的图标

视频教程

下一步

现在您了解了如何在 MkSaaS 中使用文档系统，您可能想要探索这些相关功能：

博客

配置博客内容

i18n

配置多语言功能

网站配置

配置网站设置

主题

配置主题和外观设置

MkSaaS 内置一个基于 Fumadocs 构建的强大文档系统。文档系统支持多语言内容、自定义组件和丰富的内容格式，非常适合产品文档、教程和知识库文章。

Docs

文档系统架构

文档系统使用 Fumadocs 构建，这是一个用于构建文档站点的框架，并已实现国际化。

page.tsx

layout.tsx

loading.tsx

index.tsx

lazy.ts

wrapper.tsx

dynamic-codeblock.tsx

i18n.ts

source.ts

source.config.ts

数据源配置

文档系统在 source.config.ts 文件中使用 Fumadocs MDX 配置数据源：

source.config.ts

import { defineDocs, frontmatterSchema, metaSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';

// 文档集合
export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    schema: frontmatterSchema.extend({
      preview: z.string().optional(),
      index: z.boolean().default(false),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      description: z.string().optional(),
    }),
  },
});

然后在 src/lib/source.ts 中加载数据源：

src/lib/source.ts

import { type InferPageType, loader } from 'fumadocs-core/source';
import * as LucideIcons from 'lucide-react';
import { createElement } from 'react';
import { docs } from '../../../.source';
import { docsI18nConfig } from './i18n';

/**
 * 将内容源转换为统一接口
 * .source 文件夹由 `fumadocs-mdx` 生成
 */
export const source = loader({
  baseUrl: '/docs',
  i18n: docsI18nConfig,
  source: docs.toFumadocsSource(),
  icon(iconName) {
    if (!iconName) {
      return undefined;
    }

    const IconComponent = (LucideIcons as Record<string, any>)[iconName];
    if (IconComponent) {
      return createElement(IconComponent);
    }

    console.warn(`Icon not found: ${iconName}`);
    return undefined;
  },
});

创建文档内容

添加新文档页面

在 content/docs 目录中创建新的 MDX 文件：

content/docs/getting-started.mdx

---
title: 入门文档
description: 设置 MkSaaS 项目的快速入门文档
icon: Rocket
---

# 入门文档

这是一个帮助您开始使用 MkSaaS 的文档。

## 安装

首先，您需要安装依赖项...

前言中的 icon 属性支持所有 Lucide 图标，并将显示在文档标题旁边。

组织文档

Fumadocs 允许您使用分层结构组织文档：

content/
  docs/
    getting-started.mdx
    features/
      auth.mdx
      database.mdx
    deployment/
      hosting.mdx
      ci-cd.mdx

您可以使用元文件自定义侧边栏顺序和分组：

content/docs/meta.json

{
  "title": "文档",
  "pages": [
    "getting-started",
    {
      "title": "功能特性",
      "pages": ["features/auth", "features/database"]
    },
    {
      "title": "部署",
      "pages": ["deployment/hosting", "deployment/ci-cd"]
    }
  ],
  "description": "项目的完整文档",
  "root": true,
  "icon": "BookOpen"
}

嵌套文档结构

对于嵌套文档，创建特定于文件夹的元文件：

content/docs/features/meta.json

{
  "title": "功能特性",
  "pages": ["auth", "database"],
  "description": "了解关键功能",
  "root": false,
  "icon": "Star"
}

多语言支持

MkSaaS 文档系统完全支持国际化。您可以使用以下文件命名约定创建多语言内容：

默认语言（例如英语）：filename.mdx
其他语言（例如中文）：filename.zh.mdx

多语言文档示例

英语文档页面：

content/docs/getting-started.mdx

---
title: Getting Started
description: Quick start guide for setting up your MkSaaS project
icon: Rocket
---

英语内容...

同一页面的中文版本：

content/docs/getting-started.zh.mdx

---
title: 入门文档
description: MkSaaS项目的快速设置文档
icon: Rocket
---

中文内容...

多语言元文件

元文件也支持多语言：

content/docs/meta.zh.json

{
  "title": "文档",
  "pages": [
    "getting-started",
    {
      "title": "功能特性",
      "pages": ["features/auth", "features/database"]
    }
  ],
  "description": "完整的项目文档",
  "root": true,
  "icon": "BookOpen"
}

文档组件

MkSaaS 包含由 Fumadocs 提供支持的各种文档组件：

创建自定义组件

要为您的文档创建自定义组件，您可以修改 src/components/docs/index.tsx 中的 MDX 组件。以下是使用 YoutubeVideo 组件的示例：

src/components/docs/mdx-components.tsx

import { YoutubeVideo } from '@/components/docs/youtube-video';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  const baseComponents: Record<string, any> = {
    ...defaultMdxComponents,
    // 用于嵌入 YouTube 视频的自定义 YoutubeVideo 组件
    YoutubeVideo,
    // 在这里添加更多自定义组件
  };

  return {
    ...baseComponents,
    ...components,
  };
}

YoutubeVideo 组件在 src/components/docs/youtube-video.tsx 中定义：

src/components/docs/youtube-video.tsx

interface YoutubeVideoProps {
  url: string;
  width?: number;
  height?: number;
}

/**
 * YoutubeVideo 组件
 *
 * 如何获取 YouTube 视频的 URL？
 * 1. 进入到您想要嵌入的 YouTube 视频
 * 2. 点击分享按钮并复制嵌入 URL
 * 3. 将 URL 粘贴到 url 属性中
 *
 * @param {string} url - YouTube 视频的 URL
 * @param {number} width - 视频的宽度
 * @param {number} height - 视频的高度
 */
export const YoutubeVideo = ({
  url,
  width = 560,
  height = 315,
}: YoutubeVideoProps) => {
  return (
    <div className="my-4">
      <iframe
        width={width}
        height={height}
        src={url}
        title="YouTube video player"
        frameBorder="0"
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
        referrerPolicy="strict-origin-when-cross-origin"
        allowFullScreen
        className="w-full aspect-video"
      />
    </div>
  );
};

将组件添加到 MDX 组件后，您可以直接在 MDX 文件中使用它：

content/docs/themes.mdx

---
title: 主题
description: 学习如何在MkSaaS 模板中自定义主题
icon: Palette
---

# 主题教程

视频教程：

<YoutubeVideo url="https://www.youtube.com/embed/jHzdo1Bm9Lk?si=unAfwFdnRCvDXdGu" />

上面的视频演示了如何在MkSaaS 模板中自定义主题。