OceanBase Documentation Formatting

This skill ensures all OceanBase documentation follows consistent formatting standards and markdown lint rules.

Meta information format

Always use table format, NOT YAML frontmatter:

Important:

• Default: Only fill description and keywords
• Fill tenant-type only when document applies to specific mode
• Do NOT delete machine-translation field if present
• All descriptions must end with period (句号)

Notice boxes

说明 (Explain) - For explanations

Use for explaining complex concepts, providing background, or detailed clarifications:

<main id="notice" type='explain'> <h4>说明</h4> <p>不支持 <code>CREATE TABLE AS SELECT</code>。</p> </main>

注意 (Notice) - For warnings

Use for warnings, limitations, or important alerts:

<main id="notice" type='notice'> <h4>注意</h4> <p>不支持修改关联 OCP 的 <strong>OCP 名</strong> 和 <strong>服务地址</strong>。</p> </main>

Formatting:

• Use single quotes for type attribute: type='explain' or type='notice'
• Use <h4> for heading
• Use <p> for content
• Use <code> for inline code
• Use <strong> for emphasis

Spacing rules

Follow these spacing requirements:

1. Title and body: Space between title and body text
2. Body and code blocks: Space between body text and code blocks
3. Body and tables: Space between body text and tables
4. Sections: Space between major sections

Example:

## Syntax

ALTER SYSTEM KILL SESSION 'session_id';

## Parameters

Markdown lint compliance

• Use proper heading hierarchy (#, ##, ###)
• Code blocks must specify language: ``sql, ``json, etc.
• Tables should have proper alignment
• Lists should use consistent formatting
• No trailing whitespace
• Proper line breaks

Video cards

For video content:

<div role="videolist"> <a role='video' data-code='在 boss 后台获取视频的 code' href='视频地址'> <img src='图标地址'/> 填写需要在卡片里展示的文案 </a> <a role='link' href='链接地址'> <img src='图标地址'/> 填写需要在卡片里展示的文案 </a> </div>

Download cards

For download links:

<div role="videolist"> <a role='link' href='链接地址'> <img src='图标地址'/> 填写需要在卡片里展示的文案 </a> </div>

Download icon URL:

https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/download.png

Notes:

• Use role='link' for direct file downloads
• Each <a> tag represents one card
• Use the provided download icon URL for download cards

Code block formatting

For existing code (code references)

Use this format when referencing existing code:

startLine:endLine:filepath
// code content here

Requirements:

• Include startLine and endLine (required)
• Include full filepath (required)
• Include at least 1 line of actual code
• Do NOT add language tags
• Do NOT indent triple backticks

For new code (markdown code blocks)

Use standard markdown with language tag:

ALTER SYSTEM KILL SESSION 'session_id';

Requirements:

• Always specify language
• No line numbers
• Do NOT indent triple backticks

Table formatting

• Include header row
• Use proper alignment
• Keep content concise
• Use code formatting for technical terms in cells

Example:

Quality checks

Before finalizing:

• Meta table format (not YAML)
• Notice boxes use correct format
• Proper spacing throughout
• Markdown lint compliant
• Code blocks have language tags
• Tables properly formatted
• No trailing whitespace