docs: make jsdoc generate anchor names so ToC links work #4471
Conversation
Can't fix subsequent children and nativeControlsForTouch in options tutorial.
| @@ -35,6 +35,7 @@ | |||
| }, | |||
| "plugins": ["plugins/markdown"], | |||
| "markdown": { | |||
| "tags": ["example"] | |||
| "tags": ["example"], | |||
| "idInHeadings": true | |||
There was a problem hiding this comment.
The way that marked/jsdoc add anchor links isn't quite compatible with GFM, so, it warranted the changes in fix-api-docs.js below.
| {find: /(\<h[1-6] id="(?:.*)?)video-js(.*)?"\>/g, replace: '$1videojs$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)don-t(.*)?"\>/g, replace: '$1dont$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)node-js(.*)?"\>/g, replace: '$1nodejs$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)vtt-js(.*)?"\>/g, replace: '$1vttjs$2">'}, |
There was a problem hiding this comment.
headings with a period get a dash in jsdoc but not in GFM
There was a problem hiding this comment.
I probably should move some of these comments directly into the code.
There was a problem hiding this comment.
I don't think this needs changes, but I feel obliged to post this... https://stackoverflow.com/a/1732454
| {find: /(\<h[1-6] id="(?:.*)?)node-js(.*)?"\>/g, replace: '$1nodejs$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)vtt-js(.*)?"\>/g, replace: '$1vttjs$2">'}, | ||
| {find: /(\<h[1-6] id=")-(.*)("\>)/g, replace: '$1$2$3'}, | ||
| {find: /(\<h[1-6] id=")(.*)-("\>)/g, replace: '$1$2$3'}, |
There was a problem hiding this comment.
headings with backticks get a dash in there. Need two rules to get those that start and end with them.
| {find: /(\<h[1-6] id="(?:.*)?)vtt-js(.*)?"\>/g, replace: '$1vttjs$2">'}, | ||
| {find: /(\<h[1-6] id=")-(.*)("\>)/g, replace: '$1$2$3'}, | ||
| {find: /(\<h[1-6] id=")(.*)-("\>)/g, replace: '$1$2$3'}, | ||
| {find: /(\<h[1-6] id=".*)-docs-guides-.*-md("\>)/g, replace: '$1$2'}, |
There was a problem hiding this comment.
In the main page, a lot of headings are linked and jsdoc adds the link pieces into the heading but not GFM.
| {find: '<h4 id="i-want-to-have-a-single-source-and-dont-care-about-live-adaptive-streaming">', | ||
| replace: '<h4 id="i-want-to-have-a-single-source-and-dont-care-about-liveadaptive-streaming">'}, | ||
| {find: '<h2 id="api-docs-api">', replace: '<h2 id="api-docs">'}, | ||
| {find: '<h2 id="guides-docs-guides">', replace: '<h2 id="guides">'} |
There was a problem hiding this comment.
various specific changes that are hard to target programmatically and are just changed directly.
There was a problem hiding this comment.
I guess my only question with this section is whether it would make more sense to parse the HTML into a DOM and loop through all the heads, looking at their id attributes? It might be less error/typo-prone than this approach.
There was a problem hiding this comment.
Probably best option would be to make a PR to jsdoc to expose the marker renderer so we can override the headings portion to our likings. For example, we're still missing a chain icon thing near each heading to click to be taken to that section.
| {find: /(\<h[1-6] id="(?:.*)?)video-js(.*)?"\>/g, replace: '$1videojs$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)don-t(.*)?"\>/g, replace: '$1dont$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)node-js(.*)?"\>/g, replace: '$1nodejs$2">'}, | ||
| {find: /(\<h[1-6] id="(?:.*)?)vtt-js(.*)?"\>/g, replace: '$1vttjs$2">'}, |
There was a problem hiding this comment.
I don't think this needs changes, but I feel obliged to post this... https://stackoverflow.com/a/1732454
| {find: '<h4 id="i-want-to-have-a-single-source-and-dont-care-about-live-adaptive-streaming">', | ||
| replace: '<h4 id="i-want-to-have-a-single-source-and-dont-care-about-liveadaptive-streaming">'}, | ||
| {find: '<h2 id="api-docs-api">', replace: '<h2 id="api-docs">'}, | ||
| {find: '<h2 id="guides-docs-guides">', replace: '<h2 id="guides">'} |
There was a problem hiding this comment.
I guess my only question with this section is whether it would make more sense to parse the HTML into a DOM and loop through all the heads, looking at their id attributes? It might be less error/typo-prone than this approach.
No description provided.