The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.In #2923453: Guidelines for adding videos to the User Guide I proposed allowing for videos to be embedded into pages in the user guide. It was agreed that that is a good idea, and some guidelines where proposed for how to handle it.
This patch adds a video to each of the task pages in the guide.
I ran the scripts/mkfeeds.sh script locally and can verify the videos are added. However, I do think it might be nice to figure out how to make them a bit larger. Right now they are embedded using an <embed> tag, and the player itself ends up being pretty small. Small enough that you can't really watch the video. I poked at this a little but couldn't figure how/where to modify this output. So maybe Jennifer will have some suggestions.
This also adds a README-VIDEOS.txt file with information about how to provide translated captions for any of the videos should anyone want to do so.
You can see a complete list of the videos being added in this playlist - https://www.youtube.com/watch?v=35e16QDFE7k&list=PLVqGqrTs4ZWMqt_g3RW-1j...
Note: English language captions for these are still a work in-progress. The videos all have captions created, but they are still being reviewed for accuracy, spelling, etc.. Once that's been completed we will add the completed captions to YouTube, and anyone who wishes to do so will be able to download the completed captions and/or translate them using our translation tools. In the meantime, the auto-generated captions that YouTube creates are pretty accurate though we wouldn't recommend using them as the basis for translation.
| Comment | File | Size | Author |
|---|---|---|---|
| #23 | 2944883-drupalize-videos-23.patch | 34.25 KB | jhodgdon |
| #21 | 2944883-drupalize-videos-21.patch | 29.65 KB | jhodgdon |
Comments
Comment #2
jhodgdonYeah, we can probably modify the video-blockmacro in std.conf so that it has more parameters, similar to what the image-inlinemacro does (which is just above that in std.conf).
Here is the (somewhat cryptic) documentation for the videodata element in DocBook, which shows its attributes:
http://tdg.docbook.org/tdg/5.0/videodata.html
It looks like it has width and depth that we can use, so probably if you copy the width/height section of the image macro and change it to width/depth, that will work. Then look at how we embed images with width/height and modify your use of the video macro accordingly.
If that isn't enough to go on, let me know and I can take a look. Not sure if you want to dig into the macros. :)
Comment #3
drummFrom a security perspective, it would be best to separate these out into another field when imported to Drupal.org. Then we can keep embed tags out of the text format used on documentation guide pages.
While we have committers for this project to review, it would be ideal to have something that is useful and safe for all documentation.
We don’t have any sort of media stack on Drupal.org right now. I think ideally we would have something that is a straightforward field formatter that does whatever validation is possible, and outputs a standardized HTML fragment, such as using consistent size and configuration.
Comment #4
eojthebraveHmm. Okay. I can see why this could be a security issue. And why it might also be nice to be able to embed videos into other non-user guide documentation pages. Are there any plans to include a media stack on Drupal.org? Going this route sounds like it could pretty quickly turn into a whole lot of work. Especially if it's not something planned already. Though, I'm not necessarily opposed.
If we do go that route we would need to also:
- Adjust the user guide import code to extract the video(s) from a topic and insert the value into the field
- Also potentially come up with a scenario that allows for videos from a field to be embedded/inserted into the body content of a node if want to allow users to choose where in the page the video appears
Another alternative, that might be less work, would be to use some kind of text format + custom token. For example
[youtube:https://www.youtube.com/watch?v=35e16QDFE7k]could be extracted from the text and replaced with a proper embed code alleviating the security risk of allowing something like embed, or iframe in the HTML format. Though I think this might end up being harder to support multiple different video hosting platforms if that's a concern.I'm willing to do what I can to help with either solution. But I'm not really sure what the best path forward is going to be.
Comment #5
jhodgdonHm. As we found on #2923453: Guidelines for adding videos to the User Guide, the video tag already works on drupal.org ... but you must have permission to use a full HTML text format.
Is it possible that we could go with this as it is now, but later on, once drupal.org has another way to support video embeds on documentation pages, support that?
If not, another option would be that we could modify the macro so that instead of doing a video embed, it just puts in a link to the video (which is what will happen in the PDF anyway).
Thoughts?
Comment #6
eojthebraveI don't know if it makes much difference or not. But just a heads up, that in the example in #2923453: Guidelines for adding videos to the User Guide we used an
iframe, and not anembedtag. Which, might potentially limit the hosting providers that someone could use to host there videos. Though, I think most do iframes these days as their default method for embedding.e.g.:
<iframe width="560" height="315" src="https://www.youtube.com/embed/HymQsDOcT3E" frameborder="0" allowfullscreen></iframe>I would be fine with this as a solution though. I think we can adjust things to accommodate others who want to add videos to the guide as different requirements arise. And I don't really anticipate their being a whole lot of demand to do so.
I realize this doesn't really solve the problem generically for the rest of Drupal.org though.
Comment #7
jhodgdonWe can definitely adjust the scripts to use whatever tags are preferred, in the User Guide. And if d.o comes to have a video field, we can adjust the import/feeds scripts so that the video section is detected and the embed URL is put into that field.
The question is, can we do something now, so we can get this very valuable video content into the User Guide.
I think we have 3 options on how to do it:
a) Add video field to d.o and do some work on the feeds/import module and the build scripts so that the videos are put there. This will take considerable time and back-and-forth I think?
b) Use the scripts and guidelines we developed on #2923453: Guidelines for adding videos to the User Guide, possibly with a small modification to change the tag we use to embed the video in the HTML output that we then import into drupal.org. [Which tag does the DA prefer?]
c) Change the scripts so that instead of embedding the videos in the HTML output of the User Guide, we instead link to YouTube (which is what will happen in the PDF output anyway). This is basically what we have been doing in the past with documentation pages on drupal.org -- see
https://www.drupal.org/videocasts and its associated guidelines page https://www.drupal.org/node/62196
I believe that (b) is of the most value to readers/viewers of the User Guide. But if the DA objects to it, we can do (c) instead. And then we can plan to do (a) in the future in either case (when/if the DA decides how to handle videos for d.o in general). That's my perspective... thoughts?
Comment #8
joachim namysloThink about others think ahead
Drupalize.me's example video has great quality. They know a lot about doing Videos but also a lot about narration in terms of tempo accurateness and so on. May be we should discuss how to help translators from other languages how to do videos for the user guide as well and make sure to achieve great quality. Guess this is a topic for a separate issue. Even with a great microphone Adobe audition and some knowledge how to do this there is some space to do mistakes.
Comment #9
jhodgdonWe discussed how to add videos and how to translate them on the related issue #2923453: Guidelines for adding videos to the User Guide
Comment #10
eojthebraveRelated to comment #8, FWIW we have slide decks, and written scripts for each of the videos that we recorded which I think we would be willing to share in order to help people if they wanted to re-record the videos in another language.
And, like Jennifer said, there are instructions for adding translated captions to the videos already included. And, while not the same as translated audio, it's likely a lot easier to achieve.
Comment #11
jhodgdonSooooo... Can we move forward on this now, with the caveat that if drupal.org has a better way to do it in the future, we will modify the import scripts at that time? See comment #5 and #7.
Comment #12
jhodgdonComment #13
eojthebraveI talked with @drumm about this a bit at DrupalCon last week. And I believe the consensus was that for now we should move forward with the suggestion in #5. He also mentioned that we should take a look at the various parameters for YouTube embeds and turn off some of the features like automatic recommendations for "next up", and autoplay, etc.
Long term they would still like to have better video/media management for pages, but we agreed that it's probably not worth holding up this issue for that feature to be completed.
Neil please feel free to chime in if I'm misrepresenting anything.
Comment #14
jhodgdonGreat news! So, the next step is to investigate parameters for embeds, and YouTube in particular, and then once we've figured out what those are, get them into this patch?
Comment #15
eojthebraveYeah. I think we need up update the asciidoc config so that it outputs an iframe instead of an embed tag. And use the following params:
- autoplay=0, ensures videos don't autoplay on page load
- rel=0, turns off the related videos listed at the end
- modestbranding=1, optional, but uses a more modest branding on the player
You can also use
https://www.youtube-nocookie.comas the URL - Which ensures that YouTube won't store information about visitors on the page unless they click play on a video.Comment #16
jhodgdonOK. So, I think the macros and instructions we added on #2923453: Guidelines for adding videos to the User Guide do not need to be changed. Those make it so that if we put video:: things into our AsciiDoc source, the DocBook output gets videoobject tags added to it, which we still want.
What we need to add is an override to how DocBook is getting translated to HTML, so that instead of the default (embed tag), we output an iframe instead. Since the videoobject tag doesn't have attributes for autoplay and the other stuff, we'll just have to hard-wire it. I'll play around with this today or in the next few days, on my local site, and see what I can come up with. It shouldn't be too hard, I've overridden quite a bit of the HTML output already. And don't worry, this comment is just a reminder for me of what I need to do, not particularly for anyone else to get into. :)
Comment #17
jhodgdonOK, here's a new patch. Changes:
- Added/modified scripts a bit so that they output an iframe as in comment #15 instead of an embed tag, for the plain HTML and feeds HTML output. I hard-wired the width/height and other attributes, as well as the suffix to the URLs with the ?etc. parameters. It seems to work fine.
- Edited the README-VIDEOS.txt file slightly: word-wrapped to 80 character lines, and fixed a couple of typos.
I didn't make an interdiff because every line in the README changed (due to the word wrapping)...
I think that README file needs one thing added to it: it says that you can use a tool of your choice to translate the videos if you don't want to use dotsub. But it doesn't seem to say how to send the SRT format to drupalize.me so it can be imported -- maybe that is done on dotsub but it wasn't clear to me from reading the README or the drupalize.me blog post. Adding a quick line with that information would be great.
Other than that, I think this is ready to go -- want to add a line to the README?
Comment #18
jhodgdonHere's another patch... I've edited the patch to use the nocookie URL. I've also edited the formatting.txt file in Guidelines to mention this URL, and the interdiff is just the diff for this edit.
Also, I noticed in guidelines-writing, we said the README for videos should go in the source directory, so I'm moving it there in this patch.
Comment #19
jhodgdonHere's an example of the iframe this is now producing for output, from the Installing a Module topic. First I'll paste it in a code tag so it can be viewed easily, and then bare so we can verify it works fine on drupal.org (hopefully). Note: had to change the text format on the comment to full HTML so the iframe would work (hopefully).
Comment #20
eojthebraveHere's updated text for the README.
Comment #21
jhodgdonNeeds a ; in
You may also use a tool of your choice for translating the captions as long as
-they can be exported and provided to us SRT format we can incorporate them.
+they can be exported and provided to us in SRT format we can incorporate them.
I put that in and will mark this RTBC. @drumm, any comments?
Comment #22
jhodgdonComment #23
jhodgdonWhoops. The patches in #20 and #21 are missing the changes in guidelines and scripts directories. Here is a new patch that is just like #21 except also including 4 files that were in the patch in #18 that went missing from #21.
Comment #24
drummLooks okay to me. I’d definitely like to solve this for documentation pages in general, including those edited on www.drupal.org, but don’t need to scope creep into that for this issue.
Comment #25
jhodgdonGreat! I'll go ahead and commit this and email the translation list.
My thought is that we can hopefully fix a couple more content issues and then make an 8.x-5.0 release, and get all this new stuff imported to drupal.org.
Comment #27
eojthebraveYay!