Adds video guidance to syntax ref guide#3253
Conversation
📝 WalkthroughWalkthroughThis pull request introduces a new documentation page that provides guidance on embedding and linking videos in the docs. The changes include adding a reference to 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/syntax/videos.md`:
- Line 6: The Elastic-hosted example contradicts the "Video link URLs must use
lowercase characters only" rule by using a mixed-case ID in the example URLs;
update the Elastic example so both video link URLs use the lowercase-only ID
(replace the mixed-case ID with its lowercase equivalent in the Elastic-hosted
example) so the guidance and example are consistent.
- Line 53: Update the checklist entry that currently reads "Use lowercase
characters in all video URLs" so it only applies to Elastic/integrations style
paths (e.g., URLs containing "elastic" or "/integrations/") and not to external
provider IDs like YouTube video IDs; change the sentence to explicitly scope
lowercase requirement to Elastic/integrations URL pattern and add a note that
provider IDs (e.g., YouTube IDs) must be left case-sensitive. Also adjust the
related duplicate instances of that checklist text so they match the new scoped
wording.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 17ab26ba-50e3-43af-9a9c-2560dbb20f0e
📒 Files selected for processing (2)
docs/_docset.ymldocs/syntax/videos.md
| Videos can supplement documentation to demonstrate features, workflows, or complex procedures. Embed videos using standard Markdown link and image syntax. | ||
|
|
||
| :::{important} | ||
| Video link URLs must use **lowercase characters only**. Mixed-case URLs cause build failures in integrations documentation. |
There was a problem hiding this comment.
Lowercase rule is contradicted by the Elastic-hosted example
Line 6 requires lowercase-only URLs, but Line 20 uses a mixed-case ID in both URLs. This undercuts the guidance and can lead to copy/paste failures in integration docs.
Suggested doc fix
-Video link URLs must use **lowercase characters only**. Mixed-case URLs cause build failures in integrations documentation.
+For integrations documentation, video link URLs must use **lowercase characters only**. Mixed-case URLs can cause build failures.
@@
-[](https://videos.elastic.co/watch/eT92arEbpRddmSM4JeyzdX?)
+[](https://videos.elastic.co/watch/video_id?)Also applies to: 20-20
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/syntax/videos.md` at line 6, The Elastic-hosted example contradicts the
"Video link URLs must use lowercase characters only" rule by using a mixed-case
ID in the example URLs; update the Elastic example so both video link URLs use
the lowercase-only ID (replace the mixed-case ID with its lowercase equivalent
in the Elastic-hosted example) so the guidance and example are consistent.
There was a problem hiding this comment.
Maybe we should say Video link URLs must use lowercase characters only, otherwise they cause build errors in integrations docs or something like that on line 5
There was a problem hiding this comment.
@benironside That reads well — combining the rule and consequence into one sentence is cleaner. Here's a concrete version keeping the bold for emphasis:
Video link URLs must use **lowercase characters only**, otherwise they cause build failures in integrations documentation.
|
|
||
| - ✅ Introduce videos with context, such as "The following video demonstrates these steps (click to watch)." | ||
| - ✅ Use descriptive alt text that explains the video content | ||
| - ✅ Use lowercase characters in all video URLs |
There was a problem hiding this comment.
“All video URLs lowercase” is too broad and conflicts with YouTube IDs
Line 53/58 says all video URLs must be lowercase, but Line 44 shows a mixed-case YouTube ID. Lowercasing YouTube IDs can break links. Scope the lowercase warning to the Elastic/integrations URL pattern only.
Also applies to: 58-58, 44-44
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/syntax/videos.md` at line 53, Update the checklist entry that currently
reads "Use lowercase characters in all video URLs" so it only applies to
Elastic/integrations style paths (e.g., URLs containing "elastic" or
"/integrations/") and not to external provider IDs like YouTube video IDs;
change the sentence to explicitly scope lowercase requirement to
Elastic/integrations URL pattern and add a note that provider IDs (e.g., YouTube
IDs) must be left case-sensitive. Also adjust the related duplicate instances of
that checklist text so they match the new scoped wording.
benironside
left a comment
benironside
left a comment
There was a problem hiding this comment.
LGTM, syntax is familiar. Not blocking, but the callout about the lowercase URLs is interesting. I haven't tested it but I think making clear exactly what happens with integrations docs if we use video URLs with mixed cases would be helpful.
| Videos can supplement documentation to demonstrate features, workflows, or complex procedures. Embed videos using standard Markdown link and image syntax. | ||
|
|
||
| :::{important} | ||
| Video link URLs must use **lowercase characters only**. Mixed-case URLs cause build failures in integrations documentation. |
There was a problem hiding this comment.
Maybe we should say Video link URLs must use lowercase characters only, otherwise they cause build errors in integrations docs or something like that on line 5
2 participants
Resolves elastic/docs-content#5626 by adding guidance on how to add videos to docs.