LogoMkSaaS Docs

Docs

Learn how to create, manage, and customize your documentation

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.

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

  1. 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...
  1. 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:

  1. Default locale (e.g., English): filename.mdx
  2. 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...

The system will automatically match the documentation with the appropriate language based on the user's locale.

Multi-language Meta Files

Meta files also support localization:

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:

Customizing the Documentation

Modifying the 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.

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:

Build Process

The documentation system uses Fumadocs MDX's build process:

  1. Development: Content is processed on-demand during development
  2. Build: Run pnpm run content to generate optimized documentation sources
  3. Generated Files: The .source directory contains generated TypeScript files with your content
  4. Type Safety: Full TypeScript support with inferred types from your content

Advanced Configuration

For more advanced customization of the documentation system, you can refer to the Fumadocs documentation:

Best Practices

  1. Consistent Structure: Maintain a consistent structure across documentation pages
  2. Clear Headings: Use descriptive headings that follow a logical hierarchy
  3. Code Examples: Include practical code examples where appropriate
  4. Visuals: Use diagrams, screenshots, or interactive components to explain complex concepts
  5. Progressive Disclosure: Start with basic concepts and gradually introduce more complex topics
  6. Cross-Linking: Link related documentation pages to help users navigate your content
  7. Versioning: Consider documentation versioning for different software releases
  8. Accessibility: Ensure your documentation is accessible to all users
  9. Search Optimization: Use clear titles and descriptions to make content discoverable
  10. Meta Files: Use meta.json files to organize and structure your documentation sidebar
  11. Icon Consistency: Use consistent icons throughout your documentation
  12. Schema Validation: Leverage Zod schemas for type-safe frontmatter validation

Next Steps

Now that you understand how to work with the documentation system in MkSaaS, you might want to explore these related features: