docs: source-align the Echo website in echox

Ouverte
  • Quelque chose ne va pas ?
#448 3 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
25/100
Type d'issue
Documentation
Clarté
Plutôt claire
Activité
À l'abandon
Stack technique
go
Domaine
accessibility, build-system, documentation, localization, performance, testing-qa

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.
Langage dominant
MDX
Étoiles
440
Forks
298
Merge moyen
17 min
PR mergées (30 j)
13

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de labstack/echox

Toutes les issues de labstack/echox

Issues similaires

Plus d'issues Accessibility

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.