typo3-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TYPO3 Documentation Skill

TYPO3 文档技能

Create and maintain TYPO3 extension documentation following official docs.typo3.org standards.

按照官方docs.typo3.org标准创建和维护TYPO3扩展文档。

Core Workflow

核心工作流程

To create or maintain TYPO3 documentation, follow these steps:

Run extraction first to analyze the codebase and identify documentation gaps:
bash
```
scripts/extract-all.sh /path/to/extension
scripts/analyze-docs.sh /path/to/extension
```
This reveals what features exist vs. what is documented.
Consult the appropriate reference file for the task
Use TYPO3-specific directives, not plain text
Run
```
scripts/validate_docs.sh
```
to check syntax
Run
```
scripts/render_docs.sh
```
to build HTML output
Verify rendered output (see Pre-Commit Checklist for required evidence)
Verify README.md and Documentation/ synchronization

Critical: When the user asks to "show docs", render and display HTML output, not raw RST.

要创建或维护TYPO3文档，请遵循以下步骤：

先运行提取脚本以分析代码库并找出文档缺失项：
bash
```
scripts/extract-all.sh /path/to/extension
scripts/analyze-docs.sh /path/to/extension
```
这会显示已有的功能和已文档化的功能之间的差异。
查阅对应任务的参考文件
使用TYPO3专用指令，而非纯文本
运行
```
scripts/validate_docs.sh
```
检查语法
运行
```
scripts/render_docs.sh
```
生成HTML输出
验证渲染后的输出（请参考预提交检查清单获取所需验证依据）
验证README.md与Documentation/目录下内容的一致性

关键提示：当用户要求“展示文档”时，需渲染并显示HTML输出，而非原始RST文件。

Using Reference Documentation

参考文档使用指南

File Structure and Setup

文件结构与配置

When setting up documentation structure, consult

references/file-structure.md

for directory layout, file naming conventions, and required files.

When configuring guides.xml, consult

references/guides-xml.md

for build configuration, project metadata, and interlink settings.

When setting up editor configuration, consult

references/coding-guidelines.md

for .editorconfig requirements, indentation rules, and line length limits.

设置文档结构时，请查阅

references/file-structure.md

获取目录布局、文件命名规范和必填文件说明。

配置guides.xml时，请查阅

references/guides-xml.md

了解构建配置、项目元数据和交叉链接设置。

设置编辑器配置时，请查阅

references/coding-guidelines.md

获取.editorconfig要求、缩进规则和行长度限制。

RST Syntax and Elements

RST语法与元素

When writing RST content, consult

references/rst-syntax.md

for heading levels, lists, tables, and basic formatting.

When using inline code references, consult

references/text-roles-inline-code.md

for text roles like

:php:

:file:

:guilabel:

, and

:ref:

When documenting code, consult

references/code-structure-elements.md

for code blocks, literalinclude, confval directives, and PHP domain syntax.

When using TYPO3-specific directives, consult

references/typo3-directives.md

for confval, versionadded, versionchanged, deprecated, and other TYPO3 directives.

When creating interactive content, consult

references/content-directives.md

for accordion, tabs, card-grid, and admonition directives.

编写RST内容时，请查阅

references/rst-syntax.md

了解标题层级、列表、表格和基础格式。

使用内联代码引用时，请查阅

references/text-roles-inline-code.md

了解

:php:

、

:file:

、

:guilabel:

和

:ref:

等文本角色。

编写代码文档时，请查阅

references/code-structure-elements.md

了解代码块、literalinclude、confval指令和PHP域语法。

使用TYPO3专用指令时，请查阅

references/typo3-directives.md

了解confval、versionadded、versionchanged、deprecated等TYPO3指令。

创建交互式内容时，请查阅

references/content-directives.md

了解accordion、tabs、card-grid和admonition指令。

Images and Screenshots

图片与截图

When adding screenshots, consult

references/screenshots.md

for image requirements, alt text, figure directives, zoom/lightbox options, and screenshot best practices.

MANDATORY: When documenting backend modules, configuration screens, or UI workflows, you MUST take screenshots. Do not proceed without them. See "Screenshot Requirements" below.

添加截图时，请查阅

references/screenshots.md

了解图片要求、替代文本、figure指令、缩放/灯箱选项和截图最佳实践。

强制要求：当记录后端模块、配置界面或UI工作流时，必须截取截图。不得跳过此步骤。请参阅下方的“截图要求”。

Rendering and Deployment

渲染与部署

When rendering documentation locally, consult

references/rendering.md

for Docker commands, live preview, and troubleshooting.

When deploying to docs.typo3.org, consult

references/intercept-deployment.md

for webhook configuration, build triggers, and deployment verification.

本地渲染文档时，请查阅

references/rendering.md

了解Docker命令、实时预览和故障排除方法。

部署到docs.typo3.org时，请查阅

references/intercept-deployment.md

了解webhook配置、构建触发和部署验证步骤。

Advanced Topics

进阶主题

When writing Architecture Decision Records, consult

references/architecture-decision-records.md

for ADR templates, directory structure, and RST formatting.

When analyzing documentation coverage, consult

references/documentation-coverage-analysis.md

for feature coverage methodology and gap analysis.

When extracting documentation from code, consult

references/extraction-patterns.md

for automated extraction workflows and data flow.

When understanding TYPO3 extension structure, consult

references/typo3-extension-architecture.md

for file hierarchy and documentation priority weighting.

编写架构决策记录时，请查阅

references/architecture-decision-records.md

了解ADR模板、目录结构和RST格式。

分析文档覆盖率时，请查阅

references/documentation-coverage-analysis.md

了解功能覆盖率方法和缺失项分析。

从代码中提取文档时，请查阅

references/extraction-patterns.md

了解自动提取工作流和数据流。

了解TYPO3扩展结构时，请查阅

references/typo3-extension-architecture.md

了解文件层级和文档优先级权重。

Running Scripts

运行脚本

Documentation Validation

文档验证

To validate RST syntax before committing:

bash

scripts/validate_docs.sh /path/to/extension

提交前验证RST语法：

bash

scripts/validate_docs.sh /path/to/extension

Documentation Rendering

文档渲染

To render documentation to HTML:

bash

scripts/render_docs.sh /path/to/extension

将文档渲染为HTML：

bash

scripts/render_docs.sh /path/to/extension

Documentation Extraction

文档提取

To extract documentation data from all sources:

bash

scripts/extract-all.sh /path/to/extension

To extract from specific sources:

bash

undefined

从所有来源提取文档数据：

bash

scripts/extract-all.sh /path/to/extension

从特定来源提取：

bash

undefined

Extract PHP API documentation

提取PHP API文档

scripts/extract-php.sh /path/to/extension

Extract extension configuration (ext_emconf.php, ext_localconf.php)

提取扩展配置（ext_emconf.php、ext_localconf.php）

scripts/extract-extension-config.sh /path/to/extension

Extract Composer metadata

提取Composer元数据

scripts/extract-composer.sh /path/to/extension

Extract build configurations (CI, testing)

提取构建配置（CI、测试）

scripts/extract-build-configs.sh /path/to/extension

Extract project files (README, CHANGELOG)

提取项目文件（README、CHANGELOG）

scripts/extract-project-files.sh /path/to/extension

Extract repository metadata (GitHub/GitLab)

提取仓库元数据（GitHub/GitLab）

scripts/extract-repo-metadata.sh /path/to/extension

undefined

scripts/extract-repo-metadata.sh /path/to/extension

undefined

Documentation Analysis

文档分析

To analyze documentation coverage and identify gaps:

bash

scripts/analyze-docs.sh /path/to/extension

分析文档覆盖率并找出缺失项：

bash

scripts/analyze-docs.sh /path/to/extension

AI Context Setup

AI环境设置

To add AGENTS.md template to Documentation/ folder:

bash

scripts/add-agents-md.sh /path/to/extension

将AGENTS.md模板添加到Documentation/目录：

bash

scripts/add-agents-md.sh /path/to/extension

Using Asset Templates

使用资源模板

AI Agent Context

AI Agent 环境

To provide AI assistants with documentation context, copy

assets/AGENTS.md

to the extension's

Documentation/

folder. This template includes:

Documentation type and strategy
Target audience definition
File structure overview
Style guidelines for AI-generated content

为AI助手提供文档上下文时，请将

assets/AGENTS.md

复制到扩展的

Documentation/

目录。该模板包含：

文档类型与策略
目标受众定义
文件结构概述
AI生成内容的风格指南

Screenshot Requirements (MANDATORY)

截图要求（强制）

YOU MUST TAKE SCREENSHOTS when documenting any of the following. This is not optional:

Documentation Topic	Screenshot Required
Backend module interfaces	✅ YES - Show the module UI
Extension configuration screens	✅ YES - Show settings location
Multi-step UI workflows	✅ YES - One screenshot per step
TCA/FlexForm configurations	✅ YES - Show resulting forms
Frontend visual output	✅ YES - Show what users see
Error messages/states	✅ YES - Help users identify issues

记录以下内容时必须截取截图，无例外：

文档主题	是否需要截图
后端模块界面	✅ 是 - 展示模块UI
扩展配置界面	✅ 是 - 展示设置位置
多步骤UI工作流	✅ 是 - 每个步骤一张截图
TCA/FlexForm配置	✅ 是 - 展示生成的表单
前端视觉输出	✅ 是 - 展示用户看到的内容
错误消息/状态	✅ 是 - 帮助用户识别问题

Screenshot Workflow

截图工作流程

Before writing documentation: Identify which screens need screenshots
Set up screenshot environment: Use Docker container or DDEV
Take screenshots: PNG format, 1400x1050 or cropped
Add to documentation: Use figure directive with
```
:zoom: lightbox
```
and
```
:alt:
```
Verify in rendered output: Confirm images display correctly

编写文档前：确定需要截图的界面
设置截图环境：使用Docker容器或DDEV
截取截图：PNG格式，1400x1050像素或裁剪至相关区域
添加到文档：使用figure指令，添加
```
:zoom: lightbox
```
和
```
:alt:
```
在渲染输出中验证：确认图片显示正常

Taking Screenshots

截取截图

Using browser DevTools (Chrome/Firefox):

bash

undefined

使用浏览器开发者工具（Chrome/Firefox）：

bash

undefined

Open DevTools (F12), then:

打开开发者工具（F12），然后：

Ctrl+Shift+P → "Capture screenshot" or "Capture full size screenshot"

Ctrl+Shift+P → “Capture screenshot”或“Capture full size screenshot”


**Using Playwright MCP (automated):**

mcp__playwright__browser_take_screenshot


**Using Chrome DevTools MCP:**

mcp__chrome-devtools__take_screenshot

undefined


**使用Playwright MCP（自动化）：**

mcp__playwright__browser_take_screenshot


**使用Chrome DevTools MCP：**

mcp__chrome-devtools__take_screenshot

undefined

Screenshot Checklist (verify before proceeding)

截图检查清单（继续前请验证）

PNG format used
Light theme in TYPO3 backend
Cropped to relevant area
```
:alt:
```
text describes image content
```
:zoom: lightbox
```
added for click-to-enlarge
```
:class: with-border with-shadow
```
for visual polish
Image stored in
```
Documentation/Images/
```
with CamelCase name

DO NOT write "TODO: add screenshot" or skip screenshots. If you cannot take a screenshot, explicitly ask the user to provide one or use the MCP tools to capture them.

使用PNG格式
TYPO3后端使用浅色主题
裁剪至相关区域
```
:alt:
```
文本描述图片内容
添加
```
:zoom: lightbox
```
支持点击放大
添加
```
:class: with-border with-shadow
```
提升视觉效果
图片存储在
```
Documentation/Images/
```
目录，采用驼峰式命名

禁止写入“TODO: add screenshot”或跳过截图。如果无法截取截图，请明确要求用户提供，或使用MCP工具进行捕获。

Critical Rules

关键规则

UTF-8 encoding, 4-space indentation, 80 character max line length, LF line endings
CamelCase for file and directory names, sentence case for headings
Index.rst required in every subdirectory
PNG format for screenshots with
```
:alt:
```
text and
```
:zoom: lightbox
```
.editorconfig required in
```
Documentation/
```
directory

使用UTF-8编码、4空格缩进、每行最多80字符、LF换行符
文件和目录名采用驼峰式，标题采用句首大写格式
每个子目录必须包含Index.rst
截图采用PNG格式，需添加
```
:alt:
```
文本和
```
:zoom: lightbox
```
```
Documentation/
```
目录下必须包含**.editorconfig**

Element Selection Guide

元素选择指南

Content Type	Directive to Use
Code (5+ lines)	`literalinclude` (preferred)
Short code snippets	`code-block` with `:caption:`
Configuration options	`confval` with `:type:` , `:default:`
PHP API documentation	`php:class::` , `php:method::`
Important notices	`note` , `tip` , `warning` , `important`
Feature grids	`card-grid`
Alternative approaches	`tabs` (synchronized)
Collapsible content	`accordion`
UI/Backend screenshots	`figure` with `:zoom: lightbox` `:class: with-border with-shadow`
Tutorial steps	`figure` with `:zoom: gallery` `:gallery: group-name`
Technical diagrams	`figure` with `:zoom: inline` for scroll-to-zoom

内容类型	应使用的指令
代码（5行以上）	`literalinclude` （优先）
短代码片段	`code-block` 并添加 `:caption:`
配置选项	`confval` 并添加 `:type:` 、 `:default:`
PHP API文档	`php:class::` 、 `php:method::`
重要提示	`note` 、 `tip` 、 `warning` 、 `important`
功能网格	`card-grid`
替代方案	`tabs` （同步）
可折叠内容	`accordion`
UI/后端截图	`figure` 并添加 `:zoom: lightbox` `:class: with-border with-shadow`
教程步骤	`figure` 并添加 `:zoom: gallery` `:gallery: group-name`
技术图表	`figure` 并添加 `:zoom: inline` 支持滚动缩放

Pre-Commit Checklist

预提交检查清单

```
.editorconfig
```
exists in
```
Documentation/
```
Every directory has
```
Index.rst
```
with CamelCase naming
4-space indentation, no tabs, max 80 characters per line
Code blocks have
```
:caption:
```
and valid syntax highlighting
Inline code uses appropriate roles (
```
:php:
```
,
```
:file:
```
,
```
:typoscript:
```
)
Screenshots exist for all backend modules, config screens, and UI workflows
All images have
```
:alt:
```
text and
```
:zoom: lightbox
```
(or appropriate zoom mode)
```
scripts/validate_docs.sh
```
passes without errors
Render verification evidence required - After
```
scripts/render_docs.sh
```
, verify and confirm:
- No warnings or errors in render output
- Card grids display correctly (no broken layouts)
- Cross-references resolve (no broken
```
:ref:
```
  links)
- Images/screenshots load and display
README ↔ Documentation sync verified - After edits, confirm:
- Feature descriptions match between README.md and Documentation/Index.rst
- Installation instructions are identical
- Configuration examples are consistent
- Version/compatibility info is synchronized

```
Documentation/
```
目录下存在
```
.editorconfig
```
每个目录都有驼峰式命名的
```
Index.rst
```
使用4空格缩进，无制表符，每行最多80字符
代码块包含
```
:caption:
```
和有效的语法高亮
内联代码使用合适的角色（
```
:php:
```
、
```
:file:
```
、
```
:typoscript:
```
）
所有后端模块、配置界面和UI工作流均已添加截图
所有图片都有
```
:alt:
```
文本和
```
:zoom: lightbox
```
（或合适的缩放模式）
```
scripts/validate_docs.sh
```
运行无错误
需要提供渲染验证依据 - 运行
```
scripts/render_docs.sh
```
后，需验证并确认：
- 渲染输出无警告或错误
- 卡片网格显示正常（无布局错乱）
- 交叉引用可正确解析（无失效的
```
:ref:
```
  链接）
- 图片/截图可正常加载显示
已验证README与文档内容同步 - 编辑后需确认：
- README.md与Documentation/Index.rst中的功能描述一致
- 安装说明完全相同
- 配置示例保持一致
- 版本/兼容性信息同步

External Resources

外部资源

When understanding TYPO3 documentation standards, consult the TYPO3 Documentation Writing Guide.

When seeking rendering tool documentation, consult the TYPO3 Documentation Rendering.

When checking directive syntax, consult the TYPO3 Documentation Reference.

Contributing: https://github.com/netresearch/typo3-docs-skill

了解TYPO3文档标准时，请查阅TYPO3文档编写指南。

查阅渲染工具文档时，请访问TYPO3文档渲染工具。

检查指令语法时，请查阅TYPO3文档参考手册。

贡献指南：https://github.com/netresearch/typo3-docs-skill