diff --git a/guidelines/formatting.txt b/guidelines/formatting.txt index 27b970c..224289a 100644 --- a/guidelines/formatting.txt +++ b/guidelines/formatting.txt @@ -184,7 +184,7 @@ See also: <> [[formatting-images]] -==== Including images +==== Including images and videos Here's the syntax to include an image: @@ -233,6 +233,22 @@ translated language, avoid annotations if possible. * See <> for guidelines on what images should be included. +The syntax for embedded videos is similar: + +---- +video:\https://www.youtube.com/embed/X30_HwaxOxk[] +---- + +Notes and guidelines: + +* Make sure you use a URL suitable for video embedding. + +* Note the backslash character before the URL, and brackets after the URL. + +* See <> for guidelines on embedding videos. + + + [[style-literals]] ==== Typography formatting diff --git a/guidelines/guidelines-writing.txt b/guidelines/guidelines-writing.txt index 320276c..a2bbbdf 100644 --- a/guidelines/guidelines-writing.txt +++ b/guidelines/guidelines-writing.txt @@ -21,6 +21,7 @@ On this page: * <> * <> * <> +* <> [[guideline-lists]] @@ -128,6 +129,39 @@ what it stands for (make two entries). Example: `Cross-site scripting See <> or the templates in <> for instructions on how to put index entries into your topic. +[[guideline-additional-info]] +==== Adding links and videos + +There are several sections in both task and concept topics where links to +additional information can be added: + +Prerequisite knowledge:: + Add links in this section to other topics within the same book that cover + knowledge someone would need to understand before reading this topic. +Expand your understanding (task topics):: + Add links in this section to task topics in the same book that would help + solidify or broaden the knowledge covered in this topic. +Related concepts (task topics):: + Add links in this section to concept topics in the same book that are not + prerequisites, but which are somehow related. +Related topics (concept topics):: + Add links to related task and concept topics in the same book that are not + prerequisites. +Videos:: + Embed videos in this section that exactly (or nearly exactly) reproduce the + content of the topic in video format. See <> for syntax. +Additional resources:: + Add links in this section to outside materials related to this topic, which + could include videos, articles, documentation pages, blog posts, and books. + Do not embed videos in this section; instead, provide a link. + +All outside links to resources and videos must conform to the following +guidelines: + +* The page or video linked to must be primarily providing knowledge, not + promotion or advertising. +* The page or video must be freely available, without paying, logging in, or + subscribing to the site. *Attributions* diff --git a/guidelines/templates.txt b/guidelines/templates.txt index 4de0f25..071e494 100644 --- a/guidelines/templates.txt +++ b/guidelines/templates.txt @@ -140,11 +140,20 @@ Remove this placeholder text. Remove this placeholder text. +==== Videos + +// In this section, embed videos that exactly cover this topic. For videos +// that are related but do not exactly cover the topic, add links in the +// Additional resources section instead. + +Remove this placeholder text. + + ==== Additional resources // In this section, make a list of outside references: videos, Drupal.org // documentation, etc. Make sure all links have link text showing the name -// of the article or page it being linked to. +// of the article or page being linked to. Remove this placeholder text. @@ -242,11 +251,20 @@ Remove this placeholder text. Remove this placeholder text. +==== Videos + +// In this section, embed videos that exactly cover this topic. For videos +// that are related but do not exactly cover the topic, add links in the +// Additional resources section instead. + +Remove this placeholder text. + + ==== Additional resources // In this section, make a list of outside references: videos, Drupal.org // documentation, etc. Make sure all links have link text showing the name -// of the article or page it being linked to. +// of the article or page being linked to. Remove this placeholder text. diff --git a/scripts/std.conf b/scripts/std.conf index 338518e..ea30362 100644 --- a/scripts/std.conf +++ b/scripts/std.conf @@ -27,8 +27,21 @@ {alt={target}} +[video-inlinemacro] +# Video macro template, not defined in standard AsciiDoc template. + + + + + {target} + [replacements] # Macro for making links to api.drupal.org. # @todo Write this macro. + +[macros] + +# Add video to commmon macro syntax. +(?su)(?http|https|ftp|file|irc|mailto|callto|image|video|link|anchor|xref|indexterm|indexterm2):(?P\S*?)\[(?P.*?)(?