docs(fixup): fixup docs (#5489)

videojs · Oct 10, 2018 · 794cd71 · 794cd71
1 parent 29c8259
commit 794cd71
Show file tree

Hide file tree

Showing 17 changed files with 148 additions and 109 deletions.
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
@@ -15,10 +15,16 @@
       * [I accidentally committed a broken change to master](#i-accidentally-committed-a-broken-change-to-master)
 * [video.js releases](#videojs-releases)
   * [Getting dependencies](#getting-dependencies)
-    * [Install contrib](#install-contrib)
     * [npm access](#npm-access)
     * [GitHub personal access token](#github-personal-access-token)
+  * [Deciding what type of version release](#deciding-what-type-of-version-release)
   * [Doing a release](#doing-a-release)
+    * [Video.js 6](#videojs-6)
+    * [Video.js 5](#videojs-5)
+      * [Edit git-semver-tags](#edit-git-semver-tags)
+    * [And now for the release](#and-now-for-the-release)
+  * [Deploy as a patch to the CDN](#deploy-as-a-patch-to-the-cdn)
+  * [Announcement](#announcement)
 * [Doc credit](#doc-credit)
 
 ## Issues and Pull Requests
@@ -35,18 +41,17 @@ If issues or PRs are very short and don't contain much information, ask for more
 
 There are labels that are useful to include on issues and PRs. A few of them are defined below:
 
-| Label | Issue or PR | Description |
-|-------|-------------|-------------|
-| confirmed | Issue and PR | Issue: marks as reproducible. PR: marks as ready to be merged|
-| 5.x | PR | Marks as a change to the 5.x branch only |
-| bug | Issue | Marks as a confirmed bug |
-| good first issue | Issue | Marks as a good bug or enhancement for first time contributors to Video.js |
-| first-timers-only | Issue | Marks as a good bug or enhancement to be done by a newcomer to open source |
-| minor, patch, major | PR | Marks PR with the expected semver classification of the change |
-| needs: LGTM | PR | Marks PR to be reviewed by a collaborator |
-| needs: more info | Issue | Marks as needing more information from the issue reporter |
-| needs: reduced test case | Issue | Marks as needing a reduced test case from the issue reporter |
-
+| Label                    | Issue or PR  | Description                                                                |
+| ------------------------ | ------------ | -------------------------------------------------------------------------- |
+| confirmed                | Issue and PR | Issue: marks as reproducible. PR: marks as ready to be merged              |
+| 5.x                      | PR           | Marks as a change to the 5.x branch only                                   |
+| bug                      | Issue        | Marks as a confirmed bug                                                   |
+| good first issue         | Issue        | Marks as a good bug or enhancement for first time contributors to Video.js |
+| first-timers-only        | Issue        | Marks as a good bug or enhancement to be done by a newcomer to open source |
+| minor, patch, major      | PR           | Marks PR with the expected semver classification of the change             |
+| needs: LGTM              | PR           | Marks PR to be reviewed by a collaborator                                  |
+| needs: more info         | Issue        | Marks as needing more information from the issue reporter                  |
+| needs: reduced test case | Issue        | Marks as needing a reduced test case from the issue reporter               |
 
 ## Accepting changes
 
@@ -382,12 +387,14 @@ git checkout 5.x
 git pull origin 5.x
 ```
 
-> *Note:* you probably need to delete v6 tags due to the way that the our CHANGELOG lib works.
+> _Note:_ you probably need to delete v6 tags due to the way that the our CHANGELOG lib works.
 >
 > You can run this to delete them:
+>
 > ```sh
 > git tag | grep '^v6' | xargs git tag -d
 > ```
+>
 > This will find all tags that start with `^v6` and delete them.
 
 At this point, you should run `npm install` because dependencies may have changed.
@@ -398,6 +405,7 @@ Then, we have a script that automates most of the steps for publishing. It's a l
 
 You'll need to edit `git-semver-tags` to support our usage of tags that are not part of the branch.
 In the file `node_modules/conventional-changelog-cli/node_modules/conventional-changelog/node_modules/conventional-changelog-core/node_modules/git-semver-tags/index.js`, edit the line that says sets the `cmd` to be:
+
 ```js
 var cmd = 'git log --all --date-order --decorate --no-color';
 ```
@@ -432,7 +440,7 @@ and then pasted into the correct [GitHub release](https://github.com/videojs/vid
 
 ### Deploy as a patch to the CDN
 
-Follow the steps on the [CDN repo][] for the CDN release process.
+Follow the steps on the [CDN repo][cdn repo] for the CDN release process.
 If it's a `next` or `next-5` release, only publish the patch version to the CDN.
 
 When the version gets promoted to `latest` or `latest-5`, the corresponding `minor` or `latest` version should be published to the CDN.
@@ -461,6 +469,6 @@ This collaborator guide was heavily inspired by [node.js's guide](https://github
 
 [slack]: http://slack.videojs.com
 
-[CDN repo]: https://github.com/videojs/cdn
+[cdn repo]: https://github.com/videojs/cdn
 
 [raw chg]: https://raw.githubusercontent.com/videojs/video.js/5.x/CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -79,16 +79,16 @@ A good bug report should be as detailed as possible, so that others won't have t
 
 There are a few labels that might be added to your issue or PR by a maintainer. Here's a quick rundown of what they mean:
 
-| Label | Issue or PR | Description |
-|-------|-------------|-------------|
-| confirmed | Issue and PR | Issue: marks as reproducible by a maintainer. PR: marked by a maintainer as ready to be merged|
-| 5.x | PR | Marks as a change to the 5.x branch only |
-| bug | Issue | Marks as a confirmed bug by a maintainer |
-| good first issue | Issue | Marked as a good bug or enhancement for first time contributors to Video.js |
-| first-timers-only | Issue | Marked as a good bug or enhancement to be done by a newcomer to open source |
-| minor, patch, major | PR | Marks PR with the expected [semver](https://semver.org/) classification of the change |
-| needs: more info | Issue | Marked by a maintainer as needing more information from the issue reporter. Please update your issue with more information to help us reproduce the bug. |
-| needs: reduced test case | Issue | Marked by a maintainer as needing a reduced test case from the issue reporter. Please create a test page that we can inspect to help us indentify a bug. |
+| Label                    | Issue or PR  | Description                                                                                                                                              |
+| ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| confirmed                | Issue and PR | Issue: marks as reproducible by a maintainer. PR: marked by a maintainer as ready to be merged                                                           |
+| 5.x                      | PR           | Marks as a change to the 5.x branch only                                                                                                                 |
+| bug                      | Issue        | Marks as a confirmed bug by a maintainer                                                                                                                 |
+| good first issue         | Issue        | Marked as a good bug or enhancement for first time contributors to Video.js                                                                              |
+| first-timers-only        | Issue        | Marked as a good bug or enhancement to be done by a newcomer to open source                                                                              |
+| minor, patch, major      | PR           | Marks PR with the expected [semver](https://semver.org/) classification of the change                                                                    |
+| needs: more info         | Issue        | Marked by a maintainer as needing more information from the issue reporter. Please update your issue with more information to help us reproduce the bug. |
+| needs: reduced test case | Issue        | Marked by a maintainer as needing a reduced test case from the issue reporter. Please create a test page that we can inspect to help us indentify a bug. |
 
 ## Contributing code
 

diff --git a/README.md b/README.md
@@ -26,14 +26,17 @@ Thanks to the awesome folks over at [Fastly][fastly], there's a free, CDN hosted
 <link href="//vjs.zencdn.net/7.0/video-js.min.css" rel="stylesheet">
 <script src="//vjs.zencdn.net/7.0/video.min.js"></script>
 ```
-> For the latest version of video.js and URLs to use, check out the [Getting Started][getting-started] page on our website.
 
+> For the latest version of video.js and URLs to use, check out the [Getting Started][getting-started] page on our website.
+>
 > In the `vjs.zencdn.net` CDN-hosted versions of Video.js we include a [stripped down Google Analytics pixel](https://github.com/videojs/cdn/blob/master/src/analytics.js) that tracks a random sampling (currently 1%) of players loaded from the CDN. This allows us to see (roughly) what browsers are in use in the wild, along with other useful metrics such as OS and device. If you'd like to disable analytics, you can simply include the following global before including Video.js via the free CDN:
 >
 > ```html
 > <script>window.HELP_IMPROVE_VIDEOJS = false;</script>
 > ```
-> Alternatively, you can include Video.js by getting it from [npm](http://videojs.com/getting-started/#download-npm), downloading from [GitHub releases](https://github.com/videojs/video.js/releases) or by including it via [unpkg](https://unpkg.com) or another JavaScript CDN like CDNjs. These releases *do not* include Google Analytics tracking at all.
+>
+> Alternatively, you can include Video.js by getting it from [npm](http://videojs.com/getting-started/#download-npm), downloading from [GitHub releases](https://github.com/videojs/video.js/releases) or by including it via [unpkg](https://unpkg.com) or another JavaScript CDN like CDNjs. These releases _do not_ include Google Analytics tracking at all.
+>
 > ```html
 > <!-- unpkg -->
 > <link href="https://unpkg.com/video.js/dist/video-js.css" rel="stylesheet">

diff --git a/docs/guides/embeds.md b/docs/guides/embeds.md
@@ -10,7 +10,9 @@ However, this is kind of weird to have a `<video>` element embed with a `<div>`
 Below, the three kinds of embeds are detailed.
 
 ## Embeds
+
 ### `<video>` embed
+
 The classic Video.js embed. You can then initialize it via `data-setup` or via the `videojs` method.
 
 ```html
@@ -24,11 +26,13 @@ The classic Video.js embed. You can then initialize it via `data-setup` or via t
   <source src="//vjs.zencdn.net/v/oceans.mp4">
 </video>
 ```
+
 ```js
 const player = videojs('vid1', {});
 ```
 
 ### Player div ingest
+
 The enhanced classic embed. You can also initialize it via `data-setup` or via the `videojs` method.
 
 ```html
@@ -46,13 +50,15 @@ The enhanced classic embed. You can also initialize it via `data-setup` or via t
   </video>
 </div>
 ```
+
 ```js
 const player = videojs('vid1', {});
 ```
 
 As you can see, it isn't much different from the classic `<video>` embed. It also does make it easier to work with [React](/docs/guides/react.md).
 
 ### `<video-js>` embed
+
 This is the [I Can't Believe It's Not Custom Elements](https://developers.google.com/web/fundamentals/web-components/customelements) embed code.
 It looks very much like the `<video>` embed but instead of `video` it's a `video-js` embed.
 This is useful for all the things that the player div ingest is useful for and it matches our library name!
@@ -68,15 +74,18 @@ This is useful for all the things that the player div ingest is useful for and i
   <source src="//vjs.zencdn.net/v/oceans.mp4">
 </video-js>
 ```
+
 ```js
 const player = videojs('vid1', {});
 ```
 
 Adding `class="video-js"` with this embed is no longer necessary as it will automatically add the class `video-js` if missing.
 
 #### Custom Elements
+
 Native Custom Elements support is relatively small according to [Can I Use](https://caniuse.com/#feat=custom-elementsv1) and because we didn't want to include a polyfill we're going with just an element called `video-js` rather than a full blown custom element.
 
 ## data-setup
+
 This is an ease-of-use method for having Video.js set up the player automatically. It is an HTML attribute and it takes a JSON string representation of the [player options](/docs/guides/options.md) as the value.
 Using the programmatic approach is probably preferable.
diff --git a/docs/guides/faq.md b/docs/guides/faq.md
@@ -11,18 +11,19 @@
 * [Q: Why does the entire video download before playback? Why does the video load for a long time?](#q-why-does-the-entire-video-download-before-playback-why-does-the-video-load-for-a-long-time)
 * [Q: I see an error thrown that mentions vdata12345. What is that?](#q-i-see-an-error-thrown-that-mentions-vdata12345-what-is-that)
 * [Q: I think I found a bug with Video.js or I want to add a feature. What should I do?](#q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do)
-  * [if you think that you can fix the issue or add the feature](#if-you-think-that-you-can-fix-the-issue-or-add-the-feature)
+  * [If you think that you can fix the issue or add the feature](#if-you-think-that-you-can-fix-the-issue-or-add-the-feature)
   * [If you don't think you can fix the issue or add the feature](#if-you-dont-think-you-can-fix-the-issue-or-add-the-feature)
 * [Q: What is a reduced test case?](#q-what-is-a-reduced-test-case)
 * [Q: What media formats does Video.js support?](#q-what-media-formats-does-videojs-support)
 * [Q: How does Video.js choose which source to use?](#q-how-does-videojs-choose-which-source-to-use)
-* [Q: How to I autoplay the video?](#q-how-to-i-autoplay-the-video)
+* [Q: How do I autoplay a video?](#q-how-do-i-autoplay-a-video)
   * [Q: How can I autoplay a video on a mobile device?](#q-how-can-i-autoplay-a-video-on-a-mobile-device)
 * [Q: How can I play RTMP video in Video.js?](#q-how-can-i-play-rtmp-video-in-videojs)
 * [Q: How can I hide the links to my video/subtitles/audio/tracks?](#q-how-can-i-hide-the-links-to-my-videosubtitlesaudiotracks)
 * [Q: Can I turn off Video.js logging?](#q-can-i-turn-off-videojs-logging)
 * [Q: What is a plugin?](#q-what-is-a-plugin)
 * [Q: How do I make a plugin for Video.js?](#q-how-do-i-make-a-plugin-for-videojs)
+* [Q: How do I add a button to Video.js?](#q-how-do-i-add-a-button-to-videojs)
 * [Q: Where can I find a list of Video.js plugins?](#q-where-can-i-find-a-list-of-videojs-plugins)
 * [Q: How can I get my plugin listed on the website?](#q-how-can-i-get-my-plugin-listed-on-the-website)
 * [Q: Where can I find a list of Video.js skins?](#q-where-can-i-find-a-list-of-videojs-skins)
@@ -31,10 +32,10 @@
 * [Q: Does Video.js support video tracks?](#q-does-videojs-support-video-tracks)
 * [Q: Does Video.js support text tracks (captions, subtitles, etc)?](#q-does-videojs-support-text-tracks-captions-subtitles-etc)
 * [Q: Does Video.js support HLS (HTTP Live streaming) video?](#q-does-videojs-support-hls-http-live-streaming-video)
-* [Q: Does Video.js support MPEG Dash video?](#q-does-videojs-support-mpeg-dash-video)
+* [Q: Does Video.js support MPEG DASH video?](#q-does-videojs-support-mpeg-dash-video)
 * [Q: Does Video.js support live video?](#q-does-videojs-support-live-video)
-* [Q: Can Video.js wrap around YouTube videos?](#q-can-videojs-wrap-around-youtube-videos)
-* [Q: Can Video.js wrap around Vimeo videos?](#q-can-videojs-wrap-around-vimeo-videos)
+* [Q: Can Video.js play YouTube videos?](#q-can-videojs-play-youtube-videos)
+* [Q: Can Video.js play Vimeo videos?](#q-can-videojs-play-vimeo-videos)
 * [Q: Does Video.js support DRM video?](#q-does-videojs-support-drm-video)
 * [Q: Does Video.js have any support for advertisement integrations?](#q-does-videojs-have-any-support-for-advertisement-integrations)
 * [Q: Can Video.js be required in node.js?](#q-can-videojs-be-required-in-nodejs)
@@ -67,7 +68,7 @@ see the [setup guide][install-guide].
 ## Q: Is Video.js on bower?
 
 Versions prior to Video.js 6 support bower, however, as of Video.js 6, bower is no
-longer officially supported. Please see https://github.com/videojs/video.js/issues/4012
+longer officially supported. Please see <https://github.com/videojs/video.js/issues/4012>
 for more information.
 
 ## Q: What do Video.js version numbers mean?
@@ -136,15 +137,14 @@ When an array of sources is available, Video.js test each source in the order gi
 
 ## Q: How do I autoplay a video?
 
-
 Due to recent changes in autoplay behavior we no longer recommend using the `autoplay` attribute
 on the `video` element. It's still supported by Video.js but, many browsers, including Chrome, are changing their
 `autoplay` attribute behavior.
 
 Instead we recommend using the `autoplay` option rather than the `autoplay` attribute, for more information on using that.
 see the [autoplay option][autoplay-option] in the Video.js options guide.
 
-For more information on the autoplay changes see our blog post: https://blog.videojs.com/autoplay-best-practices-with-video-js/
+For more information on the autoplay changes see our blog post: <https://blog.videojs.com/autoplay-best-practices-with-video-js/>
 
 ### Q: How can I autoplay a video on a mobile device?
 
@@ -201,6 +201,7 @@ a plugin existed and was published users could include it on their page to share
 See the [plugin guide][plugin-guide] for information on making a plugin for Video.js.
 
 ## Q: How do I add a button to Video.js?
+
 See the [components guide][components-guide] for an example of adding a button to Video.js.
 
 ## Q: Where can I find a list of Video.js plugins?
@@ -337,7 +338,9 @@ Yes! See [ReactJS integration example][react-guide].
 
 [starter-example]: https://jsbin.com/axedog/edit?html,output
 
-[techorder]: [cors]: /docs/guides/options.md#techorder
+[techorder]: /docs/guides/options.md#techorder
+
+[cors]: /docs/guides/options.md#techorder
 
 [text-tracks]: /docs/guides/text-tracks.md
 

diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
@@ -6,11 +6,18 @@ Hooks exist so that users can globally hook into certain Video.js lifecycle mome
 
 * [Current Hooks](#current-hooks)
   * [beforesetup](#beforesetup)
+    * [Example](#example)
   * [setup](#setup)
+    * [Example](#example-1)
 * [Usage](#usage)
   * [Adding](#adding)
+    * [Example](#example-2)
+  * [Adding Once](#adding-once)
+    * [Example](#example-3)
   * [Getting](#getting)
+    * [Example](#example-4)
   * [Removing](#removing)
+    * [Example](#example-5)
 
 ## Current Hooks
 
@@ -145,7 +152,6 @@ To access the array of functions that currently exists for any hook, use the `vi
 #### Example
 
 ```js
-
 // Get an array of all the 'beforesetup' hooks.
 var beforeSetupHooks = videojs.hooks('beforesetup');
 

diff --git a/docs/guides/languages.md b/docs/guides/languages.md
@@ -13,10 +13,9 @@ Some translations may be less complete than others - see the [translations neede
   * [File Naming](#file-naming)
   * [Updating an Existing Translation](#updating-an-existing-translation)
   * [Writing a New Translation](#writing-a-new-translation)
-* [Advanced Language Usage](#advanced-language-usage)
   * [Adding Languages via the API](#adding-languages-via-the-api)
-  * [Per-Player Languages](#per-player-languages)
-  * [Setting Default Player Language](#setting-default-player-language)
+  * [Per-Player Translations](#per-player-translations)
+  * [Setting Player Language](#setting-player-language)
   * [Determining Player Language](#determining-player-language)
     * [Internal Language Selection](#internal-language-selection)
 * [References](#references)

diff --git a/docs/guides/layout.md b/docs/guides/layout.md
@@ -10,11 +10,11 @@ Enabling fluid mode will disable fill mode. If both are enabled, fluid mode take
 
 You can enable fluid in a few ways:
 
-- Add `vjs-fluid`, `vjs-16-9`, or `vjs-4-3` as a class to the player element.
-- pass `fluid` option to the player.
-- call `player.fluid(true)`.
-- pass `aspectRatio` option to the player.
-- call `player.aspectRatio('16:9')`.
+* Add `vjs-fluid`, `vjs-16-9`, or `vjs-4-3` as a class to the player element.
+* pass `fluid` option to the player.
+* call `player.fluid(true)`.
+* pass `aspectRatio` option to the player.
+* call `player.aspectRatio('16:9')`.
 
 ### Classes
 
@@ -58,7 +58,6 @@ var player = videojs('vid2');
 player.aspectRatio('1:1');
 ```
 
-
 ### Disabling fluid mode
 
 You can disable fluid mode by remove the associated classes or by calling passing in `false` to the method.