Repository navigation
docs: add cross-links between related documentation pages #936
Description
Gap
Docs pages are siloed with no cross-references. Users can't discover related features or understand how concepts connect. This makes the docs harder to navigate and reduces user confidence in the platform's capabilities.
Existing Docs Pages
High-Level Pages
docs/src/content/docs/guide.md— Main guide entry pointdocs/src/content/docs/whatsnew.md— Changelog/release notesdocs/src/content/docs/tips-and-tricks.md— Best practicesdocs/src/content/docs/community.md— Community resourcesdocs/src/content/docs/sdk-first-mode.md— SDK-first development modedocs/src/content/docs/insider-program.md— Insider programdocs/src/content/docs/sample-prompts.md— Sample prompts
Get Started (Onboarding)
docs/src/content/docs/get-started/— Directory with setup/intro
Features
docs/src/content/docs/features/— Feature overviews and guides
Concepts
docs/src/content/docs/concepts/— Core concepts (agent, coordinator, ceremonies, pluggable interfaces, etc.)
Reference
docs/src/content/docs/reference/— Detailed API/config reference
Cookbook
docs/src/content/docs/cookbook/— How-to guides and examples
Guide (Deep Dives)
docs/src/content/docs/guide/— Extended guides (coordination patterns, performance, etc.)
Scenarios
docs/src/content/docs/scenarios/— Real-world use case walkthroughs
Tours
docs/src/content/docs/tour-first-session.md— Guided first sessiondocs/src/content/docs/tour-github-issues.md— GitHub issues workflow tourdocs/src/content/docs/tour-gitlab-issues.md— GitLab issues workflow tour
Cross-Link Mapping
Priority 1: Foundational Links (High Traffic)
| Source Page | Target Page(s) | Link Type | Context |
|---|---|---|---|
get-started/ |
concepts/agent.md |
"Learn more" | Explain what agents are right after intro |
get-started/ |
concepts/coordinator.md |
"Learn more" | Explain coordinator role early |
get-started/ |
guide/coordination-patterns.md |
"Next steps" | Direct to intermediate topics |
concepts/agent.md |
concepts/coordinator.md |
"See also" | Bidirectional: agents work within coordinator |
concepts/coordinator.md |
concepts/agent.md |
"See also" | Bidirectional |
concepts/coordinator.md |
reference/coordinator-restraint.md |
"Detailed rules" | Link from concept to reference |
concepts/coordinator.md |
reference/compaction-recovery.md |
"Detailed rules" | Link from concept to reference |
features/ |
guide/ |
"Deep dive" | From feature overview to detailed guide |
reference/pluggable-interfaces.md |
reference/ceremony.md |
"Powered by" | Pluggable interfaces underpin ceremonies |
reference/ceremony.md |
reference/pluggable-interfaces.md |
"Uses" | Ceremonies implement pluggable patterns |
Priority 2: Workflow Links (Task-Oriented)
| Source Page | Target Page(s) | Link Type | Context |
|---|---|---|---|
cookbook/ |
scenarios/ |
"See also" | Similar but different approaches |
tour-github-issues.md |
tour-gitlab-issues.md |
"Alternative workflow" | Show other platform workflows |
guide/coordination-patterns.md |
cookbook/ |
"Examples" | Link detailed patterns to practical examples |
guide/performance-tuning.md |
reference/ |
"Details" | Performance guide links to config reference |
tips-and-tricks.md |
guide/, cookbook/ |
"Related topics" | Tips reference deeper content |
Priority 3: Cross-Domain Links (Platform Concepts)
| Source Page | Target Page(s) | Link Type | Context |
|---|---|---|---|
reference/result-persistence.md |
reference/orchestration-log.md |
"Related" | Result persistence uses orchestration log |
reference/orchestration-log.md |
reference/result-persistence.md |
"Related" | Orchestration log stores persisted results |
features/mcp-integration.md |
reference/mcp-config.md |
"Setup guide" | Feature page links to config reference |
whatsnew.md |
concepts/, features/ |
"New concepts/features" | Changelog explains what's new |
sdk-first-mode.md |
reference/sdk-api.md |
"API reference" | SDK guide links to detailed API |
Implementation: See Also Sections
Format for all pages:
At the end of each page, add a "See Also" section:
## See Also
- [Agents](../concepts/agent.md) — Learn about agent roles and charters
- [Coordination Patterns](../guide/coordination-patterns.md) — Deep dive into coordinator strategies
- [Pluggable Interfaces](../reference/pluggable-interfaces.md) — Extend Squad with custom toolsAcceptance Criteria
- Add "See Also" sections to all concept pages (bidirectional links between coordinator ↔ agent, etc.)
- Add "See Also" sections to all reference pages (link related config, API, and ceremony docs)
- Add "See Also" sections to all guide pages (link to cookbook examples and related guides)
- Add "See Also" sections to all feature pages (link to setup/reference docs)
- Test that all internal links resolve correctly (docs build succeeds)
- Cross-verify no orphaned pages (every page is linked from at least one other page, except index)
- Link table above is used as a basis for implementation (can be expanded as needed)
Source: docs-opportunity-scanner (2026-04-08)
Activity
diberry commentedon Apr 8, 2026
Too vague; needs specifics:
Suggest: Add a table or list mapping which docs should link to which, with link types (related, see-also, prerequisite).
docs: add cross-links between related documentation pages
docs: add cross-links between related documentation pages
docs: add cross-links between related documentation pages (github#956)
docs: add cross-links between related documentation pages (#956)