文档 | 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 模板中自定义主题。