docs: source-align the Echo website in echox

Aberta
  • Algo errado?
#448 3 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
25/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
go
Domínio
accessibility, build-system, documentation, localization, performance, testing-qa

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.
Linguagem predominante
MDX
Estrelas
440
Forks
298
Merge médio
17min
PRs com merge (30d)
13

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de labstack/echox

Todas as issues de labstack/echox

Issues semelhantes

Mais issues de Accessibility

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.