Documentation

MkSaaS includes a powerful documentation system built with Fumadocs and MDX. 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.

Configuration

The documentation system can be configured in multiple places:

1. The main layout configuration is in src/app/[locale]/docs/layout.tsx
2. The content source configuration is in src/lib/docs/source.ts
3. The i18n configuration is in src/lib/docs/i18n.ts

Creating Documentation Content

Adding a New Documentation Page

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

2. 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"]
    }
  ]
}

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:

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

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:

1. Add your component to the src/components/shared/custom-mdx-content.tsx file
2. Map it to the appropriate MDX element in the components object

Example of customizing the img tag to use a enhanced ImageZoom component:

// ... existing components and imports ...
 
// Add to the baseComponents object in CustomMDXContent:
{
  // ... other components ...
  
  // Custom img component that uses ImageZoom
  img: (props: ComponentProps<'img'>) => {
    if (!props.src) {
      return null;
    }
 
    return (
      <ImageZoom
        src={props.src}
        alt={props.alt || 'image'}
        width={1400}
        height={787}
        style={{
          width: '100%',
          height: 'auto',
          objectFit: 'contain',
        }}
        priority
      />
    );
  },
}

This customization enhances all images in your MDX content with zoom functionality, responsive sizing, and improved loading performance. You can use standard Markdown syntax in your MDX files and the custom component will automatically be applied:

---
title: My Page with Enhanced Images
description: A page with custom image component
icon: Image
---
 
# Enhanced Images Example
 
![Example image description](/images/example.jpg)
 
The image above will automatically use the ImageZoom component with all the configured enhancements.

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

Next Steps

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