Skip to content

Commit 9d02139

Browse files
authored
docs(readme): restructure for narrative, SEO, and GitHub UX conventions (#842)
## Summary Restructures `README.md` (+257 / −177) so the front door of the repo reads less like a feature spec and more like the entry path an integrator actually takes when landing here from a search engine. - **Narrative lead** — single-sentence positioning statement (TYPO3 v13/v14 LTS, CKEditor 5, FAL) and a "Why this extension exists" section that surfaces the TYPO3 v10 RTE-image removal context. This is the search intent that brings most integrators to this repo and was previously not addressed until the docs site. - **Table of contents** — anchored ToC near the top; standard GitHub convention for READMEs > ~250 lines. - **Features regrouped** into four narrative subsections (editor experience / frontend rendering / integrity & maintenance / quality & security) instead of one 17-bullet wall. - **Tables** for requirements, extension configuration options, quality multipliers, and DDEV URLs — easier to scan than mixed prose/bullets. - **Numbered install steps** with prose intros explaining the Site Set vs. manual TypoScript vs. custom-preset trade-offs. - **Security promoted to its own H2** — lists all six defense layers (caption XSS sanitization, file visibility, URL protocol allowlist, SVG sanitization, SSRF, whitespace-smuggling hardening) with explicit links to ADR-003 and `SECURITY.md`. - **Distribution channels** spelled out under "Verifying releases" (Composer / TER / GitHub Releases). - **i18n note** in Contributing (31 languages via Crowdin). - **Removed marketing emoji** in the badge-source comment. SEO keywords woven in naturally: *TYPO3 CKEditor image*, *TYPO3 v13/v14 LTS*, *Rich Text Editor*, *File Abstraction Layer (FAL)*, *CKEditor 5 plugin*, *Magic Images*, *inline images*, *Fluid templates*, *PSR-14*. ## What is **not** changed - All TypoScript snippets, Composer commands, DDEV URLs, and CLI commands are preserved verbatim. - ADR-004 storage convention paragraph is preserved verbatim. - SLSA verification commands are preserved verbatim. - Badge block at the top of the file is unchanged. - No code changes anywhere else in the repo. ## Test plan - [ ] Render the README on GitHub and confirm headings, ToC anchors, table layout, and the hero screenshot render correctly. - [ ] Verify every link resolves (badges, docs.typo3.org sections, ADR-003 / ADR-004, in-repo files). - [ ] Confirm the screenshot alt text reads sensibly to a screen reader. - [ ] Confirm `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `AGENTS.md`, and `LICENSE` still exist at the paths the README points to.
2 parents 120056a + f4612b4 commit 9d02139

1 file changed

Lines changed: 276 additions & 181 deletions

File tree

0 commit comments

Comments
 (0)