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.
Source Configuration
The documentation system is configured using Fumadocs MDX in the source.config.ts
file:
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
:
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:
---
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:
{
"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:
{
"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:
---
title: Getting Started
description: Quick start guide for setting up your MkSaaS project
icon: Rocket
---
Content in English...
For the same page in Chinese:
---
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:
{
"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:
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
:
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:
---
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:
- 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 - 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:
Fumadocs UI
Learn about docs layout customization
Fumadocs Components
Additional components to improve your docs
Internationalization
Advanced i18n features for your documentation
Markdown
Learn about Markdown features and syntax
Best Practices
- 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
- Progressive Disclosure: Start with basic concepts and gradually introduce more complex topics
- 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
- 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: