Restructure docs nav into product-aligned tabs#728
Merged
Conversation
Replace the single "Documentation" mega-tab with 7 focused tabs: Get Started, API Reference, Async STT, Streaming STT, Speech Understanding, Guardrails, and LLM Gateway. - Fold cookbooks into their relevant product tabs as "Guides" sections - Move voice agent content under Streaming STT tab - Move FAQ pages to hidden section (URLs preserved for SEO) - Move Playground and Changelog to navbar buttons - Remove Roadmap external link tab - Add redirects for old /docs/guides and /docs/faq paths Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Merge changes from main: - Rename "Universal 3 Pro" to "Universal-3 Pro" (hyphen) - Add API Reference link to Pre-recorded section - Move Streaming Endpoints after Whisper in streaming nav - Rename "Voice agents" to "Voice Agents and Orchestrators" - Rename "Streaming Diarization and Multichannel" to "Diarization and Multichannel" - Update streaming API Reference href for U3Pro Streaming rename - Change universal3Pro to universal3ProStreaming in API ref - Remove Ruby SDK snippets - Update PII redaction slug from lemur- to llm-gateway- - Add U3Pro Streaming and PII redaction redirects Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Overview tab (renamed from "Get Started"):
- Renamed tab to "Overview"
- Rewrote home.mdx: replaced marketing banner/video/products/footer with
clean card grid — "Explore our models" (5 product tabs) and "Deployment
options" (API ref, Integrations, LiveKit, Pipecat, SDKs)
- Restructured Getting started: Overview, Models, Evaluations, Benchmarks,
Account management, Introducing Universal-3 Pro (moved to bottom)
- Created "Use cases & integrations" section header containing:
- Use case guides (new landing page with cards for notetaker, medical
scribe, voice agent, contact center) with subpages
- Integrations (landing page + all subsections nested under it)
- Created "Trust & security" section: Trust center, Security overview,
new combined "Data retention and model training" page (consolidates 6
FAQ topics with exact legal-approved language preserved)
- Folded billing-tracking content into Account management page
- Removed: Deployment & Operations, Security, Build with AssemblyAI,
Platform Guides sections
Content redistribution to product tabs:
- Async STT: added quickstart, pre-recorded audio evaluations, cloud
regions, webhooks at top; meeting notetaker + medical scribe in guides;
self-hosted async (hidden) at bottom
- Streaming STT: added quickstart, streaming evaluations at top; webhooks
before voice agents; meeting notetaker + medical scribe in guides;
self-hosted streaming (hidden) at bottom
- Speech Understanding: new intro/landing page (index.mdx) with cards
for all 9 features
- Guardrails: new intro/landing page (guardrails-index.mdx) with cards
for all 4 features
New pages created:
- fern/pages/speech-understanding/index.mdx
- fern/pages/audio-intelligence/guardrails-index.mdx
- fern/pages/use-cases/index.mdx
- fern/pages/concepts/data-retention-and-model-training.mdx
Other changes:
- Evaluations page: added intro content explaining why evals matter
- Benchmarks page: restructured to mirror assemblyai.com/benchmarks with
methodology section and hallucination coverage
- Sentence case applied across entire left nav
- Added redirect: /docs/deployment-operations/evaluating-stt-models →
/docs/evaluations
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Renamed tab display-name from "Async STT" to "Pre-recorded STT" - Updated all references in home.mdx and use-cases/index.mdx - Fixed Guardrails overview 404 by removing skip-slug from section so /docs/guardrails resolves to the landing page Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pre-recorded STT tab: - Added "Getting started" and "Models & features" section headers - Moved model selection, evals, cloud endpoints, webhooks into Getting started - Removed (Async) suffixes from Universal-3 Pro and Prompting guide - Renamed cloud regions to "Cloud endpoints & data residency" - Moved Migration guides above Guides, reordered (Deepgram first) - Hidden redundant guides (EU region, combine keyterms — content folded in) - Added combine keyterms+prompts code examples to prompting guide - @api-info metadata on all 19 Getting started + Models & features pages Streaming STT tab: - Added "Getting started" and "Models & features" section headers - Moved model selection, evals, cloud endpoints, webhooks into Getting started - Restructured "Build a voice agent": U3P Streaming (LiveKit, Pipecat) and Universal Streaming (legacy LiveKit, Pipecat) as model subsections - Moved Migration guides above Guides, reordered (Deepgram first) - Hidden guides overview - @api-info metadata on all 18 Getting started + Models & features pages using speech_model (singular) with pipe-delimited model options Speech Understanding tab: - Replaced section+icon with "Models & features" header - Getting started page as first item in section - Merged guides into parent feature pages as sub-items - Hidden guides overview - @api-info metadata on all 10 feature pages (all pre-recorded only) Guardrails tab: - Replaced section with "Models & features" header - Getting started page as first item - @api-info metadata on all 5 pages (all pre-recorded only) LLM Gateway tab: - Replaced "LLM Gateway" section+icon with "Getting started" - Overview + pre-recorded + streaming docs in Getting started - Remaining features in "Use cases" section - Hidden guides overview - Duplicated streaming LLM Gateway guides into LLM Gateway tab - Cross-referenced LLM Gateway in Pre-recorded and Streaming guides Other changes: - Added "Community" link (Discord) to navbar - Local LiveKit/Pipecat SVGs with currentColor fills - CSS filters for theme-aware logo coloring (blue light / orange dark) - Replaced all 9 external assemblyaiassets.com logo references with local SVGs - Fixed broken redirects: deployment/, lemur/, bare guardrails URLs - Added redirects for /docs/pii-redaction, /docs/content-moderation, /docs/speech-threshold, /docs/profanity-filtering → /docs/guardrails/ - Fixed /docs/audio-intelligence/:slug wildcard → speech-understanding - Fixed webhook slug collisions with explicit /webhooks and /streaming/webhooks - Renamed tab "Async STT" → "Pre-recorded STT" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Broken links fixed in page content: - Guardrails index: /docs/pii-redaction → /docs/guardrails/pii-redaction (all 4 cards) - 12+ pages: /docs/deployment/* → new locations (/docs/webhooks, /docs/streaming/webhooks, /docs/account-management) - Streaming anchor links: /docs/streaming#authenticate-with-a-temporary-token → /docs/streaming/authenticate-with-a-temporary-token (etc.) Missing redirects added: - /docs/deployment/webhooks → /docs/webhooks - /docs/deployment/webhooks-streaming → /docs/streaming/webhooks - /docs/deployment/account-management → /docs/account-management - /docs/deployment/self-hosted-streaming → /docs/streaming/self-hosted-streaming - /docs/deployment/self-hosted-async → /docs/self-hosted-async - /docs/deployment → /docs/ - /docs/pii-redaction → /docs/guardrails/pii-redaction - /docs/content-moderation → /docs/guardrails/content-moderation - /docs/speech-threshold → /docs/guardrails/speech-threshold - /docs/profanity-filtering → /docs/guardrails/profanity-filtering - /docs/pre-recorded-audio/code-switching → code-switching-docs - Explicit audio-intelligence → speech-understanding for all 6 features Slug fixes: - Explicit slugs for /evaluations, /benchmarks, /account-management - Explicit slugs for eval sub-pages: /evaluations/pre-recorded-audio, /evaluations/voice-agents - Webhook slug collision: /webhooks (pre-recorded), /streaming/webhooks - Removed duplicate redirect sources (getting-started/faq, keyterms) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Broken Link AuditI checked all 179 unique internal 1.
|
| Broken Link | Correct URL | Referenced In |
|---|---|---|
/docs/pre-recorded-audio/universal-3-pro |
/docs/universal-3-pro |
4 files (FAQs, models, getting-started, streaming prompting guide) |
/docs/pre-recorded-audio/prompting |
/docs/prompting |
4 files (models, pre-recorded-evals, universal-3-pro, streaming prompting) |
/docs/pre-recorded-audio/speaker-diarization |
/docs/speaker-diarization |
3 files (getting-started, speaker-diarization page, prompt-engineering) |
/docs/pre-recorded-audio/supported-languages |
/docs/supported-languages |
8 files (entity-detection, ALD guides, code-switching, errors guide, etc.) |
/docs/pre-recorded-audio/language-detection |
/docs/language-detection |
2 files (set-language-manually, getting-started) |
/docs/pre-recorded-audio/keyterms-prompting |
/docs/keyterms-prompting |
2 files (code-switching-docs, prompt-engineering) |
/docs/pre-recorded-audio/improving-transcript-accuracy |
/docs/keyterms-prompting |
1 file (FAQ) |
/docs/pre-recorded-audio/export-paragraphs-and-sentences |
/docs/transcript-export-options |
1 file (FAQ) |
2. /docs/speech-to-text/pre-recorded-audio/* prefix is broken — needs redirect or direct fix
These old-style /docs/speech-to-text/pre-recorded-audio/ links are used in unchanged (non-PR) files like FAQs. Some have redirects defined but the redirect destinations are themselves broken (they point to /docs/pre-recorded-audio/* which is also broken).
| Broken Link | Correct URL | Referenced In |
|---|---|---|
/docs/speech-to-text/pre-recorded-audio/automatic-language-detection |
/docs/language-detection |
FAQ page |
/docs/speech-to-text/pre-recorded-audio/code-switching |
/docs/code-switching |
code-switching-docs, FAQ |
/docs/speech-to-text/pre-recorded-audio/custom-spelling |
/docs/custom-spelling |
FAQ |
/docs/speech-to-text/pre-recorded-audio/select-the-region |
(see note below) | 6 files (FAQ, data-retention, deployment) |
/docs/speech-to-text/pre-recorded-audio/set-language-manually |
/docs/set-language-manually |
FAQ |
/docs/speech-to-text/pre-recorded-audio/set-the-start-and-end-of-the-transcript |
/docs/set-the-start-and-end-of-the-transcript |
FAQ |
/docs/speech-to-text/pre-recorded-audio/speaker-diarization |
/docs/speaker-diarization |
4 files (use-cases, migration guide, FAQs) |
/docs/speech-to-text/pre-recorded-audio/word-level-timestamps |
/docs/transcript-export-options |
summarization page |
/docs/speech-to-text/pre-recorded-audio/prompting-best-practices |
/docs/prompting |
combine-keyterms guide |
/docs/speech-to-text/speaker-diarization |
/docs/speaker-diarization |
9 files (summarization, sentiment, use-cases, guides, etc.) |
Note on select-the-region: The pre-recorded region page doesn't have a clear root-level slug. The page path is select-the-region.mdx under the async-stt tab's "Getting started" section without an explicit slug, so it may resolve to something different. The streaming equivalent is at /docs/streaming-endpoints-and-data-zones.
3. /docs/streaming/* — old slugs that changed
| Broken Link | Correct URL | Referenced In |
|---|---|---|
/docs/streaming/turn-detection |
/docs/streaming/universal-streaming/turn-detection |
7 files (use-cases, messages, multichannel, guides) |
/docs/streaming/message-sequence |
/docs/streaming/universal-streaming/message-sequence or /docs/streaming/universal-3-pro/u3-pro-message-sequence |
6 files (use-cases, intro guides, getting-started) |
/docs/streaming/multichannel-streams |
/docs/streaming/diarization-and-multichannel |
streaming-diarization page |
/docs/streaming/streaming-diarization-and-multichannel |
/docs/streaming/diarization-and-multichannel |
2 files (use-cases, FAQ) |
/docs/streaming/voice-agents |
No direct equivalent (section, not a page) | universal-streaming overview |
4. /docs/llm-gateway/* — pages moved to root-level slugs
The llm-gateway tab's "Use cases" section has skip-slug: true, so pages are at root level, not under /docs/llm-gateway/.
| Broken Link | Correct URL | Referenced In |
|---|---|---|
/docs/llm-gateway/agentic-workflows |
/docs/agentic-workflows |
llm-gateway overview, migration-from-lemur |
/docs/llm-gateway/chat-completions |
/docs/chat-completions |
4 files (lemur pages, llm-gateway overview, streaming) |
/docs/llm-gateway/conversations |
/docs/conversations |
3 files (lemur, llm-gateway overview, migration) |
/docs/llm-gateway/tool-calling |
/docs/tool-calling |
llm-gateway overview, migration-from-lemur |
/docs/llm-gateway/migration-from-lemur |
/docs/migration-from-lemur |
FAQ |
/docs/llm-gateway/improving-your-prompt |
/docs/improving-your-prompt |
2 guides |
5. /docs/lemur/* — old LeMUR paths
| Broken Link | Correct URL | Referenced In |
|---|---|---|
/docs/lemur/customize-parameters |
/docs/customize-parameters |
summarize-audio, past-response-prompts guide |
/docs/lemur/examples |
/docs/examples |
summarize-audio |
/docs/lemur/improving-your-prompt |
/docs/improving-your-prompt |
summarize-audio |
Note: There's a wildcard redirect /docs/lemur/:slug → /docs/llm-gateway/:slug, but since these pages are now at root level (not /docs/llm-gateway/), the redirect chain ends in a 404.
6. /docs/guides/* — guides moved or removed
These guide pages were reorganized into product tabs. Links pointing to the old /docs/guides/ paths are broken:
| Broken Link | Now Located At | Referenced In |
|---|---|---|
/docs/guides/creating-summarized-chapters-from-podcasts |
/docs/speech-understanding/auto-chapters/creating-summarized-chapters-from-podcasts |
audio-intelligence guide, guides index |
/docs/guides/identifying-highlights-in-audio-or-video-files |
/docs/speech-understanding/key-phrases/identifying-highlights-in-audio-or-video-files |
audio-intelligence guide, guides index |
/docs/guides/identifying-hate-speech-in-audio-or-video-files |
/docs/speech-understanding/topic-detection/identifying-hate-speech-in-audio-or-video-files |
audio-intelligence guide, guides index |
/docs/guides/summarizing-virtual-meetings |
/docs/speech-understanding/summarization/summarizing-virtual-meetings |
guides index, audio-intelligence guide |
/docs/guides/transcribing-an-audio-file |
(page appears removed) | 4 files (FAQ, guides index, google-drive guide) |
/docs/guides/automatic-language-detection-workflow |
(page appears removed) | pre-recorded guide, guides index |
/docs/guides/generating-subtitles-for-videos |
(page appears removed) | guides index |
/docs/guides/real-time-streaming-transcription |
(page appears removed) | streaming guide, guides index |
/docs/guides/partial_transcripts |
(page appears removed) | streaming guide |
/docs/guides/input-text-speaker-labels |
(page appears removed) | guides index |
/docs/guides/custom-vocab-lemur |
(page appears removed) | lemur examples, custom-vocabulary |
/docs/guides/speaker-identification |
(page appears removed) | lemur examples |
/docs/guides/speechmatics_to_aai_streaming |
/docs/migration-guides/speechmatics_to_aai_streaming |
self-referencing in migration guide |
7. Use cases — slug mismatch
| Broken Link | Correct URL | Referenced In |
|---|---|---|
/docs/meeting-notetaker-best-practices |
Exists in nav but 404s — may be a slug collision (page appears under both Overview and Guides sections) | use-cases index |
/docs/medical-scribe-best-practices |
Same issue as above | use-cases index |
These pages are defined in multiple places in docs.yml (Overview tab section 82-91 AND Pre-recorded STT Guides section 752-757 AND Streaming STT Guides section 1032-1037). The duplicate definitions with the same slug may be causing conflicts.
8. Redirect chains that end in 404
Several redirects in docs.yml point to destinations that are themselves broken:
/docs/speech-to-text/pre-recorded-audio/:slug→/docs/pre-recorded-audio/:slug(many/pre-recorded-audio/URLs are 404)/docs/lemur/:slug→/docs/llm-gateway/:slug(but pages are at root level, not under/llm-gateway/)/docs/streaming/multichannel-streams→/docs/streaming/streaming-diarization-and-multichannel(destination is 404, correct URL is/docs/streaming/diarization-and-multichannel)/docs/streaming/streaming-diarization→/docs/streaming/streaming-diarization-and-multichannel(same issue)/docs/speech-to-text/pre-recorded-audio/improving-transcript-accuracy→/docs/pre-recorded-audio/keyterms-prompting(destination 404)
Summary
The majority of broken links fall into a few systematic patterns:
/docs/pre-recorded-audio/*should be/docs/*— theskip-slug: trueon the async-stt tab means pages are at root level/docs/llm-gateway/*use-case pages should be/docs/*— sameskip-slugissue/docs/streaming/turn-detectionand/docs/streaming/message-sequenceneed the/universal-streaming/prefix now- Several guides moved under speech-understanding sub-sections and need updated paths
- Redirect chains need updating since intermediate destinations are also broken
- Add /pre-recorded-audio/ prefix to Models & features section slug - Add /llm-gateway/ prefix to Use cases section slug - Fix use-case page slug collisions (meeting-notetaker, medical-scribe) - Add slug for Cloud endpoints page and Keyterms prompting page - Fix redirect chains ending in 404 - Add redirects for moved guides and streaming page renames - Update broken streaming links in MDX files (turn-detection, message-sequence, diarization) - Update broken guide links in MDX files to new paths Co-Authored-By: Lee Vaughn <dlvprogramming@gmail.com>
- Fix turn-detection links to use /docs/streaming/universal-streaming/turn-detection - Fix message-sequence links to use /docs/streaming/universal-streaming/message-sequence - Fix streaming-diarization-and-multichannel links to use correct path - Fix concurrency-limit links to point to /docs/account-management - Fix models/speech-recognition links to point to /docs/getting-started/models - Fix code-switching links and add explicit slug for code-switching page - Fix prompting-best-practices links to /docs/pre-recorded-audio/prompting - Fix vapi link to external https://vapi.ai - Fix speechmatics self-referencing link to use migration-guides path - Add skip-slug to Use case guides section - Add redirects for prompting-best-practices, concurrency-limit, models/speech-recognition, streaming-diarization - Fix turn-detection and message-sequence redirect destinations Co-Authored-By: Lee Vaughn <dlvprogramming@gmail.com>
Co-Authored-By: Lee Vaughn <dlvprogramming@gmail.com>
…slug Co-Authored-By: Lee Vaughn <dlvprogramming@gmail.com>
Co-Authored-By: Lee Vaughn <dlvprogramming@gmail.com>
… pages Co-Authored-By: Lee Vaughn <dlvprogramming@gmail.com>
LeeVaughn
approved these changes
Mar 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Full docs navigation restructure across all 7 product tabs, with content redistribution, new landing pages, LLM-optimized metadata, and comprehensive redirect coverage.
Overview tab (renamed from "Get Started")
Pre-recorded STT tab (renamed from "Async STT")
Streaming STT tab
Speech Understanding tab
Guardrails tab
LLM Gateway tab
Cross-cutting changes
Updates since last revision (broken link fixes — round 1)
Addressed 47 broken internal links identified during review:
/pre-recorded-audio/prefix to "Models & features" section slug, added explicit slugs for Cloud endpoints and Keyterms prompting pages/llm-gateway/prefix to "Use cases" section slug, converted absolute slugs to relativeUpdates since last revision (broken link fixes — round 2)
Additional fixes after testing the latest preview deployment:
{/_ @api-infosyntax in 59 MDX files (restored to valid{/* @api-infofor acorn parser compatibility)/docs/pre-recorded-audio/code-switchingwas both source and destination, updated internal links fromcode-switching-docstocode-switching/docs/deployment/webhooks-for-pre-recorded-audio→/docs/webhooks,/docs/deployment/webhooks-for-streaming-speech-to-text→/docs/streaming/webhooks/docs/evaluations/benchmarks→/docs/benchmarks/docs/guides/*to/docs/migration-guides/*(aws_to_aai, dg_to_aai, dg_to_aai_streaming, gladia-to-aai-streaming, gladia_to_aai, google_to_aai, oai_to_aai)/docs/guides/entity_redaction→/docs/speech-understanding/entity-detection/entity_redaction/docs/guides/tracking-your-customers-usage→/docs/account-management/docs/streaming/streaming-endpoints-and-data-zones→/docs/streaming-endpoints-and-data-zones,/docs/streaming/voice-agents-and-orchestrators→/docs/streaming/voice-agentsReview & Testing Checklist for Human
Critical items to verify against the latest preview deployment:
/docs/deployment/webhooks-for-pre-recorded-audio,/docs/guides/aws_to_aai,/docs/guides/entity_redaction,/docs/streaming/voice-agents-and-orchestratorsand verify they redirect to correct destinations/docs/pre-recorded-audio/code-switchingand verify content loads (not 404)@api-infometadata (e.g., voice-agent-best-practices.mdx, entity-detection.mdx) and verify they parse correctly without acorn errors/pre-recorded-audio/prefix — Navigate to docs.yml "Models & features" section pages (e.g., Universal-3 Pro, Prompting guide) and verify URLs include/pre-recorded-audio//llm-gateway/prefix — Navigate to Use cases section pages and verify URLs include/llm-gateway/Notes