Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

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

wants to merge 6 commits into from

Conversation

@tbaxter-coveo
Copy link
Contributor

@tbaxter-coveo tbaxter-coveo commented Nov 21, 2025 •
edited
Loading

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

@tbaxter-coveo tbaxter-coveo requested a review from a team as a code owner November 21, 2025 22:04
@tbaxter-coveo tbaxter-coveo marked this pull request as draft November 21, 2025 22:04
Copilot finished reviewing on behalf of tbaxter-coveo November 21, 2025 22:06
github-code-quality[bot]
github-code-quality bot found potential problems Nov 21, 2025
View reviewed changes
Copilot AI reviewed Nov 21, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

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
Copy link

github-actions bot commented Nov 21, 2025 •
edited
Loading

🔗 Scratch Orgs ready to test this PR:

jpmarceau
jpmarceau reviewed Nov 24, 2025
View reviewed changes
Copy link
Contributor

@jpmarceau jpmarceau left a comment

Choose a reason for hiding this comment

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

Do you think it would be possible to rename Modules to Reference here?
Screenshot 2025-11-24 at 11 33 56 AM
I suspect most of our readers would expect reference.

jpmarceau
jpmarceau reviewed Nov 26, 2025
View reviewed changes
Copy link
Contributor

@jpmarceau jpmarceau left a comment

Choose a reason for hiding this comment

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

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.
Screenshot 2025-11-26 at 1 01 00 PM
Not necessarily an issue, but it might be worth checking whether this affects our automation to upload to s3, just in case.

@tbaxter-coveo
Copy link
Contributor Author

tbaxter-coveo commented Nov 26, 2025

@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

jpmarceau
jpmarceau approved these changes Nov 27, 2025
View reviewed changes
Copy link
Contributor

@jpmarceau jpmarceau left a comment

Choose a reason for hiding this comment

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

Nice work!
I'm pretty excited about this migration 😄

Btw, some links look like they will change, so it would be worth checking ahead of time if we break some in our repo or in the ui-kit repo, if you haven't already.
Screenshot 2025-11-27 at 11 58 42 AM

vs
Screenshot 2025-11-27 at 11 58 30 AM

@tbaxter-coveo
Copy link
Contributor Author

tbaxter-coveo commented Nov 27, 2025

@jpmarceau

Btw, some links look like they will change, so it would be worth checking ahead of time if we break some in our repo or in the ui-kit repo, if you haven't already.

Honestly, how the URLs generated here translate to the rewritten URLs on our site is not always clear to me.

If the assumption is that everything after 8080 in dev URLs are what should appear after https://docs.coveo.com/en/headless/latest/reference on production, I'll ensure they do not change.

@tbaxter-coveo
Copy link
Contributor Author

tbaxter-coveo commented Nov 27, 2025

@jpmarceau I have restored the previous URL formatting for non-projectDocuments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@jpmarceau jpmarceau jpmarceau approved these changes

@jsmith2-coveo jsmith2-coveo Awaiting requested review from jsmith2-coveo

@lavoiesl lavoiesl Awaiting requested review from lavoiesl lavoiesl is a code owner automatically assigned from coveo/dxui

@fbeaudoincoveo fbeaudoincoveo Awaiting requested review from fbeaudoincoveo fbeaudoincoveo is a code owner automatically assigned from coveo/dxui

@alexprudhomme alexprudhomme Awaiting requested review from alexprudhomme alexprudhomme is a code owner automatically assigned from coveo/dxui

+1 more reviewer

@github-code-quality github-code-quality[bot] github-code-quality[bot] left review comments

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@tbaxter-coveo @jpmarceau