docs-doc-principle

Enforce retikz documentation standards across content, routing data, and bilingual i18n.

12|2|Updated Nov 27, 2024
One-click install
npx skills add https://github.com/Pionpill/retikz --skill docs-doc-principle
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: docs-doc-principle
Source: https://github.com/Pionpill/retikz/tree/main/.agents/skills/docs-doc-principle
Command: npx skills add https://github.com/Pionpill/retikz --skill docs-doc-principle

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

解决 retikz 文档站在内容、注册数据与 i18n 三处不同步导致 404、菜单与标题错乱、以及页面结构不一致导致阅读体验差的问题。

Core Features & Use Cases

  • 三处协同约束:确保内容(contents/)、注册(data/)、文案(i18n/)严格同步,避免页面无法路由或侧栏不显示。
  • 双语与写作风格统一:中文为源语言、英文跟随;规定标题与术语风格、精简写作、读者视角与层级组织。
  • DSL/演示与对照规范:以 DSL 为主、IR 克制;演示与对照必须走对应组件与规则,图示必须使用 retikz 自绘,且位置/关系类 demo 有专门写法。

Quick Start

让 AI 在你新增或改动任意 docs 页时,先依据本 skill 的规则检查三处协同目录、双语 i18n key、页面类型分流与演示图示约束,最后再给出可直接落地的 mdx 与 data/i18n 修改建议。

Frequently Asked Questions about docs-doc-principle

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent 404 errors and broken navigation in bilingual documentation?

Prevent 404 errors and broken navigation by enforcing strict directory/id alignment and synchronizing content, routing data, and i18n keys across all documentation pages.

What is the best way to manage bilingual i18n documentation with Chinese as the source language?

Manage bilingual i18n documentation by using Chinese as the source language and English as the follower, ensuring consistent terminology and style across all translated page types.

How do I standardize demo and figure components in MDX documentation?

Standardize demo and figure components in MDX documentation by mandating retikz-specific components for demos, figures, and comparisons, while using DSL-first authoring with restrained IR.

Why are my documentation sidebar titles mismatched with the actual page content?

Sidebar titles mismatch with actual page content when routing registration data and i18n translation keys are not strictly synchronized with the content directory structure.

Does this documentation standard apply to introduction and schema reference pages?

Yes, this documentation standard applies to all page types including components, examples, concepts, introduction entries, and reference schema dictionary pages.

When do I need to use self-drawn illustrations for position and relationship demos?

Use retikz self-drawn illustrations with specific authoring rules whenever creating position or relationship demos to maintain consistent visual formatting constraints.