doc: anchor link parity between markdown and html-generated docs #39304

foxxyz · 2021-07-08T06:52:42Z

Inspired by @aduh95's comments on #39164.

Honestly, this is probably a long shot due to the amount of changes, but I think the benefits are substantial - so here goes.

Main Changes

Replace current HTML anchor generation to match header anchor generation in Github markdown
Remove unnecessary double namespacing on generated anchors/links (E.G. esm.md#loaders instead of esm.md#esm_loaders)
Anchors/links are automatically prefixed with their respective modules when concatenated for usage in all.html

Benefits

All anchor links within and between markdown API docs actually work (try it out here)
Adding new anchor links no longer requires contributors to generate the HTML docs first to look up the correct anchors
Anchors are much shorter
Simpler anchor generation
All previous anchor links are preserved by generating hidden legacy anchors.

Linting (make lint-md) and doc generation (make doc-only) should have verified all new links are correct, so hopefully that saves you from needing to double-check 95% of changes in this PR. The most important changes are to files in tools/doc.

I realize this will mean tons of rebasing if this PR stays open, but I don't mind doing it if there's a chance links in the markdown docs might actually work at some point.

Other issues that discuss this: #35189 (specific comment)

aduh95

Thanks a lot for putting the effort into this, that's good work! I am a bit concerned regarding breaking existing links, but maybe the upside is worth the potential breaking. Maybe we could add something similar to what we did at https://nodejs.org/docs/latest/api/modules.html#modules_module_builtinmodules?

Alternatively, have you looked into https://www.markdownguide.org/extended-syntax/#heading-ids as an alternative? If GitHub web UI supports those, that would let us keep our existing links for the same benefit – the downside would be to have to add those heading-ids in our .md files.

tools/doc/allhtml.mjs

foxxyz · 2021-07-09T05:31:24Z

Alternatively, have you looked into https://www.markdownguide.org/extended-syntax/#heading-ids as an alternative? If GitHub web UI supports those, that would let us keep our existing links for the same benefit – the downside would be to have to add those heading-ids in our .md files.

That was the first thing I tried :) Unfortunately it's not supported in the Github markdown renderer, it just renders it next to the heading.

I am a bit concerned regarding breaking existing links, but maybe the upside is worth the potential breaking. Maybe we could add something similar to what we did at https://nodejs.org/docs/latest/api/modules.html#modules_module_builtinmodules?

I think I have a solution: 24df945 adds alias anchors to each heading that reflect the old ID scheme, while keeping the markdown uncluttered. I think that should preserve all incoming links! Let me know if you think the HTML should be different.

tools/doc/html.mjs

tools/doc/allhtml.mjs

aduh95 · 2021-07-21T07:43:38Z

@nodejs/documentation wdyt?
Also, @nodejs/lts this could impact backporting doc changes.

foxxyz · 2021-08-04T03:49:48Z

@aduh95 @jasnell anything I can do to increase chances of feedback and/or adoption?

aduh95 · 2021-08-04T08:33:03Z

I've added the tsc-agenda label to get more feedback and to discuss when would be the best time to land this.

Main changes: - Replace current HTML anchor generation to match header anchor generation in Github markdown. - Remove unnecessary double namespacing on generated anchors/links (E.G. `esm.md#loaders` instead of `esm.md#esm_loaders`). - Anchors/links are automatically prefixed with their respective modules when concatenated for usage in `all.html`. Benefits: - All anchor links within and between markdown API docs actually work. - Adding new anchor links no longer requires contributors to generate the HTML docs first to look up the correct anchors. - Anchors are much shorter. - All previous anchor links are preserved by generating hidden legacy anchors. PR-URL: #39304 Reviewed-By: Antoine du Hamel <[email protected]>

aduh95 · 2021-08-29T22:40:59Z

Landed in 6fdd582.

aduh95 · 2021-08-29T22:43:23Z

Thanks again for your hard work on this. Would you like to open a backport PR for v14.x? The commands to achieve that would be:

git fetch upstream master
git fetch upstream v14.x-staging
git reset upstream/v14.x-staging --hard
git cherry-pick 6fdd5827f0956ffc4e7ffe31babaf530e42f75b9

foxxyz · 2021-08-30T01:09:14Z

Awesome!

Thanks again for your hard work on this. Would you like to open a backport PR for v14.x?

I'd love to.

targos · 2021-08-30T04:58:36Z

Please don't backport yet. It would introduce massive conflicts with commits that haven't landed yet on v14.x

foxxyz · 2021-08-30T14:44:30Z

I expect there to be some big conflicts - I don't mind working through them - but happy to wait for your go-ahead before submitting the backport PR, @targos. Let me know.

foxxyz · 2021-09-26T02:25:39Z

@targos any change? is there still a desire to have this backported?

Main changes: - Replace current HTML anchor generation to match header anchor generation in Github markdown. - Remove unnecessary double namespacing on generated anchors/links (E.G. `esm.md#loaders` instead of `esm.md#esm_loaders`). - Anchors/links are automatically prefixed with their respective modules when concatenated for usage in `all.html`. Benefits: - All anchor links within and between markdown API docs actually work. - Adding new anchor links no longer requires contributors to generate the HTML docs first to look up the correct anchors. - Anchors are much shorter. - All previous anchor links are preserved by generating hidden legacy anchors. PR-URL: #39304 Reviewed-By: Antoine du Hamel <[email protected]>

targos · 2021-10-09T07:54:56Z

There were little conflicts on v16.x-staging and I fixed them. Pushed at d3f3111

targos · 2021-10-09T07:59:27Z

About v14.x, I would be happy to review a backport pull request, but the branch is going into maintenance in less than two weeks, so maybe it's not worth the work.

Main changes: - Replace current HTML anchor generation to match header anchor generation in Github markdown. - Remove unnecessary double namespacing on generated anchors/links (E.G. `esm.md#loaders` instead of `esm.md#esm_loaders`). - Anchors/links are automatically prefixed with their respective modules when concatenated for usage in `all.html`. Benefits: - All anchor links within and between markdown API docs actually work. - Adding new anchor links no longer requires contributors to generate the HTML docs first to look up the correct anchors. - Anchors are much shorter. - All previous anchor links are preserved by generating hidden legacy anchors. PR-URL: #39304 Reviewed-By: Antoine du Hamel <[email protected]>

Main changes: - Replace current HTML anchor generation to match header anchor generation in Github markdown. - Remove unnecessary double namespacing on generated anchors/links (E.G. `esm.md#loaders` instead of `esm.md#esm_loaders`). - Anchors/links are automatically prefixed with their respective modules when concatenated for usage in `all.html`. Benefits: - All anchor links within and between markdown API docs actually work. - Adding new anchor links no longer requires contributors to generate the HTML docs first to look up the correct anchors. - Anchors are much shorter. - All previous anchor links are preserved by generating hidden legacy anchors. PR-URL: nodejs#39304 Reviewed-By: Antoine du Hamel <[email protected]>

foxxyz · 2021-10-18T04:48:04Z

About v14.x, I would be happy to review a backport pull request, but the branch is going into maintenance in less than two weeks, so maybe it's not worth the work.

Thank you for merging into 16.x, hope it wasn't too cumbersome! 🙌🏽

I've submitted a PR for the backport at #40495 , hopefully I'm not too late.

github-actions bot added the doc Issues and PRs related to the documentations. label Jul 8, 2021

This comment has been minimized.

Sign in to view

aduh95 reviewed Jul 8, 2021

View reviewed changes

tools/doc/allhtml.mjs Outdated Show resolved Hide resolved

tools/doc/allhtml.mjs Outdated Show resolved Hide resolved

foxxyz force-pushed the consistent-doc-anchors branch from 24df945 to 6d3f460 Compare July 9, 2021 05:39

aduh95 reviewed Jul 9, 2021

View reviewed changes

tools/doc/html.mjs Outdated Show resolved Hide resolved

jasnell reviewed Jul 9, 2021

View reviewed changes

tools/doc/allhtml.mjs Show resolved Hide resolved

foxxyz force-pushed the consistent-doc-anchors branch 2 times, most recently from f58ccf2 to 50b726f Compare July 13, 2021 06:05

aduh95 reviewed Jul 13, 2021

View reviewed changes

tools/doc/allhtml.mjs Outdated Show resolved Hide resolved

tools/doc/allhtml.mjs Outdated Show resolved Hide resolved

foxxyz force-pushed the consistent-doc-anchors branch 5 times, most recently from af39af5 to f39d7b7 Compare July 20, 2021 06:32

foxxyz requested review from jasnell and aduh95 July 20, 2021 06:32

aduh95 reviewed Jul 20, 2021

View reviewed changes

tools/doc/allhtml.mjs Outdated Show resolved Hide resolved

foxxyz force-pushed the consistent-doc-anchors branch from 125c287 to 301ff47 Compare July 21, 2021 04:54

aduh95 reviewed Jul 21, 2021

View reviewed changes

tools/doc/allhtml.mjs Outdated Show resolved Hide resolved

foxxyz force-pushed the consistent-doc-anchors branch 3 times, most recently from 848b7e5 to b300764 Compare July 27, 2021 05:21

foxxyz force-pushed the consistent-doc-anchors branch from b300764 to 849213e Compare July 31, 2021 05:27

aduh95 added the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label Aug 4, 2021

foxxyz force-pushed the consistent-doc-anchors branch from 849213e to a15f6a2 Compare August 7, 2021 18:26

mhdawson mentioned this pull request Aug 9, 2021

Node.js Technical Steering Committee (TSC) Meeting 2021-08-12 nodejs/TSC#1070

Closed

aduh95 added backport-requested-v14.x author ready PRs that have at least one approval, no pending requests for changes, and a CI started. and removed backport-blocked-v14.x labels Aug 29, 2021

aduh95 closed this Aug 29, 2021

foxxyz deleted the consistent-doc-anchors branch August 30, 2021 01:16

targos added backport-blocked-v14.x labels Aug 30, 2021

targos removed the backport-blocked-v16.x label Oct 9, 2021

This was referenced Oct 9, 2021

esm: consolidate ESM Loader methods #37468

Closed

[v16.x-backport] doc: deprecate (doc-only) .aborted property and 'abort', 'aborted' event in http #40321

Closed

BethGriggs mentioned this pull request Oct 14, 2021

2021-10-19, Version 17.0.0 (Current) #40119

Merged

2 tasks

foxxyz mentioned this pull request Oct 18, 2021

[v14.x-backport] doc: anchor link parity between markdown and html-generated docs #40495

Closed

richardlau mentioned this pull request Oct 18, 2021

v16.12.0 proposal #40504

Merged

aduh95 mentioned this pull request Dec 23, 2021

tools,doc: avoid generating duplicate id attributes #41291

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: anchor link parity between markdown and html-generated docs #39304

doc: anchor link parity between markdown and html-generated docs #39304

foxxyz commented Jul 8, 2021 •

edited

Loading

This comment has been minimized.

aduh95 left a comment

foxxyz commented Jul 9, 2021

aduh95 commented Jul 21, 2021

foxxyz commented Aug 4, 2021

aduh95 commented Aug 4, 2021

aduh95 commented Aug 29, 2021

aduh95 commented Aug 29, 2021

foxxyz commented Aug 30, 2021

targos commented Aug 30, 2021

foxxyz commented Aug 30, 2021

foxxyz commented Sep 26, 2021

targos commented Oct 9, 2021

targos commented Oct 9, 2021

foxxyz commented Oct 18, 2021 •

edited

Loading

doc: anchor link parity between markdown and html-generated docs #39304

doc: anchor link parity between markdown and html-generated docs #39304

Conversation

foxxyz commented Jul 8, 2021 • edited Loading

Main Changes

Benefits

This comment has been minimized.

aduh95 left a comment

Choose a reason for hiding this comment

foxxyz commented Jul 9, 2021

aduh95 commented Jul 21, 2021

foxxyz commented Aug 4, 2021

aduh95 commented Aug 4, 2021

aduh95 commented Aug 29, 2021

aduh95 commented Aug 29, 2021

foxxyz commented Aug 30, 2021

targos commented Aug 30, 2021

foxxyz commented Aug 30, 2021

foxxyz commented Sep 26, 2021

targos commented Oct 9, 2021

targos commented Oct 9, 2021

foxxyz commented Oct 18, 2021 • edited Loading

foxxyz commented Jul 8, 2021 •

edited

Loading

foxxyz commented Oct 18, 2021 •

edited

Loading