Skip to content

docs(templates): migrate the legacy template guides to the current guide pattern - #2597

Merged
marcus-souza-azion merged 7 commits into
mainfrom
docs/mm-16246-migrate-legacy-template-guides
Nov 12, 2026
Merged

marcus-souza-azion merged 7 commits into
mainfrom
docs/mm-16246-migrate-legacy-template-guides

Conversation

@bruno-andrade-azion

@bruno-andrade-azion bruno-andrade-azion commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

What & why

Related issue: MM-16246 (epic MM-16212). This is the first of two PRs. The second, #2598, was merged into the branch of #2582 (MM-16236) and reaches main when #2582 merges.
Pages affected: 39 Marketplace template guides in apps/docs/src/content/docs/en/pages/guides/marketplace/templates/ and their pt-br pairs in apps/docs/src/content/docs/pt-br/pages/guias/marketplace/templates/ (78 files), plus the cross-links on ai-agent-third-party-llm, content-delivery, framework-next, publish-a-message-to-upstash-qstash-from-a-function and build-event-driven-apis, in en and pt-br.

Guide pattern. Each guide is rebuilt on the How-to skeleton of the template guides migrated earlier: an imperative title, an opening scope sentence, ## Prerequisites, one imperative section per task with DocSteps, and ## Next steps with two DocCards. The Requirements / Deploying / Setting up / Managing boilerplate is gone, along with "Fill in the presented fields", "You'll be redirected…" and the Products menu click path.

Terminology and links. The external pricing site is replaced by the internal Pricing page (pt-br: Preços), and absolute azion.com documentation links are now root-relative. "Set Origin" becomes Set Connector, "EdgeSQL" becomes SQL Database, the legacy API operation link is replaced, and "edge stack", "edge latency" and "on the Edge" are gone. In pt-br, "desempenho" becomes "performance", and the leftover English lines are translated. Console paths follow the convention from #2596, Access [Azion Console](https://console.azion.com/) > **<Platform Resource>**.

Facts kept. Versions, field descriptions, defaults and allowed values, repository links, <Video> embeds, code blocks and the template-specific sections (static-export support, database setup, QStash schedules, rate-limiting behavior) are all kept. Static Cache and Dynamic and Static File Optimization carry the correction from #2626: when the origin sends no cache settings, the template applies the Max Age of the cache setting.

One anchor changed. The Next.js Static Boilerplate heading "About static exports" is now "Static export support" ("Sobre static exports" → "Suporte a static exports"), and the two framework-next links point to the new anchors. External links to the old anchors still open the page, but at the top. Permalinks, namespaces, file names and Console Deploy URLs are unchanged, including the typo'd pt-br names such as neon-databse-with-drizzle and the legacy edge-* slugs.

How it was checked. The branch was rebased on main after #2596 merged. Each conflict was resolved to the migrated text, and the 78 guide files were then compared byte for byte with the pre-rebase head: no differences. On the 88 changed files, the azion-docs-writer style gate (docs_gate.py --check) reported 0 findings, linkcheck.py reported 0 broken, cross-language or unpaired links, and Prettier passed. rewrite-check.py against the previous version of each guide found no dropped fact. The only link targets it reports as gone are the external pricing site, https://console.azion.com (now with a trailing slash), and the replaced legacy API operation link. No other page in apps/docs/src links to an anchor on these guides.

Questions for the subject matter expert (Marketplace):

  • Several templates pin old framework versions, for example React 16.13.1, Astro 2.8.0 and 3.x, and Next.js 14.x. The docs keep them as they are. Will the templates be updated?
  • jekyll-boilerplate requires Ruby 2.5.0 or higher for a Console-only deployment. Does that apply only to local development?
  • The Cosmic, Sanity and Docusaurus templates say that the application uses Functions, but not whether a function is created. The card labels avoid claiming it.
  • clean-astro-sanity: the field is "Sanity Project ID" in en and "Sanity Studio Project ID" in pt-br. Which is the Console label?
  • langgraph-template: the linked EdgeSQL Shell page warns that the tool fails on a clean install. Should the guide keep recommending it?
  • vuepress-boilerplate: does the Deploy slug vuepress--boilerplate, with its double hyphen, resolve?

Left for later: the Templates reference has name mismatches and lists Qwik Minimal under the wrong category, and about 31 guides write the Console search field as plain text while 8 bold it as Application Name.

Type of change

  • 🆕 New content (feat)
  • 🩹 Fix (fix) — typo, broken link, wrong information
  • ♻️ Content update (docs) — rewrite, expansion, upkeep
  • 🌐 Translation sync (i18n)
  • 🏗️ Platform / structure (refactor / chore) — reviewed by UXE, no content mixed in

Author checklist

  • PR title follows type(scope): summary (see GOVERNANCE.md §4)
  • Frontmatter complete: title, description, meta_tags, namespace, permalink, last_reviewed — every page has the first five; none of these pages carries last_reviewed, before or after this PR
  • No legacy "edge-" product names in the copy — file names and slugs keep edge-*, since they are paths, and "EdgeSQL Shell" is kept because it is the tool's name
  • How-to/tutorial content includes at least one runnable, copy-paste-tested code block — most of these guides deploy from Azion Console and have no code; the code blocks that some guides carry were kept as they were and not re-run
  • Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
  • Internal links are relative and resolve locally
  • If any permalink changed or page moved: redirect added in this PR — no permalink changed and no page moved
  • i18n: pt-br updated in this PR or follow-up i18n issue created: pt-br updated in this PR
  • I ran pnpm build:local (build + frontmatter check) without errors — not run after the rebase; the Build check in CI runs on the push

egermano and others added 7 commits November 12, 2026 14:20
- static-cache and dynamic-and-static-file-optimization: keep the
  correction from #2626. When the origin sends no cache settings, the
  template applies the Max Age of the cache setting, not a default TTL.
- framework-next (en and pt-br): point the static exports link to the
  renamed heading anchor.
- edge-function-starter-kit: drop "Products menu" from the Console path,
  as #2596 does.
- langgraph-template: link the backend variables section by its anchor.
- Docusaurus and pt-br LangGraph descriptions: trim to 160 characters.
@marcus-souza-azion
marcus-souza-azion force-pushed the docs/mm-16246-migrate-legacy-template-guides branch from 2de6dff to 8955cea Compare November 12, 2026 17:27
@marcus-souza-azion marcus-souza-azion changed the title docs(templates): migrate the legacy template guides to the current guide pattern (MM-16246) docs(templates): migrate the legacy template guides to the current guide pattern Nov 12, 2026
@marcus-souza-azion
marcus-souza-azion merged commit 6b4bb55 into main Nov 12, 2026
10 checks passed
@marcus-souza-azion
marcus-souza-azion deleted the docs/mm-16246-migrate-legacy-template-guides branch November 12, 2026 17:32
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (48 commits)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  docs(observe): fix dataset name, Data Stream filter, and Grafana Data path (#2573)
  fix(fundamentals): rewrite the Load Balancer steps in minimize-downtime from the reference (#2578)
  i18n(pt-br): label unlabelled asides and fix label casing (#2622)
  fix(links): point pt-br links to their existing pt-br pages (#2620)
  i18n(pt-br): resync the drifted release notes, punctuation, and Edge Services pairs (#2624)
  i18n(pt-br): pair three pages with their English versions by namespace (#2625)
  docs(style-guide): adopt the jsonl tag for JSON Lines samples (#2642)
  chore(lint): check the changelog entries a PR adds (#2634)
  [NO-ISSUE] ci: replace technote-space/assign-author (SO-5131) (#2591)
  fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags (#2629)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/billing.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/teams-permissions.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/faturamento.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/teams-permissions.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
* origin/main: (58 commits)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  ...
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
…nce-soc-pci

* origin/main: (59 commits)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/compliance/pci-dss.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/compliance/soc-2.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/compliance/pci-dss.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/compliance/soc.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 13, 2026
* origin/main: (59 commits)
  docs(console): apply the review of the Console path convention (#2644)
  docs(workloads): review the Workloads section with the style guide and correct it from live tests (#2570)
  fix(ai-inference): review the AI Inference section and correct it from live tests (#2641)
  docs(templates): apply the review of the migrated template guides (#2645)
  docs(templates): point Deploy links to the current Marketplace catalog (MM-16236) (#2582)
  docs(orchestrator): split how-tos into API v4 and API v3 pages (#2584)
  fix(accounts): hyphenate Real-Time Purge and name the Bills tab in the permissions table (#2581)
  chore(lint): accept the English-only Marketplace Agreement and lower the linkcheck baseline (#2647)
  fix(links): point the v3 Applications reference and the guides at the current pages (#2646)
  docs(runtime): migrate Node.js API samples to the ES Modules handler (MM-16245) (#2592)
  docs(observe): use the current GraphQL dataset names across Observe and guides (#2579)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  ...

# Conflicts:
#	apps/docs/redirects/en/01.json
#	apps/docs/redirects/pt-br/01.json
#	apps/docs/src/content/docs/en/homes/architctures/by-use-case/application-and-network-security.mdx
#	apps/docs/src/content/docs/pt-br/homes/arquiteturas/por-solucao/seguranca-de-aplicacoes-e-redes.mdx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants