netresearch/typo3-docs-skill / skills/typo3-docs
typo3-docs
FlaggedUse when TYPO3 extension documentation has to render on docs.typo3.org, which builds a manual from Documentation/guides.xml and reads no Settings.cfg (a single README.rst serves an extension too small for one): when an extension has no documentation yet, or when creating, editing or reviewing Documentation/*.rst, guides.xml, README.md or XLF translations, rendering docs with Docker, TYPO3 RST directives, screenshots, or XLIFF 2-space indentation (TYPO3 v14+).
scripts/validate_docs.sh
View on GitHub#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
#
# Validate TYPO3 documentation RST files
#
# Usage: ./validate_docs.sh [project_root]
#
# Exit codes:
# 0 validation ran; findings, if any, are warnings
# 1 the documentation fails a required check
# 3 uv is not on PATH, so the heading check (validate_headings.py,
# Python 3.11 or later through uv run) cannot run
#
set -e
PROJECT_ROOT="${1:-.}"
DOC_DIR="$PROJECT_ROOT/Documentation"
if [ ! -d "$DOC_DIR" ]; then
echo "Error: Documentation/ directory not found at $PROJECT_ROOT"
echo "Usage: $0 [project_root]"
exit 1
fi
echo "đ Validating TYPO3 documentation..."
echo " Directory: $DOC_DIR"
echo ""
# Check for RST files
RST_FILES=$(find "$DOC_DIR" -name "*.rst" 2>/dev/null | wc -l)
if [ "$RST_FILES" -eq 0 ]; then
echo "â No RST files found in Documentation/"
exit 1
fi
echo "Found $RST_FILES RST files"
echo ""
# Check for guides.xml (modern) or Settings.cfg (legacy)
#
# Existence is not enough and used to be all this checked. A file named
# guides.xml containing an invented schema was reported as "found" and the run
# went on to say the documentation was fine â the validator reassured on the
# defect it should have caught. Measured: of ten guides.xml files recorded from
# evaluated agent runs against a real extension, nine will not render, and
# every one of those nine was "found" here. See issue #91.
if [ -f "$DOC_DIR/guides.xml" ]; then
if "$(dirname "$0")/check-guides-xml-schema.sh" "$PROJECT_ROOT"; then
:
else
echo " guides.xml exists but will not render; fix it before continuing"
exit 1
fi
elif [ -f "$DOC_DIR/Settings.cfg" ]; then
echo "â
Settings.cfg found (legacy Sphinx-based rendering)"
echo " âšī¸ Consider migrating to guides.xml for modern rendering"
else
echo "â ī¸ Warning: Neither guides.xml nor Settings.cfg found"
echo " One of these files is required for TYPO3 Intercept builds"
echo " Recommended: Create guides.xml (modern PHP-based rendering)"
fi
# Check for Index.rst
if [ ! -f "$DOC_DIR/Index.rst" ]; then
echo "â Error: Index.rst not found"
echo " This is the main entry point and is required"
exit 1
fi
echo "â
Index.rst found"
# Validate RST syntax if rst2html.py is available
if command -v rst2html.py &> /dev/null; then
echo ""
echo "Checking RST syntax..."
ERRORS=0
while IFS= read -r -d '' file; do
if ! rst2html.py --strict "$file" > /dev/null 2>&1; then
echo "â Syntax error in: $file"
ERRORS=$((ERRORS + 1))
fi
done < <(find "$DOC_DIR" -name "*.rst" -print0)
if [ $ERRORS -eq 0 ]; then
echo "â
All RST files have valid syntax"
else
echo ""
echo "â Found $ERRORS files with syntax errors"
exit 1
fi
else
echo "â ī¸ rst2html.py not found - skipping syntax validation"
echo " Install with: pip install docutils"
fi
# Check for common issues
echo ""
echo "Checking for common issues..."
# Check for common issues in a single pass over all RST files
WARNINGS=0
HEADING_ERRORS=0
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# The heading check below runs validate_headings.py through uv. Without uv the
# command substitution fails and `set -e` would end the run with no message.
if ! command -v uv >/dev/null 2>&1; then
echo "â uv not found: the heading check runs validate_headings.py on Python 3.11 or later through uv run" >&2
echo " Install uv: https://docs.astral.sh/uv/getting-started/installation/" >&2
exit 3
fi
# uv itself exits 2 when it finds no Python 3.11 or later and cannot download
# one; inside the loop that would also end the run with no message. One run on
# an empty input settles it before the first file.
if ! UV_PROBE_ERR=$(uv run "$SCRIPT_DIR/validate_headings.py" /dev/null 2>&1 >/dev/null); then
echo "â uv could not run validate_headings.py on Python 3.11 or later:" >&2
while IFS= read -r line; do echo " $line"; done <<<"$UV_PROBE_ERR" >&2
exit 3
fi
while IFS= read -r -d '' file; do
# Check for :ref: references
# The patterns are single-quoted on purpose: the backticks and brackets
# belong to the RST role and to grep, and letting the shell see them would
# start a command substitution. Pre-existing; surfaced by pre-commit only
# because this file is being touched.
# shellcheck disable=SC2016
if grep -q ':ref:`[^<]*`' "$file"; then
# shellcheck disable=SC2016
REF_COUNT=$(grep -o ':ref:`[^`]*`' "$file" | wc -l)
if [ "$REF_COUNT" -gt 0 ]; then
echo "âšī¸ Found $REF_COUNT :ref: references in $(basename "$file")"
fi
fi
# Check for UTF-8 encoding
if ! file -b --mime-encoding "$file" | grep -qE 'utf-8|us-ascii'; then
echo "â ī¸ Non-UTF-8 encoding in: $file"
WARNINGS=$((WARNINGS + 1))
fi
# Check for trailing whitespace
if grep -q '[[:space:]]$' "$file"; then
echo "â ī¸ Trailing whitespace in: $file"
WARNINGS=$((WARNINGS + 1))
fi
# Check TYPO3 heading hierarchy (= for h1/h2, - for h3, ~ for h4)
RESULT=$(uv run "$SCRIPT_DIR/validate_headings.py" "$file" 2>/dev/null)
if [ -n "$RESULT" ]; then
echo "â Heading hierarchy issue in: $(basename "$file")"
echo "$RESULT"
HEADING_ERRORS=$((HEADING_ERRORS + 1))
fi
done < <(find "$DOC_DIR" -name "*.rst" -print0)
echo ""
echo "Checking heading hierarchy..."
if [ $HEADING_ERRORS -eq 0 ]; then
echo "â
Heading hierarchy follows TYPO3 convention"
else
echo "â Found $HEADING_ERRORS files with heading hierarchy issues"
echo " TYPO3 heading order: = (h1 title, above+below), = (h2), - (h3), ~ (h4)"
WARNINGS=$((WARNINGS + HEADING_ERRORS))
fi
echo ""
if [ $WARNINGS -eq 0 ]; then
echo "â
No common issues found"
else
echo "â ī¸ Found $WARNINGS warnings (not blocking)"
fi
echo ""
echo "Validation summary:"
echo " RST files: $RST_FILES"
echo " Warnings: $WARNINGS"
echo ""
echo "â
Documentation validation complete"
echo ""
echo "Next step: Render locally to check for broken references"
echo " ./render_docs.sh $PROJECT_ROOT"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path â even casually (like "the xlsx in my downloads") â and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |