feat: migrating content from docs.coveo.com to typedoc

[tbaxter-coveo]

This migrates all content for headless from docs.coveo.com over to the typedoc site. It does not contain any textual changes. This also makes some changes to the headless-react typedoc site to align them with the changes in the headless site.

This introduces a fair amount of change to the organization of the site.

This is in Draft to allow the docs team to comment first.

To test:

• from packages/documentation run pnpm build
  • this is build the typedoc plugin which customizes the behaviour of the typedoc navigation
• from the packages/headless directory run pnpm run build:typedoc && pnpm run serve:typedoc
• from the packages/headless-react directory run pnpm run build:typedoc && pnpm run serve:typedoc

[Copilot]

Pull request overview

This PR migrates documentation content from docs.coveo.com to the TypeDoc-generated site for the Headless package. The changes introduce comprehensive documentation reorganization with new markdown files, custom navigation ordering, and a TypeDoc plugin enhancement to support advanced navigation features.

Key Changes

• Documentation migration: 28 markdown documentation files added covering usage, upgrade guides, SSR, analytics, and various Headless features
• Navigation customization: New TypeDoc plugin features for hoisting categories, sorting top-level and nested navigation items
• Configuration updates: TypeDoc configuration with project documents, custom ordering, and navigation settings

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
packages/headless/typedoc.json	Added projectDocuments array with 29 documentation files, configured navigation ordering and hoisting
packages/headless/typedoc-configs/index.typedoc.json	Added "Home" and "Contributing" to groupOrder
packages/headless/source_docs/*.md	28 new documentation markdown files covering all aspects of Headless usage
packages/documentation/lib/index.tsx	Enhanced with navigation manipulation, ordering, and hoisting logic
packages/documentation/lib/hoist.ts	New utility for hoisting "Other" categories in navigation
packages/documentation/lib/sortNodes.ts	New utility for sorting navigation nodes with custom ordering
packages/documentation/lib/types.ts	New NavNode type definition
packages/documentation/lib/normalize.ts	New string normalization utility
packages/documentation/lib/*.ts	Converted function declarations to arrow functions for consistency
packages/documentation/README.md	New README documenting the plugin's navigation features
.cspell.json	Added "coveoua" to dictionary

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

🔗 Scratch Orgs ready to test this PR:

• ✅ LWS Enabled: Open Org
• ✅ LWS Disabled: Open Org

[jpmarceau]

Do you think it would be possible to rename Modules to Reference here?

I suspect most of our readers would expect reference.

[jpmarceau]

I have some TOC comments, but I think this already looks quite good overall 🚀

[jpmarceau]

I'm happy with the simple slug solution 👍

I notice that the generated html pages now show up directly under /docs, rather than in subfolders.

Not necessarily an issue, but it might be worth checking whether this affects our automation to upload to s3, just in case.

[jpmarceau]

It would be nice to have some kind of box for this. Right now, with indentation alone, it's not immediately clear what's part of the warning:

[tbaxter-coveo]

Used the markdown

> [!WARNING]
> To provide an indent
> as well as a group marking

like this

Warning

To provide an indent
as well as a group marking

[jpmarceau]

Could you setup a similar config in the headless-react package, to ensure we respect the current ordering of the reference docs?
Compare the existing TOC: https://docs.coveo.com/en/headless-react/latest/reference/index.html

Versus what happens if I build from your branch:

[tbaxter-coveo]

I certainly can, but this points to another issue: currently this headless react content will not be linked anywhere from the site at all... at least not directly.

The only place it is linked is https://docs.coveo.com/en/headless/latest/reference/ and that page is going away (as far as I understand it). We should update the homepage of this library with a link to that reference documentation.

I'll do what I can to align these two projects as closely as possible.

[jpmarceau]

Good point.

[tbaxter-coveo]

I've added a link to the headless-react docs as well as aligned the two typedoc sites.

This includes some reordering of that site as well, specifically I moved the Controller hooks out of SSR Commerce.

My rationale for this was twofold:

• placing it under SSR Commerce introduced a Modules and index subfolders under SSR Commerce, promoting this out flattened that and aligns SSR Commerce with SSR Search
• In the headless docs, we have a number of docs under Usage which are relevant to only select aspects of the site. They are not grouped under the modules they relate to
  • I did not want to introduce a Usage section with only a single document, which is why it lives at the root unlike in the headless typedoc

[tbaxter-coveo]

@jpmarceau

I notice that the generated html pages now show up directly under /docs, rather than in subfolders.

I've fixed this, was an artifact of rewriting the URLs