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.

TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in your target TYPO3 version (v13 or v14) by checking the official TYPO3 documentation.

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

TYPO3 API优先原则： 在创建自定义实现之前，请始终使用TYPO3的内置API、核心功能和既定约定。不要重复造TYPO3已有的轮子。请务必通过官方TYPO3文档验证你使用的API和方法在目标TYPO3版本（v13或v14）中存在且未被弃用。

When to Use

适用场景

Creating documentation from scratch (no
```
Documentation/
```
exists)
Editing
```
Documentation/**/*.rst
```
files
Using TYPO3 directives:
```
confval
```
,
```
versionadded
```
,
```
card-grid
```
,
```
tabs
```
Creating/adding screenshots
Rendering and testing documentation locally
Deploying to docs.typo3.org

从零开始创建文档（不存在
```
Documentation/
```
目录）
编辑
```
Documentation/**/*.rst
```
文件
使用TYPO3指令：
```
confval
```
、
```
versionadded
```
、
```
card-grid
```
、
```
tabs
```
创建/添加截图
本地渲染和测试文档
将文档部署至docs.typo3.org

Documentation Structure

文档结构

Documentation/
├── Index.rst                 # Main entry point
├── guides.xml                # Configuration file
├── Introduction/
│   └── Index.rst
├── Installation/
│   └── Index.rst
├── Configuration/
│   └── Index.rst
├── Usage/
│   └── Index.rst
├── Developer/
│   └── Index.rst
└── Images/
    └── screenshot.png

Documentation/
├── Index.rst                 # 主入口文件
├── guides.xml                # 配置文件
├── Introduction/
│   └── Index.rst
├── Installation/
│   └── Index.rst
├── Configuration/
│   └── Index.rst
├── Usage/
│   └── Index.rst
├── Developer/
│   └── Index.rst
└── Images/
    └── screenshot.png

Creating Documentation from Scratch

从零开始创建文档

When no

Documentation/

directory exists, use the init command:

bash

docker run --rm --pull always -v $(pwd):/project -it \
  ghcr.io/typo3-documentation/render-guides:latest init

Interactive prompts:

Format: Choose
```
rst
```
(ReStructuredText) for full TYPO3 theme features
Site Set: Enter name/path if extension defines a Site set

当不存在

Documentation/

目录时，使用初始化命令：

bash

docker run --rm --pull always -v $(pwd):/project -it \
  ghcr.io/typo3-documentation/render-guides:latest init

交互式提示：

格式：选择
```
rst
```
（ReStructuredText）以使用完整的TYPO3主题功能
站点集：如果扩展定义了站点集，请输入名称/路径

guides.xml Configuration

guides.xml 配置

xml

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://docs.typo3.org/render-guides/guides.xsd">
    <project title="My Extension"/>
    <extension name="my_extension"/>
</guides>

xml

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://docs.typo3.org/render-guides/guides.xsd">
    <project title="My Extension"/>
    <extension name="my_extension"/>
</guides>

With GitHub Integration

集成GitHub

xml

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://docs.typo3.org/render-guides/guides.xsd">
    <project title="My Extension" version="1.0.0"/>
    <extension name="my_extension"/>
    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
    <settings>
        <setting name="edit_on_github" value="https://github.com/vendor/my-extension/edit/main/Documentation/"/>
        <setting name="edit_on_github_branch" value="main"/>
    </settings>
</guides>

xml

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://docs.typo3.org/render-guides/guides.xsd">
    <project title="My Extension" version="1.0.0"/>
    <extension name="my_extension"/>
    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
    <settings>
        <setting name="edit_on_github" value="https://github.com/vendor/my-extension/edit/main/Documentation/"/>
        <setting name="edit_on_github_branch" value="main"/>
    </settings>
</guides>

RST Syntax Reference

RST语法参考

Headings

标题

rst

==========
Page Title
==========

Section
=======

Subsection
----------

Subsubsection
~~~~~~~~~~~~~

rst

==========
页面标题
==========

章节
=======

子章节
----------

子子章节
~~~~~~~~~~~~~

Code Blocks

代码块

rst

..  code-block:: php
    :caption: Classes/Service/MyService.php

    <?php
    declare(strict_types=1);

    namespace Vendor\MyExtension\Service;

    final class MyService
    {
        // ...
    }

rst

..  code-block:: php
    :caption: Classes/Service/MyService.php

    <?php
    declare(strict_types=1);

    namespace Vendor\MyExtension\Service;

    final class MyService
    {
        // ...
    }

Inline Code and Text Roles

行内代码与文本角色

rst

Use :php:`MyClass` for PHP references.
The file :file:`ext_localconf.php` is loaded automatically.
Click :guilabel:`Save` to apply changes.
Press :kbd:`Ctrl+S` to save.

rst

使用:php:`MyClass`引用PHP类。
文件:file:`ext_localconf.php`会自动加载。
点击:guilabel:`保存`以应用更改。
按:kbd:`Ctrl+S`保存。

Links and References

链接与引用

rst

See :ref:`my-reference-label` for more information.

External link: `TYPO3 Documentation <https://docs.typo3.org/>`__

..  _my-reference-label:

Section with Reference
======================

This section can be referenced from anywhere.

rst

更多信息请参考:ref:`my-reference-label`。

外部链接：`TYPO3文档 <https://docs.typo3.org/>`__

..  _my-reference-label:

带引用的章节
======================

本章节可从任意位置引用。

TYPO3 Directives

TYPO3 指令

confval (Configuration Values)

confval（配置项）

rst

..  confval:: encryptionMethod
    :name: ext-myext-encryptionMethod
    :type: string
    :default: 'aes-256-gcm'
    :required: false

    The encryption method to use for API keys.

    Available options:

    -   ``aes-256-gcm`` (recommended)
    -   ``aes-256-cbc``

rst

..  confval:: encryptionMethod
    :name: ext-myext-encryptionMethod
    :type: string
    :default: 'aes-256-gcm'
    :required: false

    用于API密钥的加密方式。

    可用选项：

    -   ``aes-256-gcm``（推荐）
    -   ``aes-256-cbc``

versionadded / versionchanged / deprecated

rst

..  versionadded:: 2.0.0
    This feature was added in version 2.0.0.

..  versionchanged:: 2.1.0
    The default value was changed from ``false`` to ``true``.

..  deprecated:: 3.0.0
    Use :php:`newMethod()` instead.

rst

..  versionadded:: 2.0.0
    此功能在2.0.0版本中新增。

..  versionchanged:: 2.1.0
    默认值从``false``改为``true``。

..  deprecated:: 3.0.0
    请改用:php:`newMethod()`。

Admonitions

提示框

rst

..  note::
    Background information users should know.

..  tip::
    Helpful suggestion for better results.

..  warning::
    Potential issue or data loss risk.

..  important::
    Critical information that must not be missed.

rst

..  note::
    用户需要了解的背景信息。

..  tip::
    有助于获得更好结果的建议。

..  warning::
    潜在问题或数据丢失风险。

..  important::
    必须注意的关键信息。

Tabs

标签页

rst

..  tabs::

    ..  group-tab:: Composer

        Install via Composer:

        ..  code-block:: bash

            composer require vendor/my-extension

    ..  group-tab:: TER

        Download from the TYPO3 Extension Repository.

rst

..  tabs::

    ..  group-tab:: Composer

        通过Composer安装：

        ..  code-block:: bash

            composer require vendor/my-extension

    ..  group-tab:: TER

        从TYPO3扩展仓库下载。

Card Grid

卡片网格

rst

..  card-grid::
    :columns: 2
    :card-height: 100

    ..  card:: Installation

        Learn how to install the extension.

        :ref:`Read more <installation>`

    ..  card:: Configuration

        Configure the extension for your needs.

        :ref:`Read more <configuration>`

rst

..  card-grid::
    :columns: 2
    :card-height: 100

    ..  card:: 安装

        了解如何安装本扩展。

        :ref:`阅读更多 <installation>`

    ..  card:: 配置

        根据需求配置扩展。

        :ref:`阅读更多 <configuration>`

Accordion

折叠面板

rst

..  accordion::

    ..  accordion-item:: How do I install this extension?

        See the :ref:`installation` chapter.

    ..  accordion-item:: What PHP version is required?

        PHP 8.2 or higher is required.

rst

..  accordion::

    ..  accordion-item:: 如何安装此扩展？

        请查看:ref:`installation`章节。

    ..  accordion-item:: 需要什么版本的PHP？

        需要PHP 8.2或更高版本。

Editor Configuration

编辑器配置

Create

Documentation/.editorconfig

editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
max_line_length = 80

创建

Documentation/.editorconfig

文件：

editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
max_line_length = 80

Rendering Documentation

文档渲染

Local Rendering

本地渲染

bash

undefined

bash

undefined

Render documentation

渲染文档

docker run --rm --pull always -v $(pwd):/project -it
ghcr.io/typo3-documentation/render-guides:latest

Output is in Documentation-GENERATED-temp/

输出文件在Documentation-GENERATED-temp/目录下

undefined

undefined

With Live Preview

实时预览

bash

undefined

bash

undefined

Start watch mode for live preview

启动监听模式实现实时预览

docker run --rm --pull always -v $(pwd):/project -p 8080:8080 -it
ghcr.io/typo3-documentation/render-guides:latest --watch

Open http://localhost:8080 in browser

在浏览器中打开http://localhost:8080

undefined

undefined

Validation

语法验证

bash

undefined

bash

undefined

Validate RST syntax

验证RST语法

docker run --rm --pull always -v $(pwd):/project -it
ghcr.io/typo3-documentation/render-guides:latest --no-progress --fail-on-log

undefined

docker run --rm --pull always -v $(pwd):/project -it
ghcr.io/typo3-documentation/render-guides:latest --no-progress --fail-on-log

undefined

Screenshots

截图规范

Requirements

要求

PNG format
72 DPI
Appropriate size (not too large)
Always include
```
:alt:
```
text

PNG格式
72 DPI
尺寸合适（不宜过大）
必须添加
```
:alt:
```
替代文本

Adding Screenshots

添加截图

rst

..  figure:: /Images/BackendModule.png
    :alt: Backend module screenshot
    :class: with-shadow

    The backend module provides an overview of all items.

rst

..  figure:: /Images/BackendModule.png
    :alt: 后台模块截图
    :class: with-shadow

    后台模块展示所有项目的概览。

Screenshot Directory

截图目录结构

Documentation/
└── Images/
    ├── BackendModule.png
    ├── Configuration.png
    └── Frontend.png

Documentation/
└── Images/
    ├── BackendModule.png
    ├── Configuration.png
    └── Frontend.png

Writing Guidelines

编写规范

General Rules

通用规则

Use American English spelling (color, behavior, optimize)
Use sentence case for headings (not Title Case)
Maximum line length: 80 characters
Use 4 spaces for indentation (no tabs)
Add blank line before and after code blocks
Use present tense

使用美式英语拼写（如color、behavior、optimize）
标题采用句首大写格式（而非每个单词首字母大写）
每行最大长度：80个字符
使用4个空格缩进（禁止使用制表符）
代码块前后需添加空行
使用一般现在时

CamelCase for Files

文件名采用驼峰命名

```
Index.rst
```
(not
```
index.rst
```
)
```
Configuration/
```
(not
```
configuration/
```
)
```
BackendModule.png
```
(not
```
backend-module.png
```
)

```
Index.rst
```
（而非
```
index.rst
```
）
```
Configuration/
```
（而非
```
configuration/
```
）
```
BackendModule.png
```
（而非
```
backend-module.png
```
）

Example: Good Documentation

优秀文档示例

rst

============
Installation
============

This chapter explains how to install the extension.

Requirements
============

-   TYPO3 v13.4 or v14.x
-   PHP 8.2 or higher

Installation via Composer
=========================

Run the following command:

..  code-block:: bash

    composer require vendor/my-extension

After installation, activate the extension:

..  code-block:: bash

    vendor/bin/typo3 extension:activate my_extension

rst

============
安装指南
============

本章说明如何安装本扩展。

系统要求
============

-   TYPO3 v13.4或v14.x
-   PHP 8.2或更高版本

通过Composer安装
=========================

执行以下命令：

..  code-block:: bash

    composer require vendor/my-extension

安装完成后，激活扩展：

..  code-block:: bash

    vendor/bin/typo3 extension:activate my_extension

Deployment to docs.typo3.org

部署至docs.typo3.org

Prerequisites

前提条件

Extension registered on extensions.typo3.org
Documentation in
```
Documentation/
```
directory
Valid
```
guides.xml
```
configuration

扩展已在extensions.typo3.org注册
文档存放在
```
Documentation/
```
目录下
```
guides.xml
```
配置有效

Webhook Setup

Webhook设置

Go to https://intercept.typo3.com/
Login with TYPO3.org account
Register your repository
Add webhook to GitHub/GitLab

访问https://intercept.typo3.com/
使用TYPO3.org账号登录
注册你的代码仓库
为GitHub/GitLab添加Webhook

Trigger Rendering

触发渲染

Documentation is automatically rendered when:

Webhook receives push event
Manual trigger via Intercept

满足以下条件时，文档会自动渲染：

Webhook接收到推送事件
通过Intercept手动触发

Complete Index.rst Example

完整Index.rst示例

rst

..  include:: /Includes.rst.txt

.. _start:

==============
My Extension
==============

:Extension key:
    my_extension

:Package name:
    vendor/my-extension

:Version:
    |release|

:Language:
    en

:Author:
    Your Name

:License:
    This document is published under the
    `Creative Commons BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__
    license.

:Rendered:
    |today|

----

This extension provides functionality for managing items.

----

**Table of Contents**

..  toctree::
    :maxdepth: 2
    :titlesonly:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Developer/Index

..  toctree::
    :hidden:

    Sitemap

rst

..  include:: /Includes.rst.txt

.. _start:

==============
我的扩展
==============

:扩展密钥:
    my_extension

:包名称:
    vendor/my-extension

:版本:
    |release|

:语言:
    en

:作者:
    你的姓名

:许可证:
    本文档采用`知识共享署名4.0国际许可协议 <https://creativecommons.org/licenses/by/4.0/>`__发布。

:渲染时间:
    |today|

----

本扩展提供项目管理功能。

----

**目录**

..  toctree::
    :maxdepth: 2
    :titlesonly:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Developer/Index

..  toctree::
    :hidden:

    Sitemap

Resources

参考资源

TYPO3 Documentation Guide: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
RST Primer: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingReST/
Render Guides: https://github.com/TYPO3-Documentation/render-guides
Intercept: https://intercept.typo3.com/

TYPO3文档编写指南：https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
RST入门教程：https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingReST/
Render Guides工具：https://github.com/TYPO3-Documentation/render-guides
Intercept平台：https://intercept.typo3.com/

Credits & Attribution

致谢与贡献

Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.

感谢Netresearch DTT GmbH对TYPO3社区的贡献。