Docs

MkSaaS includes a powerful documentation system built with Fumadocs. The documentation system supports multi-language content, custom components, and rich content formatting, making it ideal for product documentation, tutorials, and knowledge base articles.

Docs

Documentation System Structure

The documentation system is built using Fumadocs, a framework for building documentation sites, and integrates with internationalization.

page.tsx

layout.tsx

loading.tsx

index.tsx

lazy.ts

wrapper.tsx

dynamic-codeblock.tsx

i18n.ts

source.ts

source.config.ts

Source Configuration

The documentation system is configured using Fumadocs MDX in the source.config.ts file:

source.config.ts

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

// Documentation collection
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(),
    }),
  },
});

The documentation source is then loaded in 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';

/**
 * Turn a content source into a unified interface
 * .source folder is generated by `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;
  },
});

Creating Documentation Content

Adding a New Documentation Page

Create a new MDX file in the content/docs directory:

content/docs/getting-started.mdx

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

# Getting Started

This is a guide to help you get started with MkSaaS.

## Installation

First, you need to install the dependencies...

The icon property in the frontmatter supports all Lucide icons and will be displayed next to the document title.

Organizing Documentation

Fumadocs allows you to organize your documentation using a hierarchical structure:

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

You can customize the sidebar order and grouping by using meta files:

content/docs/meta.json

{
  "title": "Documentation",
  "pages": [
    "getting-started",
    {
      "title": "Features",
      "pages": ["features/auth", "features/database"]
    },
    {
      "title": "Deployment",
      "pages": ["deployment/hosting", "deployment/ci-cd"]
    }
  ],
  "description": "Complete documentation for your project",
  "root": true,
  "icon": "BookOpen"
}

Nested Documentation Structure

For nested documentation, create folder-specific meta files:

content/docs/features/meta.json

{
  "title": "Features",
  "pages": ["auth", "database"],
  "description": "Learn about key features",
  "root": false,
  "icon": "Star"
}

Multi-language Support

MkSaaS documentation system fully supports internationalization. You can create content in multiple languages using the following file naming convention:

Default locale (e.g., English): filename.mdx
Other locales (e.g., Chinese): filename.zh.mdx

Multi-language Documentation Example

For an English documentation page:

content/docs/getting-started.mdx

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

Content in English...

For the same page in Chinese:

content/docs/getting-started.zh.mdx

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

Content in Chinese...

Multi-language Meta Files

Meta files also support multi-language:

content/docs/meta.zh.json

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

Documentation Components

MkSaaS includes a variety of documentation components powered by Fumadocs:

Creating Custom Components

To create custom components for your documentation, you can modify the MDX components in src/components/docs/index.tsx. Here's an example using the YoutubeVideo component:

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,
    // Custom YoutubeVideo component for embedding YouTube videos
    YoutubeVideo,
    // Add more custom components here
  };

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

The YoutubeVideo component is defined in src/components/docs/youtube-video.tsx:

src/components/docs/youtube-video.tsx

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

/**
 * YoutubeVideo component
 *
 * How to get the URL of the YouTube video?
 * 1. Go to the YouTube video you want to embed
 * 2. Click on the share button and copy the embed URL
 * 3. Paste the URL into the url prop
 *
 * @param {string} url - The URL of the YouTube video
 * @param {number} width - The width of the video
 * @param {number} height - The height of the video
 */
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>
  );
};

After adding the component to the MDX components, you can use it directly in your MDX files:

content/docs/themes.mdx

---
title: Themes
description: Learn how to customize the themes in your MkSaaS website
icon: Palette
---

# Theme Tutorial

Video tutorial:

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

The video above demonstrates how to customize themes in your MkSaaS website.

YoutubeVideo component example:

Customizing the Documentation Layout

You can customize the documentation layout by editing src/app/[locale]/docs/layout.tsx. This file controls the navigation, sidebar, and overall structure of the documentation pages.

Build Process

The documentation system uses Fumadocs MDX's build process:

Development: Content is processed on-demand during development
Build: Run pnpm run content to generate optimized documentation sources
Generated Files: The .source directory contains generated TypeScript files with your content

Consistent Structure: Maintain a consistent structure across documentation pages
Clear Headings: Use descriptive headings that follow a logical hierarchy
Code Examples: Include practical code examples where appropriate
Visuals: Use diagrams, screenshots, or interactive components to explain complex concepts
Cross-Linking: Link related documentation pages to help users navigate your content
Versioning: Consider documentation versioning for different software releases
Accessibility: Ensure your documentation is accessible to all users
Search Optimization: Use clear titles and descriptions to make content discoverable
Meta Files: Use meta.json files to organize and structure your documentation sidebar
Icon Consistency: Use consistent icons throughout your documentation

Documentation System Structure

Source Configuration

Creating Documentation Content

Adding a New Documentation Page

Organizing Documentation

Nested Documentation Structure

Multi-language Support

Multi-language Documentation Example

Multi-language Meta Files

Documentation Components

Creating Custom Components

Customizing the Documentation Layout

Build Process

Advanced Configuration

Fumadocs UI

Fumadocs Components

Internationalization

Markdown

Best Practices

Video Tutorial

Next Steps

Blog

i18n

Website Configuration

Themes

Table of Contents

Docs

Callouts

Tabs

Steps

File Tree

Cards

Fumadocs UI

Fumadocs Components

Internationalization

Markdown

Blog

i18n

Website Configuration

Themes

Table of Contents