Doc normalize markdown reference links

[nschonni]

Use explicit trailing [] for reference markdown links.
Escape brackets in titles that get flagged by remark-lint.
Convert old changlogs SHA links to match newer format.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[nschonni]

These urls where incomplete

[nschonni]

Malformed url

[nschonni]

This wasn't matching the reference link because of the extra text

[nschonni]

Only the changes for the "Class" column were flagged by remark-lint. Replaced the <code> for consistency

[nschonni]

These were rendering as links in the heading because of the reference link [encoding]

[nschonni]

@Trott I used the web to resolve the conflicts. Is there a better way to split this to make it easier for reviewers?

[Trott]

@Trott I used the web to resolve the conflicts. Is there a better way to split this to make it easier for reviewers?

I suppose if you want smaller change sets for easier review, you can either do one file per branch/PR or one type of change per branch/PR.

@nodejs/documentation Anyone want to review this as-is? It seems OK to me. I understand why we should escape [ and ] when they're not links. It has the minor disadvantage of making the raw markdown harder to understand. And it's a pretty big change-set (876 lines). But I definitely don't oppose it.

[sam-github]

I don't have a problem with the changes being across multiple files, but I am having trouble figuring out what the specific changes are, and why. I edited the description to add the commit message description in, not sure why github didn't do that itself.

For example, the unescaped [] API docs seems to be processed by our tools into HTML fine, for example, https://nodejs.org/api/tls.html#tls_tls_connect_options_callback doesn't have the raw square brackets escaped in source. So, why would we use more unreadable markup, if it doesn't change the HTML output?

Some of the changes seem to be literally malformed URLs, those could maybe be their own commit, and are obviously a good idea.

The adding of empty [] to make refs be ['some thing()'][] is in same category, if the output HTML is valid, why change the markup?

In general, we know the markup is right when the output is right, so making things "right" with no tool support to maintain that "rightness" is fragile. If we really do require these markup changes, then tool support is needed to enforce them.

It sounds like @nschonni you are relying on some kind of tools opinion about what correct markdown should be, and making the changes it suggests?

[nschonni]

These are flagged by remark-lint when using the "recommended" preset in addition to the current remark-node-preset, which has an upstream PR

[nschonni]

I've broken up the commits a little further to make it easier to review the individual types of changes

[Trott]

@nodejs/collaborators This could use some reviews.

[BridgeAR]

@vsemozhetbyt do you know how much our tooling has to fix currently to get our links to work as expected and would this improve our situation?

@nschonni I think it would be great if this PR could be split into multiple ones. That way they would probably be signed-off much faster. Especially since some parts might be more controversial to some than others. I definitely see the value in most of the change but there are a few which we might not want to change right now.

I think splitting out 3899b8c and f4f7384 would be enough, since those two seem most controversial at the moment and make up a big part of this PR.

[nschonni]

I'm fine with splitting it up, but I'm wondering how that's done here. Close this PR and open new PRs for each commit, or leave the first commit and submit new ones for the others?

[BridgeAR]

@nschonni I would roughly do the following:

# Get the latest upstream code in your fork
git checkout master
git fetch upstream
git pull upstream/master
git push origin
git checkout -b add-explicit-brackets-to-docs
git cherry-pick 3899b8c
git push -u origin add-explicit-brackets-to-docs
git checkout master
git checkout -b escape-brackets-in-docs
git cherry-pick f4f7384
git push -u origin escape-brackets-in-docs
git checkout doc--normalize-markdown-reference-links git rebase -i origin/master
# Here you just remove the two commits that you cherry picked earlier
git push --force-with-lease

[vsemozhetbyt]

@BridgeAR Unfortunately, I've lost the track of our doc tooling system since we transfer it to the unified and remark world and I cannot be of any help here( I am afraid we may have too few collaborators that grasp all the doc tooling system now.

[nschonni]

OK @BridgeAR I've split this out as recommended

[BridgeAR]

@nschonni thanks a lot!

[BridgeAR]

@nschonni are you planning on including the here used rules to our doc linter as well? Without that it will be hard to prevent any of these to be reintroduced.

[nschonni]

They're currently re-ignored in nodejs/remark-preset-lint-node#21, but can be enabled once these land

[Trott]

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3957/

[Trott]

Landed in 344c5c4...420d4e4