docs: source-align the Echo website in echox

Aperta
  • Qualcosa non va?
#448 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
go
Ambito
accessibility, build-system, documentation, localization, performance, testing-qa

Direzione di ricerca

Start with draft PR #447 and the documented CI checks, then review the remaining authored behavior and security claims against both pinned Echo revisions. Native speakers should assess the new localized task-page wording, while a browser preview should cover mobile usability, accessibility, and Core Web Vitals. Done means the remaining review decisions and any cross-repository gate ownership are recorded before publication.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

docs

Goal

Make the published Echo documentation accurate against the exact Echo revision it describes while keeping the Astro/Starlight website and all documentation-only files in labstack/echox. Preserve live URLs and important anchors, five locales, cookbook pages, search, Ask AI, and independent website publishing.

This issue was transferred from labstack/echo#3116 after repository ownership was clarified. Echo's API source remains in Echo. Runnable docs examples, reference extraction, authored pages, translations, site code, and deployment belong in echox.

Source revision contract

  • Record the Echo commit for each published reference; show it next to generated API facts.
  • Compile documentation examples against the recorded Echo source and import the same files into pages.
  • Extract facts source can establish: exported config fields and types, deprecations, signatures, and source links. A reviewed baseline must make API drift fail CI with a readable diff.
  • Author and review defaults, conditional behavior, security guidance, tutorials, and translations. Extraction alone cannot establish those claims.
  • Identify the owning module and version for external middleware.

Implemented in draft PR #447

  • Stable and next builds use separate pinned Echo revisions, visible version switches, and separate Pagefind indexes. Existing site URLs remain at the stable root; next lives under /next/.
  • Source-backed tables cover all 22 core middleware configs across 20 pages and all five locales. JWT, Prometheus, and OpenTelemetry reference facts come from their pinned module releases.
  • Request Logger and Static import the same runnable Go files that the build compiles against the Echo source. These pages correct the drift from #439.
  • A middleware task page in every locale connects common goals to pages, examples, and follow-on guide tasks.
  • CI checks source/API baselines, translated section freshness on the new and example pages, 676 routes, internal links and assets, image text, locale coverage, and representative HTML/asset size budgets. Offline link auditing also checks fragments.
  • The existing website deployment remains in echox. Echo cleanup PR labstack/echo#3119 has merged, leaving no documentation-only files in Echo.

Remaining review before publication

  1. Review authored behavior, default, and security claims against both pinned Echo revisions; API extraction does not establish runtime behavior.
  2. Have native speakers review newly authored Spanish, Japanese, Portuguese, and Chinese task-page wording. Section hashes detect drift but cannot judge translation quality.
  3. Measure mobile usability, accessibility, and Core Web Vitals in a browser preview. Current checks cover structural accessibility and static size regressions, not those human/browser measurements.
  4. Decide with Echo maintainers whether a small Echo-to-echox cross-repository PR gate is warranted and how it selects an echox ref. The site can already test a proposed Echo checkout with ECHO_SOURCE_DIR.

The gomarkdoc --embed/--check trial and its limits remain in this repository. Package-wide output is too broad for individual middleware pages, and generated fields do not establish runtime defaults or security behavior.

Acceptance criteria

  • Existing live URLs and important anchors resolve; all five locales and cookbook pages remain available.
  • Removing or renaming a core middleware API field fails the docs compatibility check until the baseline and affected pages are reviewed.
  • Cookbook, runnable reference examples, and site build pass against their recorded Echo revisions. Published references visibly identify those revisions.
  • Runtime claims, security notes, translations, and external middleware facts have explicit review and ownership paths.
  • Reader-task, accessibility, performance, and URL checks are compared with the recorded baseline before publication.
Lingua principale
MDX
Stelle
440
Fork
298
Merge medio
17m
PR unite (30g)
13

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di labstack/echox

Tutte le issue di labstack/echox

Issue simili

Altre issue su Accessibility

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.