Route reference links to openvidu.io instead of docs.livekit.io - #17
Open
gortazar wants to merge 4 commits into
Open
Route reference links to openvidu.io instead of docs.livekit.io#17gortazar wants to merge 4 commits into
gortazar wants to merge 4 commits into
Conversation
This site wins real search traffic for LiveKit-brand tutorial queries,
but its reference links funnel that traffic straight to a competitor's
domain (openvidu-marketing issue #39, "leaky funnel"). OpenVidu now has
its own Platform reference docs (openvidu.io#105 / issue #44) covering
the same ground, so swap the links that map cleanly:
- 29x webhooks references -> openvidu.io's webhooks reference (full
event table, payload schema, delivery semantics — verified equivalent)
- 16x "Video Grants" references -> openvidu.io's access-tokens
reference (18 grants documented, same claim/permission model)
- 3x Egress overview/API -> openvidu.io's egress reference
- 1x Ingress overview -> openvidu.io's ingress reference
Deliberately NOT swapped (28 remaining docs.livekit.io links):
- 2x egress/outputs#filename-templating: OpenVidu's egress page doesn't
document the {room_name}/{time}/{room_id} filename template syntax,
so swapping would send readers to a page missing that specific detail
- self-hosting/local + self-hosting/egress (6 links): about running
LiveKit's own server/egress locally for dev, a different topic than
OpenVidu's Egress reference
- client-sdk-js/server-sdk-js/Android/Swift typedoc links (~20 links):
LiveKit's generated class/method API docs; OpenVidu's client-sdk.md is
a conceptual overview, not generated typedoc — issue #44 deliberately
didn't try to mirror these
Blocked on openvidu.io#105 merging and publishing first — none of the
target URLs are live yet, so this should not merge before that lands.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DuKTd5TG5mRZMFa7cAsAvs
There was a problem hiding this comment.
Pull request overview
Updates this documentation site’s reference links so that high-intent “reference” clicks go to OpenVidu’s Platform reference docs on openvidu.io (instead of sending users to docs.livekit.io), aligning with the new OpenVidu reference section described in the PR.
Changes:
- Repoint webhook reference links to
https://openvidu.io/latest/docs/reference/webhooks/. - Repoint “Video Grants” links to
https://openvidu.io/latest/docs/reference/access-tokens/#video-grants. - Repoint Egress/Ingress reference links to
https://openvidu.io/latest/docs/reference/egress/andhttps://openvidu.io/latest/docs/reference/ingress/.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| shared/run-livekit-server.md | Updates Webhooks reference link targets to openvidu.io. |
| shared/run-livekit-server-and-egress.md | Updates Webhooks reference link targets to openvidu.io. |
| docs/tutorials/application-server/rust.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/ruby.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/python.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/php.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/node.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/java.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/index.md | Repoints the webhook reference link to openvidu.io. |
| docs/tutorials/application-server/go.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/application-server/dotnet.md | Repoints webhook + video grants reference links to openvidu.io. |
| docs/tutorials/advanced-features/recording-basic.md | Repoints Egress API reference link to openvidu.io. |
| docs/openvidu-vs-livekit.md | Repoints Egress/Ingress reference links to openvidu.io. |
| docs/index.md | Repoints the main “webhook events” reference link to openvidu.io. |
Suppressed comments (2)
shared/run-livekit-server.md:31
- Same wording issue as above: after repointing the Webhooks link to openvidu.io, "official documentation" is ambiguous about whose docs are being referenced.
All [application servers](../application-server/index.md){:target="\_blank"} have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit Cloud you need to configure webhooks to point to your local application server in order to make it work. Check the [Webhooks](https://openvidu.io/latest/docs/reference/webhooks/){target="\_blank"} section from the official documentation and follow the instructions to configure webhooks.
shared/run-livekit-server-and-egress.md:31
- Grammar: "This tutorial have" should be "This tutorial has". Also, after repointing the Webhooks link to openvidu.io, "official documentation" is ambiguous—consider explicitly referencing OpenVidu's reference docs in the wording.
This tutorial have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit Cloud you need to configure webhooks to point to your local application server in order to make it work. Check the [Webhooks](https://openvidu.io/latest/docs/reference/webhooks/){target="\_blank"} section from the official documentation and follow the instructions to configure webhooks.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| - Generate LiveKit tokens on demand for any [application client](#application-client-tutorials). | ||
| - Receive LiveKit [webhook events](https://docs.livekit.io/home/server/webhooks/){target=\_blank}. | ||
| - Receive LiveKit [webhook events](https://openvidu.io/latest/docs/reference/webhooks/){target=\_blank}. |
| !!! info "Configure Webhooks" | ||
|
|
||
| All [application servers](../application-server/index.md){:target="\_blank"} have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit locally you need to configure webhooks to point to your application server in order to make it work. Check the [Webhooks](https://docs.livekit.io/home/server/webhooks/){target="\_blank"} section from the official documentation and follow the instructions to configure webhooks. | ||
| All [application servers](../application-server/index.md){:target="\_blank"} have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit locally you need to configure webhooks to point to your application server in order to make it work. Check the [Webhooks](https://openvidu.io/latest/docs/reference/webhooks/){target="\_blank"} section from the official documentation and follow the instructions to configure webhooks. |
| !!! info "Configure Webhooks" | ||
|
|
||
| This tutorial have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit locally you need to configure webhooks to point to your application server in order to make it work. Check the [Webhooks](https://docs.livekit.io/home/server/webhooks/){target="\_blank"} section from the official documentation and follow the instructions to configure webhooks. | ||
| This tutorial have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit locally you need to configure webhooks to point to your application server in order to make it work. Check the [Webhooks](https://openvidu.io/latest/docs/reference/webhooks/){target="\_blank"} section from the official documentation and follow the instructions to configure webhooks. |
Completes the other three recommendations from openvidu-marketing issue #39-b (the "Deploy" default was already OpenVidu-first in both tabbed snippets — verified, no change needed there): - Persistent CTA band (Material's announce block, dismissible) on every page, pointing to openvidu.io. - UTM-tagged the genuine conversion touchpoints: the announce band, all 6 openvidu.io links on the about-openvidu funnel page, all 4 on the openvidu-vs-livekit comparison page, and the "Deploy OpenVidu" guide + its webhook-config link in both run-livekit-server shared snippets. utm_source=livekit-tutorials, utm_medium=referral, utm_campaign identifies which touchpoint (announce-cta / about-openvidu-page / comparison-page / deploy-step) so referrals are attributable per placement, not just lumped as one number. - Left the generic in-tutorial reference links (webhooks/access-tokens/ etc., from this PR's earlier commit) untagged — those are technical lookups available regardless of which deploy path a reader chose, not conversion CTAs. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DuKTd5TG5mRZMFa7cAsAvs
Completes item (4) from issue #39, "strengthen nav/footer routing" — the one item dropped when this was first scoped down to "three items" in conversation. - mkdocs.yml: "What is OpenVidu?" and "OpenVidu vs LiveKit" move from the last two nav items (after all three tutorial sections) to right after the homepage, so they're visible before a reader commits to a specific tutorial. Side effect: the footer's auto-generated "Next" link on the homepage now points to "What is OpenVidu?" instead of the first tutorial section. - docs/overrides/partials/footer.html: added a 4th footer column (What is OpenVidu? / OpenVidu vs LiveKit / openvidu.io, UTM-tagged utm_campaign=footer) so every page keeps a permanent OpenVidu touchpoint even after the announce band is dismissed. Simplified the existing 3-column push/pull layout to 4 plain grid-25 columns in the process — the push-66/pull-33 indirection wasn't needed to add a column and made the actual visual order harder to follow than the DOM order. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DuKTd5TG5mRZMFa7cAsAvs
Organization + WebSite + WebPage on every page. The Organization node deliberately reuses the exact same @id, name, description, logo, sameAs and contactPoint as the main openvidu.io site's own JSON-LD, rather than declaring a separate one for this subdomain — so search engines and AI crawlers read this LiveKit tutorial content as published by the same entity as openvidu.io, reinforcing the funnel work already in this PR (issue #39) instead of leaving this looking like an unrelated LiveKit fan site. Per-page-type richness (TechArticle/HowTo step markup, BreadcrumbList, FAQPage) is a deliberate follow-up, not attempted here. Found and fixed one real bug during verification: page.canonical_url is undefined on the 404 page (it has no real Page object), which crashed the build with a Jinja TypeError. Guarded the whole block on `page and page.canonical_url` — the 404 page now correctly emits no JSON-LD at all rather than a broken script tag. Verified: mkdocs build clean, and the emitted JSON-LD is valid on the homepage and a deep tutorial page (correct canonical URLs, page title/description, publisher attribution) by parsing the actual built HTML output, not just visual inspection. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DuKTd5TG5mRZMFa7cAsAvs
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
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
This site ranks well for LiveKit-brand tutorial queries (openvidu-marketing issue #39, "leaky funnel"), but funnels that traffic poorly. This PR now covers all five of #39's original recommendations, plus JSON-LD structured data reinforcing the same attribution goal.
1. Route reference links to openvidu.io instead of docs.livekit.io
OpenVidu now has its own Platform reference docs covering the same ground (
openvidu.ioPR #105, issue #44), so this swaps the links that map cleanly onto them.Swapped (49 links): 29x webhooks, 16x access-tokens ("Video Grants"), 3x Egress, 1x Ingress — each verified to cover the same ground as the LiveKit page it replaces.
Deliberately NOT swapped (28 links): 2x
egress/outputs/#filename-templating(OpenVidu's page doesn't document that syntax specifically), 6xself-hosting/local+self-hosting/egress(running LiveKit's own components locally, a different topic), ~20x generated SDK typedoc links (OpenVidu'sclient-sdk.mdis conceptual, not generated docs).2. Persistent OpenVidu CTA band
Material's
announceblock (dismissible), on every page, pointing to openvidu.io.3. "Deploy" step default
Checked both tabbed snippets (
run-livekit-server.md,run-livekit-server-and-egress.md) — "Run OpenVidu locally"/"Deploy OpenVidu" already came first, before the LiveKit options. No change needed.4. Strengthen nav/footer routing
mkdocs.yml: moved "What is OpenVidu?" and "OpenVidu vs LiveKit" from the last two nav items (after all three tutorial sections) to right after the homepage.docs/overrides/partials/footer.html: added a 4th footer column (What is OpenVidu? / OpenVidu vs LiveKit / openvidu.io) so the OpenVidu touchpoint survives dismissing the announce band. Simplified the old 3-column push/pull layout to 4 plain columns in the process.5. UTM tagging
utm_source=livekit-tutorials,utm_medium=referral, and a distinctutm_campaignper touchpoint (announce-cta/about-openvidu-page/comparison-page/deploy-step/footer) on every genuine conversion link.6. JSON-LD structured data (new — beyond #39's original scope)
Organization + WebSite + WebPage on every page. The Organization node reuses the exact same
@id/name/description/logo/sameAs/contactPoint as openvidu.io's own live JSON-LD, so this content is attributed to the same publisher entity for search engines and AI crawlers, rather than reading as an unrelated LiveKit fan site. Per-page richness (TechArticle/HowTo, BreadcrumbList, FAQPage) is a deliberate follow-up, not attempted here.Caught and fixed a real bug during verification:
page.canonical_urlis undefined on the 404 page, which crashed the build. Guarded onpage and page.canonical_url; verified by parsing the actual built HTML (homepage, a deep tutorial page, and 404.html) rather than just eyeballing it.Do not merge before openvidu.io#105 merges and publishes. None of the target
openvidu.io/latest/docs/reference/*URLs are live yet — merging this first would replace working links with broken ones.Test plan
mkdocs build(non-strict) clean across all four commits — only pre-existing, unrelated#run-openvidu-locally/#deploy-openviduanchor warningsmkdocs servepreview: announce band, nav order, footer columns all render cleanly (screenshots taken)🤖 Generated with Claude Code
https://claude.ai/code/session_01DuKTd5TG5mRZMFa7cAsAvs