docs: Update jsdoc template for better usability on mobile (#8048)

* docs: Update jsdoc template for better use on mobile

* add logo

* add logo css

* redirects should have trailing slash to avoid another redirect

* add and style linnks in header, remove from footer

* update theme to get rid of file list

* improve doc index text

* Add version number in Github link

.gitignore

@@ -2,6 +2,7 @@
 build/files/*
 build/temp/*
 docs/api/*
+docs/apistyles
 dev.html
 projects
 .zenflow-log

.jsdoc.json

@@ -1,41 +1,71 @@
 {
   "source": {
-    "include": [ "src/js/" ],
+    "include": [
+      "src/js/"
+    ],
     "includePattern": ".js$"
   },
   "opts": {
     "destination": "docs/api",
     "readme": "docs/index.md",
-    "template": "node_modules/tui-jsdoc-template",
-    "package": "package.json",
+    "template": "node_modules/clean-jsdoc-theme",
+    "package": "",
     "recurse": true,
-    "tutorials": "docs/guides",
-    "encoding": "utf8"
+    "encoding": "utf8",
+    "theme_opts": {
+      "homepageTitle": "Video.js API docs",
+      "menu": [
+        {
+          "title": "Video.js website",
+          "link": "https://videojs.com",
+          "class": "link-vjs"
+        },
+        {
+          "title": "v8.0.2 source",
+          "link": "https://github.com/videojs/video.js",
+          "class": "link-gh"
+        },
+        {
+          "title": "Twitter",
+          "link": "https://twitter.com/videojs",
+          "class": "link-tw"
+        }
+      ],
+      "favicon": "https://videojs.com/favicon.ico",
+      "footer": "<span class='copyright'><a href='https://videojs.com'>Video.js</a> is a free and open source HTML5 video player. © <a href='https://brightcove.com' target='_blank'>Brightcove, Inc</a>. <a href='https://github.com/videojs/video.js/blob/master/LICENSE' class='button blue' target='_blank'>View license</a></span>",
+      "include_css": [
+        "./build/docs/styles/videojs.css"
+      ],
+      "displayModuleHeader": true,
+      "meta": [
+        {
+          "name": "name",
+          "content": "Video.js API documentation"
+        },
+        {
+          "name": "description",
+          "content": "Generated API documentation for the latest version of Video.js."
+        }
+      ]
+    }
   },
   "templates": {
     "default": {
       "staticFiles": {
-        "include": ["build/docs/"]
+        "include": [
+          "build/docs/"
+        ]
       }
-    },
-    "logo": {
-      "url": "https://videojs.com/logo-white.png",
-      "height": "30px",
-      "width": "214px"
-    },
-    "name": "Video.js Documentation",
-    "tabNames": {
-      "tutorials": "Guides"
-    },
-    "footerText": "<span class='copyright'><a href='https://videojs.com'>Video.js</a> is a free and open source HTML5 video player. © <a href='https://brightcove.com' target='_blank'>Brightcove, Inc</a>. <a href='https://github.com/videojs/video.js/blob/master/LICENSE' class='button blue' target='_blank'>View license</a></span> <ul class='other-links'><li><a href='https://videojs.com' class='button white'><i class='fa fa-external-link'></i> Video.js</a></li> <li><a href='https://twitter.com/videojs' class='button white' target='_blank'><i class='fa fa-twitter'></i> @videojs</a></li> <li><a href='https://github.com/videojs/video.js' class='button white' target='_blank'><i class='fa fa-github-alt'></i> Source</a></li> </ul>",
-    "css": [
-      "styles/videojs.css",
-      "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.css"
-    ]
+    }
   },
-  "plugins": ["plugins/markdown", "build/jsdoc-typeof-plugin"],
+  "plugins": [
+    "plugins/markdown",
+    "build/jsdoc-typeof-plugin"
+  ],
   "markdown": {
-    "tags": ["example"],
+    "tags": [
+      "example"
+    ],
     "idInHeadings": true
   }
-}
+}

build/doc-version.js

@@ -0,0 +1,12 @@
+// Updates the "vX.X.X source" link to github in .jsdoc.json
+// that will be included in the menu of the API docs
+
+const fs = require('fs');
+const jsdocConfig = require('../.jsdoc.json');
+const pkgJson = require('../package.json');
+
+jsdocConfig.opts.theme_opts.menu.find(menuItem => {
+  return menuItem.link === 'https://github.com/videojs/video.js';
+}).title = `v${pkgJson.version} source`;
+
+fs.writeFileSync('.jsdoc.json', JSON.stringify(jsdocConfig, null, 2));

build/docs/styles/videojs.css

@@ -14,16 +14,53 @@ footer .copyright {
   float: left;
 }
 
-footer .other-links {
-  margin: 0;
-  padding: 0;
-  float: right;
+footer .logo {
+  display: none;
 }
 
-footer .other-links li {
-  display: inline;
+.sidebar-title {
+  background: center / contain no-repeat url(https://videojs.com/logo-white.png);
+  text-indent: -999em;
 }
 
-footer .logo {
-  display: none;
+.light .sidebar-title,
+.dark .link-vjs a:before,
+.dark .link-gh a:before,
+.dark .link-tw a:before {
+  -webkit-filter: invert(80%);
+  filter: invert(80%);
+}
+
+.link-vjs a:before,
+.link-gh a:before,
+.link-tw a:before {
+  content: "";
+  display: inline-block;
+  width: 1.5em;
+  height: 1em;
+  position: relative;
+  top: 0.1em;
+}
+
+.link-vjs a:before {
+  background: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 640 512'%3e%3c!--! Font Awesome Free 6.2.1 by %40fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --%3e%3cpath d='M579.8 267.7c56.5-56.5 56.5-148 0-204.5c-50-50-128.8-56.5-186.3-15.4l-1.6 1.1c-14.4 10.3-17.7 30.3-7.4 44.6s30.3 17.7 44.6 7.4l1.6-1.1c32.1-22.9 76-19.3 103.8 8.6c31.5 31.5 31.5 82.5 0 114L422.3 334.8c-31.5 31.5-82.5 31.5-114 0c-27.9-27.9-31.5-71.8-8.6-103.8l1.1-1.6c10.3-14.4 6.9-34.4-7.4-44.6s-34.4-6.9-44.6 7.4l-1.1 1.6C206.5 251.2 213 330 263 380c56.5 56.5 148 56.5 204.5 0L579.8 267.7zM60.2 244.3c-56.5 56.5-56.5 148 0 204.5c50 50 128.8 56.5 186.3 15.4l1.6-1.1c14.4-10.3 17.7-30.3 7.4-44.6s-30.3-17.7-44.6-7.4l-1.6 1.1c-32.1 22.9-76 19.3-103.8-8.6C74 372 74 321 105.5 289.5L217.7 177.2c31.5-31.5 82.5-31.5 114 0c27.9 27.9 31.5 71.8 8.6 103.9l-1.1 1.6c-10.3 14.4-6.9 34.4 7.4 44.6s34.4 6.9 44.6-7.4l1.1-1.6C433.5 260.8 427 182 377 132c-56.5-56.5-148-56.5-204.5 0L60.2 244.3z'/%3e%3c/svg%3e") no-repeat;
 }
+
+.link-gh a:before {
+  background: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 480 512'%3e%3c!--! Font Awesome Free 6.2.1 by %40fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --%3e%3cpath d='M186.1 328.7c0 20.9-10.9 55.1-36.7 55.1s-36.7-34.2-36.7-55.1 10.9-55.1 36.7-55.1 36.7 34.2 36.7 55.1zM480 278.2c0 31.9-3.2 65.7-17.5 95-37.9 76.6-142.1 74.8-216.7 74.8-75.8 0-186.2 2.7-225.6-74.8-14.6-29-20.2-63.1-20.2-95 0-41.9 13.9-81.5 41.5-113.6-5.2-15.8-7.7-32.4-7.7-48.8 0-21.5 4.9-32.3 14.6-51.8 45.3 0 74.3 9 108.8 36 29-6.9 58.8-10 88.7-10 27 0 54.2 2.9 80.4 9.2 34-26.7 63-35.2 107.8-35.2 9.8 19.5 14.6 30.3 14.6 51.8 0 16.4-2.6 32.7-7.7 48.2 27.5 32.4 39 72.3 39 114.2zm-64.3 50.5c0-43.9-26.7-82.6-73.5-82.6-18.9 0-37 3.4-56 6-14.9 2.3-29.8 3.2-45.1 3.2-15.2 0-30.1-.9-45.1-3.2-18.7-2.6-37-6-56-6-46.8 0-73.5 38.7-73.5 82.6 0 87.8 80.4 101.3 150.4 101.3h48.2c70.3 0 150.6-13.4 150.6-101.3zm-82.6-55.1c-25.8 0-36.7 34.2-36.7 55.1s10.9 55.1 36.7 55.1 36.7-34.2 36.7-55.1-10.9-55.1-36.7-55.1z'/%3e%3c/svg%3e") no-repeat;
+}
+
+.link-tw a:before {
+  background: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3e%3c!--! Font Awesome Free 6.2.1 by %40fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --%3e%3cpath d='M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z'/%3e%3c/svg%3e") no-repeat;
+}
+
+.light .navbar {
+  background-color: #f7f7f7;
+  border-radius: 1rem;
+
+}
+
+.dark .navbar {
+  background-color: #222;
+  border-radius: 1rem;
+}

docs/_redirects

@@ -1,27 +1,27 @@
 # Netlify redirects to redirect old tutorial pages to new guide pages
-/tutorial-angular.html            https://videojs.com/guides/angular            301!
-/tutorial-audio-tracks.html       https://videojs.com/guides/audio-tracks       301!
-/tutorial-components.html         https://videojs.com/guides/components         301!
-/tutorial-debugging.html          https://videojs.com/guides/debugging          301!
-/tutorial-embeds.html             https://videojs.com/guides/embeds             301!
-/tutorial-event-target.html       https://videojs.com/guides/event-target       301!
-/tutorial-faq.html                https://videojs.com/guides/faqs               301!
-/tutorial-hooks.html              https://videojs.com/guides/hooks              301!
-/tutorial-languages.html          https://videojs.com/guides/languages          301!
-/tutorial-layout.html             https://videojs.com/guides/layout             301!
-/tutorial-live.html               https://videojs.com/guides/live               301!
-/tutorial-middleware.html         https://videojs.com/guides/middleware         301!
-/tutorial-modal-dialog.html       https://videojs.com/guides/modal-dialog       301!
-/tutorial-options.html            https://videojs.com/guides/options            301!
-/tutorial-player-workflows.html   https://videojs.com/guides/player-workflows   301!
-/tutorial-plugins.html            https://videojs.com/guides/plugins            301!
-/tutorial-react.html              https://videojs.com/guides/react              301!
-/tutorial-setup.html              https://videojs.com/guides/setup              301!
-/tutorial-skins.html              https://videojs.com/guides/skins              301!
-/tutorial-tech.html               https://videojs.com/guides/tech               301!
-/tutorial-text-tracks.html        https://videojs.com/guides/text-tracks        301!
-/tutorial-troubleshooting.html    https://videojs.com/guides/troubleshooting    301!
-/tutorial-video-tracks.html       https://videojs.com/guides/video-tracks       301!
-/tutorial-videojs.html            https://videojs.com/guides/videojs            301!
-/tutorial-vue.html                https://videojs.com/guides/vue                301!
-/tutorial-webpack.html            https://videojs.com/guides/webpack            301!
+/tutorial-angular.html            https://videojs.com/guides/angular/           301!
+/tutorial-audio-tracks.html       https://videojs.com/guides/audio-tracks/      301!
+/tutorial-components.html         https://videojs.com/guides/components/        301!
+/tutorial-debugging.html          https://videojs.com/guides/debugging/         301!
+/tutorial-embeds.html             https://videojs.com/guides/embeds/            301!
+/tutorial-event-target.html       https://videojs.com/guides/event-target/      301!
+/tutorial-faq.html                https://videojs.com/guides/faqs/              301!
+/tutorial-hooks.html              https://videojs.com/guides/hooks/             301!
+/tutorial-languages.html          https://videojs.com/guides/languages/         301!
+/tutorial-layout.html             https://videojs.com/guides/layout/            301!
+/tutorial-live.html               https://videojs.com/guides/live/              301!
+/tutorial-middleware.html         https://videojs.com/guides/middleware/        301!
+/tutorial-modal-dialog.html       https://videojs.com/guides/modal-dialog/      301!
+/tutorial-options.html            https://videojs.com/guides/options/           301!
+/tutorial-player-workflows.html   https://videojs.com/guides/player-workflows/  301!
+/tutorial-plugins.html            https://videojs.com/guides/plugins/           301!
+/tutorial-react.html              https://videojs.com/guides/react/             301!
+/tutorial-setup.html              https://videojs.com/guides/setup/             301!
+/tutorial-skins.html              https://videojs.com/guides/skins/             301!
+/tutorial-tech.html               https://videojs.com/guides/tech/              301!
+/tutorial-text-tracks.html        https://videojs.com/guides/text-tracks/       301!
+/tutorial-troubleshooting.html    https://videojs.com/guides/troubleshooting/   301!
+/tutorial-video-tracks.html       https://videojs.com/guides/video-tracks/      301!
+/tutorial-videojs.html            https://videojs.com/guides/videojs/           301!
+/tutorial-vue.html                https://videojs.com/guides/vue/               301!
+/tutorial-webpack.html            https://videojs.com/guides/webpack/           301!