docs: source-align the Echo website in echox

Abierto
  • ¿Algo no está bien?
#448 3 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
go
Área
accessibility, build-system, documentation, localization, performance, testing-qa

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
MDX
Estrellas
440
Forks
298
Merge medio
17 min
PR fusionados (30 d)
13

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de labstack/echox

Todos los issues de labstack/echox

Issues similares

Más issues de Accessibility

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.