Integrate UI customization documentation into OptiView Player

[jpestugia]

Summary

• reposition Open Video UI as the component-based customization option for OptiView Player
• group UI documentation into Default UI, Open Video UI, and Chromeless approaches
• nest Open Video UI documentation within the relevant Player SDK sections
• provide consistent introductions, getting-started guides, how-to guides, and examples across SDKs
• split oversized chromeless guides into focused component mapping, UX, error handling, and sample pages
• preserve legacy Open Video UI URLs through redirects
• remove the obsolete standalone Open Video UI documentation plugin and supporting configuration

Test plan

• Run Prettier formatting checks
• Run MDX spellcheck
• Run ESLint
• Run TypeScript type checking
• Run the full Docusaurus production build
• Verify Web, Android, iOS/tvOS, React Native, and Roku UI routes locally
• Verify legacy Open Video UI redirects

Replaces #870 so the preview workflow can access repository secrets.

[theoplayer-bot]

Documentation preview
🚀 View preview at https://docs-preview.optiview.dolby.com/pr-873/
Deployed from commit 1d5ddd0 at 2026-09-21 09:41 UTC.

[MattiasBuelens]

I'm not a huge fan of this deeply nested navigation structure... 😕 Have a look at the breadcrumbs on https://docs-preview.optiview.dolby.com/pr-873/theoplayer/how-to-guides/web/ui/open-video-ui/guides/custom-ui/:

Player > How-to guides > UI > Open Video UI > How-to guides > Making a custom UI

[jpestugia]

I'm not a huge fan of this deeply nested navigation structure... 😕 Have a look at the breadcrumbs on https://docs-preview.optiview.dolby.com/pr-873/theoplayer/how-to-guides/web/ui/open-video-ui/guides/custom-ui/:

Player > How-to guides > UI > Open Video UI > How-to guides > Making a custom UI

@MattiasBuelens , do you have a suggestion for how you prefer to handle this?
We could move UI beside “How-to guides”: Player > UI > Open Video UI > How-to guides > {page}
Or
Keep UI under “How-to guides” and remove How-to/Examples category levels: Player > How-to guides > UI > Open Video UI > {page}
Or
Flatten both. Move UI top-level and remove internal category levels: Player > UI > Open Video UI > {page}.

[MattiasBuelens]

@MattiasBuelens , do you have a suggestion for how you prefer to handle this?
We could move UI beside “How-to guides”: Player > UI > Open Video UI > How-to guides > {page}

I think I like that best. That puts it at the same level as "Connectors", which feels right.

(There are probably more articles that deserve their own section outside of "How-to guides", but that's for another time.)

[MattiasBuelens]

On a more general note, we would like to highlight Open Video UI over the built-in UI, since the latter is pretty much frozen in time. (It's based on an old version of video.js, and there's no easy upgrade path without forcing customers to recheck all their CSS.)

So perhaps we should put "Open Video UI" as the first subcategory of "UI" in the sidebar, and also put it at the top on the introduction pages?

[FabienLavocat]

On a more general note, we would like to highlight Open Video UI over the built-in UI, since the latter is pretty much frozen in time. (It's based on an old version of video.js, and there's no easy upgrade path without forcing customers to recheck all their CSS.)

So perhaps we should put "Open Video UI" as the first subcategory of "UI" in the sidebar, and also put it at the top on the introduction pages?

Agreed, we should move "Default UI" down to the end.

[FabienLavocat]

We should also update the documentation page from the Open Video UI SDK to maybe move the following text to the Player > How-to guides > UI {introduction} page.

Choose the approach that fits your requirements:

Use the basic default UI when its ready-made controls meet your needs.
Use Open Video UI when you want a custom experience without building common player components yourself.
Use the chromeless player when you want to start with no UI and build every control and interaction from scratch.

[MattiasBuelens]

Sidebars look good now!

We should adjust the URLs too though: these articles are no longer in /how-to-guides/. Either /theoplayer/web/ui/ or /theoplayer/ui/web/ works, pick whatever is easiest or cleanest.

[MattiasBuelens]

We should adjust the URLs too though: these articles are no longer in /how-to-guides/. Either /theoplayer/web/ui/ or /theoplayer/ui/web/ works, pick whatever is easiest or cleanest.

Since connectors live at /theoplayer/connectors/web/, we should probably go for /theoplayer/ui/web/ then. 😉

[MattiasBuelens]

I also noticed that if you're on Open Video UI for Web and you use the platform dropdown to switch to Android or React Native, then we just send you back to /theoplayer/android/ instead.

Update the cross-platform linking logic to correctly handle UI pages.

[turbidwater]

@FabienLavocat I'm still looking through, but Devin had this in the meantime:

Two external links are 404 (carried over from the old chromeless guides, but now in new files so worth fixing here): theoplayer/how-to-guides/android/ui/chromeless/sample-code.mdx:7 → https://github.com/THEOplayer/samples-android-sdk/tree/master/Custom-UI. That folder does not exist; the repo has an open-video-ui folder but no Custom-UI sample.
theoplayer/how-to-guides/ios/ui/chromeless/sample-code.mdx:7 → https://github.com/THEOplayer/samples-ios-sdk/tree/master/Custom-UI. No such folder in that repo either.

It also called out this, but it seems less legitimate if we are ok just have breadcrumb items with no pages attached. It seems to be handled, since there's no link on those breadcrumb items, but I thought I'd mention if we do want the generated index pages for those breadcrumb items:

Five old URLs become 404 (no page and no redirect). These are the auto-generated category index pages that the old sidebarsOpenVideoUI.ts created with link: { type: 'generated-index' }. The new howToGuidesCategory(...) / examplesCategory(...) entries in sidebarsTheoplayer.ts have no link, so the pages are not generated and createRedirects never sees them:

/open-video-ui/web/guides/
/open-video-ui/web/examples/
/open-video-ui/react/guides/
/open-video-ui/react/examples/
/open-video-ui/android/guides/
Fix: add a generated-index link to those five categories (or add explicit entries in redirectsTHEOPlayer.json pointing to the new Open Video UI intro pages).