docs: source-align the Echo website in echox

Offen
  • Stimmt etwas nicht?
#448 3 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
25/100
Issue-Typ
Dokumentation
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
go
Bereich
accessibility, build-system, documentation, localization, performance, testing-qa

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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.
Vorherrschende Sprache
MDX
Sterne
440
Forks
298
Ø Merge
17 Min.
Gemergte PRs (30 T.)
13

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus labstack/echox

Alle Issues in labstack/echox

Ähnliche Issues

Weitere Issues zu Accessibility

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.