Commit 9d02139
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.1 file changed
Lines changed: 276 additions & 181 deletions
0 commit comments