amber-moe/oceanbase-doc-skills

Overview

This skill applies OceanBase documentation formatting standards to Markdown content, ensuring consistent meta tables, notice boxes, spacing, and markdown-lint compliance. It is designed for formatting or reviewing OceanBase docs so they meet publishing requirements and style rules.

How this skill works

The skill parses Markdown files and enforces the required meta information table format instead of YAML frontmatter, validates notice box structure, and normalizes spacing between titles, body, code blocks, tables, and sections. It also checks code block language tags, table headers and alignment, list consistency, and other markdown-lint rules, and can output suggested fixes or a cleaned version of the document.

When to use it

• Before publishing OceanBase documentation to ensure compliance with site standards.
• When reviewing or editing existing docs to convert YAML frontmatter to meta tables.
• During CI or pre-commit checks to catch formatting and lint issues early.
• When preparing translated or machine-translated content to preserve required fields.
• While adding code samples, tables, or notice boxes to guarantee correct structure.

Best practices

• Always use the meta information table (not YAML) and include description and keywords by default.
• Keep description sentences ending with a period and avoid deleting machine-translation fields if present.
• Use the prescribed notice box HTML structure with type='explain' or type='notice', <h4>, and <p> tags.
• Specify language tags for all markdown code blocks and use the special format for code references when required.
• Maintain required spacing: title-body, body-code, body-tables, and between major sections.
• Run the skill as part of CI or a pre-push hook to automate quality checks.

Example use cases

• Convert a repository of OceanBase docs from YAML frontmatter to the meta table format and fix missing fields.
• Lint and repair Markdown files to add missing code block language tags and remove trailing whitespace.
• Validate and standardize notice boxes in a set of articles to ensure consistent warning and explanation formatting.
• Generate a report of spacing, table, and heading hierarchy issues for technical writers to correct.
• Normalize video and download cards markup to use the documented role and icon conventions.