Documentation Development Guide

About the Framework

nextra

Documentation Writing Guidelines

Naming

All file and directory names should be in lowercase, separated by underscores. For example: development_guide.mdx, design_components.mdx.

Sidebar Structure

Define the sidebar structure and article order in the app/_meta.global.js file

TDK

Add TDK (Title, Description, Keywords) information on the first line of each article in the following format:


---
title: Documentation Development Guide
description: Documentation development guide, introducing how to write and maintain documentation
keywords: documentation development, nextra, markdown, TDK
---

Heading Structure

Document headings start with #, where level-1 headings use #, level-2 headings use ##, level-3 headings use ###, and so on. Avoid using numbers in headings and keep them as concise and clear as possible.

Code Blocks

Code blocks Use triple backticks ``` to wrap code blocks. You can specify the language as bash, javascript, etc.
Variables Use single backticks ` to wrap variable names, for example: variableName.

HTML Tag Syntax

Use <tagname> tags to insert HTML elements, for example:


<div class="custom-class">Custom content</div>

⚠️

Note: When using HTML tags, ensure they are properly closed and comply with HTML standards.

Images

Markdown Image Syntax

Use ![]() syntax to insert images. Add alternative text in square brackets and the image URL in parentheses. For example:


![Momen Logo](https://docs.momen.app/assets/images/logo.png)

HTML Image Syntax

Use <img> tags to insert images. You can specify the src attribute as the image URL and the width attribute to set the image width. For example:


<img src="https://docs.momen.app/assets/images/logo.png" width="100%" />

Image Paths and Upload Script

During local development, image resources can be placed in the public/assets/images/ directory. When referencing them in documentation, use the following format: /assets/images/logo.png

The upload script will automatically upload these images to OSS, generate corresponding links to replace the content in the documentation, and delete local image resources.

After completing local development, run the following command in the momen-docs directory to upload images:


./upload_assets.sh

Videos

Same as Images syntax, use ![]() or <video> tags to insert videos.


![Momen Demo Video](https://docs.momen.app/assets/videos/demo.mp4)


<video
  src="https://docs.momen.app/assets/videos/demo.mp4"
  controls
  width="100%"
></video>

Video resources are also stored in the public/assets/videos/ directory. When using them in documentation, use the following format: /assets/videos/demo.mp4

After completing local development, run the same command in the momen-docs directory to upload videos:


./upload_assets.sh

Links

Internal Links

Use square brackets [] to wrap link text, followed by parentheses () containing the link address. For example:


[Documentation Development Guide](/help/development)

Tips: Internal links need to be verified through local preview. Some article paths may require special paths due to aliases defined in _meta.global.js.

External Links

Use square brackets [] to wrap link text, followed by parentheses () containing the link address, with https:// prefix. For example:


[Momen Official Website](https://momen.app)

Preview

Open the `momen-docs` Directory in Your Editor

Open the momen-docs directory in your preferred editor

Environment Setup


# Install pnpm
npm install -g pnpm
# Install dependencies
pnpm install --registry=https://npm.functorz.work

Tips: Install the mdx plugin in your editor for a better editing experience.

Local Preview


pnpm run dev

Tips: When the previewed docs CSS is abnormal, manually delete the dist directory and re-preview.

Local Build

Tips: The search functionality requires a local build to work


pnpm run build

Publish

Code Commit


git add .
 
arc diff

Wait for code review

After review approval:


arc land

CI automatically builds, overwrites OSS files, and refreshes CDN

After landing is complete, switch back to master branch locally:


git checkout master


git status
git log
git pull
 
git status
git add . / arc diff
 
arc diff
 
arc land

Other Commands


# Fix code lint issues
pnpm run lint:fix
 
# Generate sitemap, creates sitemap.xml file in current directory
pnpm run gen:sitemap