docs: build source-aligned stable and next references

Author: vishr

.gitignore

@@ -10,4 +10,5 @@ vendor
 .cache/
 site/src/generated/
 site/dist/
+site/dist-next/
 site/node_modules/

README.md

@@ -15,10 +15,14 @@ the runnable cookbook recipes the docs reference.
 
 ## Documentation site
 
-Requires [Node.js](https://nodejs.org) (LTS), Go 1.27, and Git. The site build
-fetches the Echo commit recorded in `site/echo-source.json`, compiles the
-`reference/` examples against it, extracts exported middleware fields, and
-checks them against `site/reference-baseline.json` before building pages.
+Requires [Node.js](https://nodejs.org) (LTS), Go 1.27, and Git. The build
+publishes the stable docs at `/` and a next preview at `/next/`, each with its
+own search index and source revision. Those revisions are pinned in
+`site/echo-source.json` and `site/next-source.json`. The build compiles the
+`reference/` examples against both, extracts middleware fields and function
+signatures, and checks them against `site/reference-baseline.json`. JWT,
+Prometheus, and OpenTelemetry are extracted from their own pinned modules in
+`site/external-sources.json` and checked against `site/external-baseline.json`.
 
 ```bash
 cd site
@@ -28,18 +32,23 @@ npm run build    # production build to site/dist
 npm run preview  # preview the production build
 ```
 
-The first build fetches the pinned Echo source into `.cache/`. To test a proposed
-Echo checkout instead, set `ECHO_SOURCE_DIR` to its absolute path when running
-`npm run build`. The build reports changed fields and stops; review the affected
-pages, run `npm run source:prepare` and `npm run source:accept`, then review the
-baseline diff before committing it. The generated files in `site/src/generated/`
-are never edited or committed.
-
-`npm run translations:status` reports whether the reviewed Spanish, Japanese,
-Portuguese, and Chinese Request Logger and Static pages still match the current
-English source. After reviewing those translations, run
-`npm run translations:accept` and review the hash changes. This report tracks
-freshness; it does not validate translation quality.
+The first build fetches pinned source into `.cache/`. To test a proposed next
+Echo checkout, set `ECHO_SOURCE_DIR` to its absolute path when running
+`npm run build`. The build reports changed API facts and stops. Review the
+affected pages and behavior, run `npm run source:prepare` and
+`npm run source:accept`, then review the baseline diff before committing it.
+The generated files in `site/src/generated/` are never edited or committed.
+`npm run site:check` checks routes, local links and fragments, image text,
+search assets, and locale coverage. `npm run performance:check` catches large
+HTML or first-load asset growth on representative stable and next pages.
+
+`npm run translations:status` identifies changed sections in the Spanish,
+Japanese, Portuguese, and Chinese Request Logger, Static, and middleware task
+pages. Translate and review the affected section, then record that page with
+`npm run translations:accept -- es logger` (replace locale and page) and review
+the baseline diff. This tracks edits to both English and localized text; it
+does not judge translation quality. The API tables are generated from source,
+so translators focus on explanations, task guidance, examples, and safety notes.
 
 Content is Markdown/MDX under `site/src/content/docs/` (`guide/`, `middleware/`,
 `cookbook/`). To add a page, drop a file in the right folder — the sidebar is

reference/cmd/config-fields/main.go

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-// config-fields emits source-backed middleware config fields for the website.
+// config-fields emits source-backed middleware API facts for the website.
 // It does not claim to determine runtime defaults or behavior.
 package main
 
@@ -33,22 +33,33 @@ type config struct {
 	Fields []field `json:"fields"`
 }
 
+type function struct {
+	Name      string `json:"name"`
+	Signature string `json:"signature"`
+	File      string `json:"file"`
+	Line      int    `json:"line"`
+}
+
 type manifest struct {
-	Module   string   `json:"module"`
-	Revision string   `json:"revision,omitempty"`
-	Configs  []config `json:"configs"`
+	Module    string     `json:"module"`
+	Revision  string     `json:"revision,omitempty"`
+	Configs   []config   `json:"configs"`
+	Functions []function `json:"functions"`
 }
 
 func main() {
 	root := flag.String("root", "", "Echo repository root")
 	revision := flag.String("revision", "", "exact Echo commit or tag used for this build")
+	module := flag.String("module", "github.com/labstack/echo/v5", "module path containing the source")
+	directory := flag.String("directory", "middleware", "package directory relative to the module root")
+	packageName := flag.String("package", "middleware", "Go package name")
 	flag.Parse()
 	if *root == "" {
 		fmt.Fprintln(os.Stderr, "-root is required")
 		os.Exit(2)
 	}
 
-	result, err := extract(*root, *revision)
+	result, err := extractPackage(*root, *revision, *module, *directory, *packageName)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
@@ -62,26 +73,43 @@ func main() {
 }
 
 func extract(root, revision string) (manifest, error) {
+	return extractPackage(root, revision, "github.com/labstack/echo/v5", "middleware", "middleware")
+}
+
+func extractPackage(root, revision, module, directory, packageName string) (manifest, error) {
 	root, err := filepath.Abs(root)
 	if err != nil {
 		return manifest{}, err
 	}
 	fs := token.NewFileSet()
-	packageDir := filepath.Join(root, "middleware")
+	packageDir := filepath.Join(root, directory)
 	packages, err := parser.ParseDir(fs, packageDir, func(info os.FileInfo) bool {
 		return strings.HasSuffix(info.Name(), ".go") && !strings.HasSuffix(info.Name(), "_test.go")
 	}, parser.ParseComments)
 	if err != nil {
 		return manifest{}, err
 	}
-	pkg, ok := packages["middleware"]
+	pkg, ok := packages[packageName]
 	if !ok {
-		return manifest{}, fmt.Errorf("middleware package not found in %s", packageDir)
+		return manifest{}, fmt.Errorf("package %s not found in %s", packageName, packageDir)
 	}
 
-	result := manifest{Module: "github.com/labstack/echo/v5", Revision: revision, Configs: []config{}}
+	result := manifest{Module: module, Revision: revision, Configs: []config{}, Functions: []function{}}
 	for filename, source := range pkg.Files {
 		for _, declaration := range source.Decls {
+			if fn, ok := declaration.(*ast.FuncDecl); ok && fn.Recv == nil && ast.IsExported(fn.Name.Name) {
+				var rendered bytes.Buffer
+				if err := format.Node(&rendered, fs, fn.Type); err != nil {
+					return manifest{}, err
+				}
+				result.Functions = append(result.Functions, function{
+					Name:      fn.Name.Name,
+					Signature: strings.Replace(rendered.String(), "func(", "func "+fn.Name.Name+"(", 1),
+					File:      filepath.ToSlash(strings.TrimPrefix(filename, root+string(filepath.Separator))),
+					Line:      fs.Position(fn.Pos()).Line,
+				})
+				continue
+			}
 			group, ok := declaration.(*ast.GenDecl)
 			if !ok || group.Tok != token.TYPE {
 				continue
@@ -121,6 +149,7 @@ func extract(root, revision string) (manifest, error) {
 		}
 	}
 	sort.Slice(result.Configs, func(i, j int) bool { return result.Configs[i].Name < result.Configs[j].Name })
+	sort.Slice(result.Functions, func(i, j int) bool { return result.Functions[i].Name < result.Functions[j].Name })
 	return result, nil
 }
 

reference/cmd/config-fields/main_test.go

@@ -23,6 +23,8 @@ type ExampleConfig struct {
 }
 type hiddenConfig struct { Visible bool }
 type OtherType struct { Visible bool }
+func ExampleWithConfig(c ExampleConfig) bool { return c.New != "" }
+func privateFunction() {}
 `
 	if err := os.WriteFile(filepath.Join(dir, "example.go"), []byte(source), 0644); err != nil {
 		t.Fatal(err)
@@ -42,4 +44,7 @@ type OtherType struct { Visible bool }
 	if fields[0].Name != "Old" || fields[0].Type != "bool" || !fields[0].Deprecated || fields[1].Name != "New" {
 		t.Fatalf("unexpected fields: %#v", fields)
 	}
+	if len(got.Functions) != 1 || got.Functions[0].Name != "ExampleWithConfig" || got.Functions[0].Signature != "func ExampleWithConfig(c ExampleConfig) bool" || got.Functions[0].File != "middleware/example.go" {
+		t.Fatalf("unexpected functions: %#v", got.Functions)
+	}
 }

site/astro.config.mjs

@@ -2,11 +2,15 @@ import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import { redirects } from './src/redirects.mjs';
 
+const next = process.env.DOCS_CHANNEL === 'next';
+
 // https://astro.build/config
 export default defineConfig({
   site: 'https://echo.labstack.com',
+  base: next ? '/next/' : '/',
+  outDir: next ? './dist-next' : './dist',
   // Preserve every live Docusaurus /docs/* URL at cutover (generated — see ./src/redirects.mjs).
-  redirects,
+  redirects: next ? {} : redirects,
   integrations: [
     starlight({
       title: 'Echo',
@@ -36,6 +40,7 @@ export default defineConfig({
       // Keep Starlight's built-in Pagefind ⌘K search; Search override adds the
       // empty-state launchpad. "Ask AI" is the kapa.ai widget (see head).
       components: {
+        Banner: './src/components/VersionBanner.astro',
         Footer: './src/components/Footer.astro',
         Search: './src/components/Search.astro',
       },

site/echo-source.json

@@ -1,4 +1,5 @@
 {
   "repository": "https://github.com/labstack/echo.git",
-  "revision": "68ac4cf7e0b862001a9de7cdbc50d9447287a07c"
+  "revision": "caa018246b840091e71a1d61ea9ee1176ab81333",
+  "release": "v5.3.0"
 }