gh-netresearch-claude-code-marketplace-netresearch-skills-bundle/skills/typo3-docs/references/typo3-directives.md

TYPO3-Specific Directives

Comprehensive reference for TYPO3-specific RST directives and extensions.

Permalink Anchors (Labels)

Every section in TYPO3 documentation MUST have a permalink anchor (label) for deep linking.

Syntax:

..  _section-name-label:

Section heading
===============

Requirements:

• Place label immediately before the section heading (no blank line between)
• Use lowercase with hyphens (-) as separators
• Use descriptive, hierarchical names reflecting the document structure
• Labels enable :ref: cross-references and URL anchors

Example from Mass Approval documentation:

..  _crowdin-mass-approval:

========================
Mass approval on Crowdin
========================

..  _crowdin-mass-approval-workflow:

Crowdin API workflow
====================

..  _crowdin-mass-approval-api:

API endpoints
-------------

..  _crowdin-mass-approval-authentication:

Authentication
--------------

..  _crowdin-mass-approval-implementation:

PHP implementation
==================

..  _crowdin-mass-approval-implementation-usage:

Usage
-----

..  _crowdin-mass-approval-best-practices:

Best practices
==============

..  _crowdin-mass-approval-best-practices-error:

Error handling
--------------

Naming Convention:

• Start with document/topic prefix: crowdin-mass-approval
• Add section hierarchy: crowdin-mass-approval-workflow
• Add subsection: crowdin-mass-approval-implementation-usage
• This creates predictable, navigable anchor URLs

Benefits:

• Direct linking to specific sections
• Stable URLs for documentation references
• Cross-document :ref: linking
• Search engine indexability

Configuration Values (confval)

Document configuration options with structured metadata.

Basic Syntax:

.. confval:: settingName

   :type: boolean
   :Default: true
   :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['setting']

   Description of the configuration value.

Field Types:

• :type: - boolean, string, integer, array, object
• :Default: - Default value (capitalize 'Default')
• :Path: - Full path to the setting in TYPO3 configuration
• :Scope: - Where setting applies (frontend, backend, global)

Example:

.. confval:: fetchExternalImages

   :type: boolean
   :Default: true
   :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image']['fetchExternalImages']

   Controls whether external image URLs are automatically fetched and uploaded
   to the current backend user's upload folder. When enabled, pasting image
   URLs will trigger automatic download and FAL integration.

TSConfig Example:

.. confval:: RTE.default.buttons.image.options.magic.maxWidth

   :type: integer
   :Default: 300

   Maximum width in pixels for images inserted through the RTE.
   Images exceeding this width will be automatically scaled down.

YAML Configuration Example:

.. confval:: editor.externalPlugins.typo3image.allowedExtensions

   :type: string
   :Default: Value from ``$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']``

   Comma-separated list of allowed image file extensions for the CKEditor
   image plugin. Overrides global TYPO3 image extension settings.

Two-Level Configuration Pattern

Pattern: Site-wide configuration with per-item override capability

Many TYPO3 features support two-level configuration:

1. Site-wide default via TypoScript
2. Per-item override via attributes or UI

When to use:

• Features where editors need item-specific control
• Mixed content pages (some items use site-wide, others override)
• Configuration that varies by context or workflow

Documentation Structure:

## Configuration

The noScale feature can be configured at two levels:

1. **Site-wide (TypoScript)** - Default behavior for all images
2. **Per-image (Editor)** - Override for specific images

### Site-Wide Configuration

.. confval:: noScale

   :type: boolean
   :Default: false (auto-optimization enabled)
   :Path: lib.parseFunc_RTE.tags.img.noScale

   Controls whether images are automatically optimized or used as original files.
   When enabled, all images skip TYPO3's image processing.

   **Configuration Priority:**

   - **Per-image setting** (data-noscale attribute) takes precedence
   - **Site-wide setting** (TypoScript) is the fallback
   - **Default behavior** when neither is set

   **Enable for all images:**

   .. code-block:: typoscript
      :caption: setup.typoscript

      lib.parseFunc_RTE {
          tags.img {
              noScale = 1  # All images use original files
          }
      }

### Per-Image Override

.. versionadded:: 13.0.0
   Editors can now enable noScale for individual images using the CKEditor
   image dialog, overriding the site-wide TypoScript setting.

**How to Use:**

1. Insert or edit an image in CKEditor
2. Open the image dialog (double-click or select + click insert image button)
3. Check "Use original file (noScale)" checkbox
4. Save the image

**Configuration Priority:**

- **Per-image setting** (data-noscale attribute) overrides site-wide configuration
- If unchecked: Falls back to site-wide TypoScript setting
- If no site-wide setting: Default behavior (auto-optimization)

**Workflow Benefits:**

- **Mixed Content**: Some images original, others optimized on same page
- **Editorial Control**: Editors decide per-image without developer intervention
- **Flexibility**: Override site-wide settings for specific images
- **Newsletter Integration**: Mark high-quality images for email

**Technical Implementation:**

.. code-block:: html

   <!-- Per-image override via data attribute -->
   <img src="image.jpg" data-noscale="true" />

Example from t3x-rte_ckeditor_image:

The noScale feature uses this pattern:

• Site-wide: lib.parseFunc_RTE.tags.img.noScale = 1 in TypoScript
• Per-image: Checkbox in CKEditor dialog sets data-noscale attribute
• Priority: Per-image attribute overrides TypoScript setting

Documentation Benefits:

✅ Clear separation of site-wide vs per-item configuration ✅ Explicit priority/precedence rules documented ✅ Workflow guidance for editors ✅ Technical implementation details for developers ✅ Use case explanations (mixed content, newsletters)

Version Information

Document version-specific changes with proper directives.

Version Added:

.. versionadded:: 13.0.0
   The CKEditor plugin now requires ``StyleUtils`` and ``GeneralHtmlSupport``
   dependencies for style functionality. Previous versions did not have this requirement.

Version Changed:

.. versionchanged:: 13.1.0
   Image processing now uses TYPO3's native image processing service instead
   of custom processing logic.

Deprecated:

.. deprecated:: 13.2.0
   The ``oldSetting`` configuration option is deprecated. Use ``newSetting`` instead.
   This option will be removed in version 14.0.0.

Placement: Place version directives immediately before or after the relevant content they describe.

PHP Domain

Document PHP classes, methods, and properties.

Class:

.. php:class:: SelectImageController

   Main controller for image selection wizard.

   Extends: ``TYPO3\\CMS\\Backend\\Controller\\ElementBrowserController``

Method:

.. php:method:: infoAction(ServerRequestInterface $request): ResponseInterface

   Retrieves image information and processed file details.

   :param \\Psr\\Http\\Message\\ServerRequestInterface $request: PSR-7 server request
   :returns: JSON response with image data or error response
   :returntype: \\Psr\\Http\\Message\\ResponseInterface
   :throws \\RuntimeException: When file is not found or invalid

Property:

.. php:attr:: resourceFactory

   :type: \\TYPO3\\CMS\\Core\\Resource\\ResourceFactory

   Resource factory for file operations.

Namespace:

.. php:namespace:: Netresearch\\RteCKEditorImage\\Controller

.. php:class:: SelectImageController

Card Grids

Create visual card layouts for navigation.

Basic Card Grid:

.. card-grid::
    :columns: 1
    :columns-md: 2
    :gap: 4
    :card-height: 100

    ..  card:: 📘 Introduction

        The RTE CKEditor Image extension provides comprehensive image handling
        capabilities for CKEditor in TYPO3.

        ..  card-footer:: :ref:`Read more <introduction>`
            :button-style: btn btn-primary stretched-link

    ..  card:: 🔧 Configuration

        Learn how to configure the extension with TSConfig, YAML, and TypoScript
        settings for your specific needs.

        ..  card-footer:: :ref:`Read more <configuration>`
            :button-style: btn btn-secondary stretched-link

Card Grid Options:

• :columns: - Number of columns (default layout)
• :columns-md: - Columns for medium+ screens
• :gap: - Gap between cards (1-5)
• :card-height: - Card height (100 for equal height)
• :class: - Additional CSS classes

Card Footer Styles:

• btn btn-primary stretched-link - Primary button with full card click
• btn btn-secondary stretched-link - Secondary button with full card click
• btn btn-light stretched-link - Light button

UTF-8 Emoji Icons: Use in card titles for visual appeal:

• 📘 Documentation
• 🔧 Configuration
• 🎨 Design
• 🔍 Search
• ⚡ Performance
• 🛡️ Security
• 📊 API
• 🆘 Troubleshooting

Intersphinx References

Cross-reference TYPO3 core documentation.

TSRef (TypoScript Reference):

:ref:`t3tsref:start`
:ref:`t3tsref:stdwrap`
:ref:`t3tsref:cobj-image`

Core API:

:ref:`t3coreapi:start`
:ref:`t3coreapi:fal`
:ref:`t3coreapi:dependency-injection`

TSConfig:

:ref:`t3tsconfig:start`
:ref:`t3tsconfig:pagetsconfig`

TCA:

:ref:`t3tca:start`
:ref:`t3tca:columns-types`

Fluid:

:ref:`t3viewhelper:start`
:ref:`t3viewhelper:typo3-fluid-image`

Index and Glossary

Index Entry:

.. index:: Image Processing, FAL, CKEditor

.. _image-processing:

Image Processing
================

Glossary:

.. glossary::

   FAL
      File Abstraction Layer - TYPO3's file management system

   Magic Image
      Automatically processed image with dimension constraints

Reference Glossary:

See :term:`FAL` for details.

Tabs

Create tabbed content for multiple options.

.. tabs::

   .. tab:: Composer

      .. code-block:: bash

         composer require netresearch/rte-ckeditor-image

   .. tab:: Extension Manager

      Install via TYPO3 Extension Manager:

      1. Go to Admin Tools > Extensions
      2. Search for "rte_ckeditor_image"
      3. Click Install

Special TYPO3 Directives

Include Partial:

.. include:: ../Includes.rst.txt

File Tree:

.. directory-tree::

   * Classes/

     * Controller/
     * Database/
     * Utils/

   * Resources/

     * Public/

       * JavaScript/

YouTube Video:

.. youtube:: VIDEO_ID

Download Link:

:download:`Download PDF <../_static/manual.pdf>`

Best Practices

1. Use confval for all configuration: Document every setting with proper metadata
2. Version everything: Add versionadded/versionchanged for all version-specific features
3. Cross-reference liberally: Link to related documentation with :ref:
4. Card grids for navigation: Use card-grid layouts for Index.rst files
5. Emoji icons in titles: Use UTF-8 emojis in card titles for visual appeal
6. Stretched links: Always use stretched-link class in card-footer for full card clicks
7. PHP domain for APIs: Document all public methods with php:method
8. Intersphinx for core: Reference TYPO3 core docs with intersphinx

Quality Checklist

✅ All configuration options documented with confval ✅ Version information added for all version-specific features ✅ Cross-references work (no broken :ref: links) ✅ Card grids use stretched-link in card-footer ✅ UTF-8 emoji icons in card titles ✅ PHP API documented with php:method ✅ Code blocks specify language ✅ Admonitions used appropriately ✅ Local render shows no warnings ✅ All headings have proper underlines ✅ Sentence case used for all headlines (not Title Case) ✅ Permalink anchors (.. _label:) before every section heading ✅ List punctuation: all list items end with periods ✅ CGL compliance: PHP code examples pass make fix-cgl

References

• TYPO3 Documentation Guide: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
• Confval Reference: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html
• Version Directives: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Versions.html
• PHP Domain: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html
• Card Grid: https://sphinxcontrib-typo3-theme.readthedocs.io/en-us/latest/