Skip to content

fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags - #2629

Merged
marcus-souza-azion merged 3 commits into
mainfrom
fix/mm-16262-structure-headings-meta-fences
Nov 12, 2026
Merged

marcus-souza-azion merged 3 commits into
mainfrom
fix/mm-16262-structure-headings-meta-fences

Conversation

@bruno-andrade-azion

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

Copy link
Copy Markdown
Contributor

What & why

Related issue: MM-16262, in the epic MM-16212
Pages affected: 52 pages in en and pt-br:

  • the dated Terms of Service and the Savings Plan (27), plus the pt-br Terms of Service of May 12, 2026 and the pt-br index;
  • four older pt-br Terms of Service whose meta_tags move to English: November 10, 2016, May 15, 2019, August 18, 2020 and October 25, 2017;
  • the OpenNext guide and the pt-br v3 Main Settings reference;
  • the Functions quickstart, the browserless, serverless functions, test origin and WebAssembly guides, and the Edge Node reference;
  • the style guide's bilingual pages and procedures pages.

The ticket's counts come from the October 29 review. I measured them again on main, parsing frontmatter with gray-matter and skipping code blocks, and most of them don't hold up:

Ticket item In the ticket On main Fixed here Left to
H1 in the body 41 pages 0 — —
Skipped heading level 30 pages 32 30 #2624 (Edge Services); #2598 (MongoDB template) already merged
Missing meta_tags 15 pt-br pages 15 14 the pt-br April 26, 2023 terms, after #2625
namespace written as >- 2 namespaces 4 files 0 #2625
Code block with no language 1,247 31 22 #2558 (6), #2597 (1); #2593 deleted the page with one more, and the page this PR had tagged
  • H1 in the body. The 41 pages are exactly the ones with a # ... comment inside a code block or a <Code code={...}> template literal. No page has a real H1 in its body.
  • Release notes and changelog. They look like they jump from the title to H3, but they don't: DocUpdate renders each entry's date as an <h2>. I left them as they are.

Code blocks. A fence with no language reaches CodeBlock with no lang, because astro-code-blocks.ts passes node.lang ?? undefined. The webkit highlighter then falls back to JavaScript, so output such as Hello World! was tokenized as JavaScript.

Heading levels. No legal text changes.

  • In the agreements, #### Previous versions of this document: becomes ## Previous versions of this document. That's how the current Terms of Service already write it. The anchor doesn't change, and the section now shows in the page's table of contents, as it does on the current terms.
  • The OpenNext guide started at ###. Prerequisites, Local development, Deployment and Best practices become H2, and the two app setup sections, "Create a Next.js app" and "Adapt an existing Next.js app", become H2 siblings of Prerequisites instead of its children. The rewritten headings follow the style guide's headings rules: sentence case, the imperative instead of a gerund, and "and" instead of "&". No link points at the old anchors.
  • In the pt-br v3 Main Settings reference, "Lista de portas disponíveis" becomes an H3, as in English.

meta_tags. The style guide keeps meta_tags in US English in both languages (Two languages, Bilingual pages). Fourteen pt-br Terms of Service pages get 'Terms of Service, Azion Terms of Service', the value their English pairs carry, and four older pt-br terms that had the Portuguese value switch to it, so 18 pt-br terms now match.

How I checked it:

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 — no page in the repository carries last_reviewed, and the pt-br April 26, 2023 terms get meta_tags only after i18n(pt-br): pair three pages with their English versions by namespace #2625 merges
  • No legacy "edge-" product names in the copy — this PR adds no copy; the touched pages keep their wording
  • How-to/tutorial content includes at least one runnable, copy-paste-tested code block — no code block is added; existing blocks only get a language tag
  • Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
  • Internal links are relative and resolve locally — no link is added or changed, but the touched pages already have 5 broken links and the agreements use absolute URLs; the agreements links belong to MM-16265
  • 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: both languages are in this PR
  • I ran pnpm build:local (build + frontmatter check) without errors — it passed before the rebase; after the rebase and the review fixes, the CI Build check is what verifies it

@marcus-souza-azion

Copy link
Copy Markdown
Contributor

Rebased this branch onto main and force-pushed (old head 393e11cc5, new head 88c2f5cb7). Your two commits are unchanged apart from the rebase; one review commit sits on top.

The description is updated to match.

egermano and others added 3 commits November 12, 2026 11:52
…sing pt-br meta_tags

- Tag 23 bare code fences in 17 pages (text for output, mdx for page
  source). A fence without a language reached CodeBlock with no lang, and
  the highlighter fell back to JavaScript.
- Fix heading skips on 30 pages: the agreements "Previous versions"
  heading becomes an H2, as on the current Terms of Service; the OpenNext
  guide moves up one level; a pt-br v3 reference H4 becomes H3, as in en.
- Add meta_tags to the 15 pt-br Terms of Service pages that lacked it.
…2625

#2625 rewrites the namespace line next to it; adding meta_tags there now
would conflict.
…penNext outline

- The style guide keeps meta_tags in US English in both languages, so 18
  pt-br Terms of Service carry the English value, 'Terms of Service, Azion
  Terms of Service', as their English pairs do. November 10, 2020 keeps its
  Portuguese value until #2625 merges: #2625 rewrites the namespace line
  right below it.
- In the OpenNext guide, the app setup sections become H2 siblings of
  Prerequisites instead of its children, and the rewritten headings use
  sentence case, the imperative, and "and" in place of "&".
@marcus-souza-azion
marcus-souza-azion force-pushed the fix/mm-16262-structure-headings-meta-fences branch from 88c2f5c to f4a67d2 Compare November 12, 2026 14:53
@marcus-souza-azion
marcus-souza-azion merged commit be433a0 into main Nov 12, 2026
9 checks passed
@marcus-souza-azion
marcus-souza-azion deleted the fix/mm-16262-structure-headings-meta-fences branch November 12, 2026 14:57
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (29 commits)
  fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags (#2629)
  docs(style-guide): drop the nonexistent GlossaryFilter from the glossary template (#2577)
  docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry (#2572)
  fix(orchestrator): fix broken bind and create-service API samples (#2574)
  docs(readability): split the long sentences in the Runtime, CLI, Reference, and KV Store pages (#2635)
  chore(nav): count only visible rows toward the navcheck soft max (#2640)
  docs(nav): triage the pages outside the navigation (#2593)
  fix(guides): match the QStash variable and the Functions usage response to the code (#2571)
  feat(nav): give every breadcrumb crumb a page and make CLI commands runnable (#2636)
  fix(cli): drop azion update workload-deployment, which the CLI does not expose (#2639)
  docs(terminology): retire Edge Node, module, and add-on from current pages (#2618)
  docs(migration): share the repeated migration-guide procedures as partials (#2619)
  fix(marketplace): drop the Azion CLI prerequisite from firewall integration guides (#2612)
  docs(guides): replace the residual "These checks confirm" lines with use-case expect blocks (#2611)
  docs(guides): make the auth layer and vector search tutorials runnable (#2566)
  chore(scripts): add pnpm lint:terraform to validate Terraform samples (#2637)
  fix(firewall): correct the CLI binding, the WAF config sample, and the JWT paywall steps (#2565)
  docs(cli): document azion workload-deployment and fix pages that say the CLI cannot bind a deployment (#2567)
  docs(terraform): rewrite the samples for provider v2.10.0 (#2557)
  chore(deploy): promote docs-v2.4.4 to production (#2631)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/observe/real-time-events/data-sources.mdx
#	apps/docs/src/content/docs/pt-br/pages/observe/real-time-events/fontes-de-dados.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (39 commits)
  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)
  docs(style-guide): drop the nonexistent GlossaryFilter from the glossary template (#2577)
  docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry (#2572)
  fix(orchestrator): fix broken bind and create-service API samples (#2574)
  docs(readability): split the long sentences in the Runtime, CLI, Reference, and KV Store pages (#2635)
  chore(nav): count only visible rows toward the navcheck soft max (#2640)
  docs(nav): triage the pages outside the navigation (#2593)
  fix(guides): match the QStash variable and the Functions usage response to the code (#2571)
  feat(nav): give every breadcrumb crumb a page and make CLI commands runnable (#2636)
  fix(cli): drop azion update workload-deployment, which the CLI does not expose (#2639)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/store/sql-database/glossary.mdx
#	apps/docs/src/content/docs/pt-br/pages/store/sql-database/glossario.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (53 commits)
  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)
  docs(style-guide): drop the nonexistent GlossaryFilter from the glossary template (#2577)
  docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry (#2572)
  fix(orchestrator): fix broken bind and create-service API samples (#2574)
  docs(readability): split the long sentences in the Runtime, CLI, Reference, and KV Store pages (#2635)
  chore(nav): count only visible rows toward the navcheck soft max (#2640)
  docs(nav): triage the pages outside the navigation (#2593)
  fix(guides): match the QStash variable and the Functions usage response to the code (#2571)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/personal-tokens.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/reference/services/support/http-error-status-codes.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/personal-tokens.mdx
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
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