Skip to content

Remove legacy frontmatter, placeholder defaults, and duplicated text from AI reference pages - #873

Merged
Manny-r31 merged 2 commits into
mainfrom
devon/ai-reference-legacy-cleanup
Oct 28, 2026
Merged

Manny-r31 merged 2 commits into
mainfrom
devon/ai-reference-legacy-cleanup

Conversation

@Devon-White

Copy link
Copy Markdown
Collaborator

Summary

Finishes the legacy cleanup that #598 tracks on the AI reference pages #578 touched.

  • Legacy frontmatter. Removed id: and hide_title: false from ai/languages, ai/prompt, and the Google Cloud TTS page, plus unlisted: false from ai/languages. Nothing in the repo references the ids. unlisted: false hid nothing, so removing it publishes nothing new. Slugs are unchanged.
  • default="None" removed from languages[].function_fillers, .model, .speech_fillers, and .params. The TypeSpec gives none of these four a default.
  • Prompt page fillers. The enter_fillers sentence giving the key resolution order repeated the canonical text on the SWAIG page's Filler language codes word for word. It's cut, and the existing link now says that page has the order.
  • Multilingual page. function_fillers repeated two sentences from fillers word for word. It now says "Same shape and translation behavior as fillers" (both are string[] | FunctionFillers in the spec).
  • Voice and language guide. Body headings now start at ## and use sentence case. The title is "Voice and language", which matches fern/llms.txt, and Python comments use # instead of ##. No links in the repo point at the old heading anchors.

Already done on main, so not touched here: the Google Cloud ## Languages voice names, and the bare-voice-id warning, which now appears once on ai/languages with a one-line cross-reference.

Closes #598

Notes for reviewers

  • Overlap with fix(swml): align the SWML method reference with platform behavior #852. That PR also edits ai/languages/index.mdx (adds text around the voice strings section and the warning) and ai/prompt/index.mdx (contexts, steps, prompt.model, confidence). It doesn't touch any item in this PR, and this PR stays out of its hunks. A test merge of the two heads is clean.
  • Left alone as out of scope: the voice-language guide still opens with a ## Voice configuration overview heading rather than an intro paragraph, the reference pages keep their bold ## **Properties** / ## **Examples** headings, and google.mdx has no max-toc-depth.
  • The SWML .tsp descriptions for multilingual function_fillers still repeat the fillers text. Each spec description has to read on its own in the generated schema, so the spec is unchanged and no yarn build:specs was needed.

Verification

  • yarn fern-md-check: all MDX files valid.
  • Checked #filler-language-codes by hand against the SWAIG page (slug: reference/calling/ai/swaig, ### Filler language codes).

Preview:

  • /docs/swml/reference/calling/ai/languages
  • /docs/swml/reference/calling/ai/prompt
  • /docs/swml/reference/calling/ai/multilingual
  • /docs/platform/voice/tts/gcloud
  • /docs/server-sdks/guides/voice-language

…ages

Remove legacy id/unlisted/hide_title frontmatter from the languages, prompt,
and Google Cloud TTS pages; drop default="None" on four languages[]
ParamFields the source gives no default; cut the duplicated filler resolution
order on the prompt page and the repeated function_fillers text on the
multilingual page; move the voice-language guide to ## headings in sentence
case, retitle it without &, and use # for Python comments.

Refs #598
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

@Manny-r31 Manny-r31 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: ready to merge

CI is green, no conflicts. Nothing blocking.

Verified

  • Removing default="None" is correct: ai_languages.tsp defines no default for function_fillers, speech_fillers, or params.
  • "Same shape and translation behavior as fillers" holds: fillers and function_fillers are both string[] | FunctionFillers in ai_multilingual.tsp with matching descriptions.
  • The resolution-order text cut from the prompt page still lives at swaig#filler-language-codes, so nothing is lost.
  • ## to # in the Python comments is correct.
  • No slugs changed and nothing links to the guide's heading anchors, so no nav or redirect work is needed.

Optional nits

  1. voice-language.mdx:2: the title "Voice and language" is now the only sentence-case sidebar label among its 33 Title Case siblings in build-ai-agents. It's correct per mdx-style, so fine to keep. Just flagging the visual inconsistency until the rest get swept.
  2. The PR description says hide_title: false was removed from google.mdx, but on main that file only has id:, and the diff correctly removes only id:. Description only, no code change needed.
  3. multilingual/index.mdx:143: optionally link fillers to the param directly above it.
  4. Untouched em dashes remain in voice-language.mdx (lines 74, 264), prompt/index.mdx (22-28), and the languages[].model description. Out of scope here, worth a separate sweep.

@Manny-r31
Manny-r31 merged commit ff7e3af into main Oct 28, 2026
2 checks passed
@Manny-r31
Manny-r31 deleted the devon/ai-reference-legacy-cleanup branch October 28, 2026 13:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Legacy cleanup on the AI reference pages #578 touched

2 participants