doc: use .md extension for internal links #35191

aduh95 · 2020-09-14T15:16:34Z

This helps catch broken links as part of the test suite. This also
improves the user experience when browsing the markdown files.

Fixes: #35189

~~This is currently blocked by #35182.~~

Checklist

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

nodejs-github-bot · 2020-09-14T15:16:39Z

doc/api/crypto.md

doc/api/n-api.md

aduh95 · 2020-09-16T11:59:13Z

Yikes, there are already conflicts… I'll resolve them as soon as I have a moment.

@DerekNonGeneric, would you kindly ping @nodejs/documentation as well? Their input would be valuable given the size of the change.

DerekNonGeneric · 2020-09-16T12:10:37Z

Oh hmm, the bot should have done that. Wish we had that awaiting feedback label that was proposed recently.

/cc @nodejs/documentation

gengjiawen · 2020-09-16T12:58:39Z

@aduh95 You need to rebase.

tools/doc/markdown.js

Trott · 2020-09-16T13:23:16Z

Since my changes caused the conflicts, I resolved them and force-pushed.

Trott · 2020-09-16T13:25:36Z

Oh hmm, the bot should have done that.

If the bot pinged the documentation team on changes to doc files, they'd probably be pinged on around half of the PRs in the repo. (Same for the testing team.) Since the auto-pinging is a new thing, I'm guessing the idea has been to roll it out slowly and not overwhelm large-ish teams with pings.

aduh95 · 2020-09-22T18:34:53Z

Rebased and split into 3 commits because #35224 landed before this one. PTAL

DerekNonGeneric

This looks good overall. I just have a couple of questions.

DerekNonGeneric · 2020-09-26T22:54:57Z

tools/doc/markdown.js

 };

 function replaceLinks({ filename, linksMapper }) {
  return (tree) => {
    const fileHtmlUrls = linksMapper[filename];

+    visit(tree, (node) => {


Can you link to this API's docs?

I have just copied the code below, I haven't used the API docs nor do I know where to find it.

From what I was able to find out, unist-util-visit uses the Universal Syntax Tree.

@wooorm might be able to clue us in on whether there are additional learning resources, but so far this code seems to be fully functional to me. It would be nice to get a better understanding of how this works though.

readme for unist-util-visit(-parents) should have enough info. There are also some recipes on the website of unified.

tools/doc/markdown.js

DerekNonGeneric · 2020-09-26T23:01:33Z

test/doctool/test-local-md-file-reference-regex.js

@@ -0,0 +1,47 @@
+'use strict';


What's the command you ran to make this test run?

make test-doc

node/Makefile

Line 606 in 7390098

$(PYTHON) tools/test.py $(PARALLEL_ARGS) doctool; \

tools/doc/html.js

DerekNonGeneric · 2020-09-26T23:02:54Z

tools/doc/html.js

-const gtocMD = fs.readFileSync(gtocPath, 'utf8').replace(/^<!--.*?-->/gms, '');
+const gtocMD = fs.readFileSync(gtocPath, 'utf8')
+  .replace(/\(([^#?]+?)\.md\)/ig, (_, filename) => `(${filename}.html)`)
+  .replace(/^<!--.*?-->/gms, '');


Do you recall what this replacement was for?

To remove HTML comments it seems. I haven't looked into it though.

tools/doc/markdown.js

DerekNonGeneric · 2020-09-26T23:07:12Z

tools/doc/markdown.js

 };

 function replaceLinks({ filename, linksMapper }) {
  return (tree) => {
    const fileHtmlUrls = linksMapper[filename];

+    visit(tree, (node) => {
+      if (node.url) {


I would like to know what this data structure looks like.

Here's the result of a console.log(node) here:

{ type: 'link', title: null, url: '#cli_diagnostic_dir_directory', children: [ { type: 'text', value: '--diagnostic-dir', position: [Position] } ], position: Position { start: { line: 131, column: 1, offset: 3405 }, end: { line: 131, column: 50, offset: 3454 }, indent: [] } }

aduh95 · 2020-09-29T08:22:25Z

Rebased to solve conflict. If everyone is happy with the current code, I'd like to have it landed before other conflicts arise.

@DerekNonGeneric my understanding is that none of your comments are blocking, is that right?

nodejs-github-bot · 2020-09-30T21:21:38Z

CI: https://ci.nodejs.org/job/node-test-pull-request/33310/

This helps catch broken links as part of the test suite. This also improves the user experience when browsing the markdown files. PR-URL: nodejs#35191 Fixes: nodejs#35189 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Refs: nodejs#35244 PR-URL: nodejs#35191 Fixes: nodejs#35189 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Fixes: nodejs#35189 PR-URL: nodejs#35191 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Trott · 2020-10-01T13:25:50Z

Landed in 726143e...91837e9

This helps catch broken links as part of the test suite. This also improves the user experience when browsing the markdown files. PR-URL: #35191 Fixes: #35189 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Refs: #35244 PR-URL: #35191 Fixes: #35189 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Fixes: #35189 PR-URL: #35191 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

This helps catch broken links as part of the test suite. This also improves the user experience when browsing the markdown files. PR-URL: nodejs#35191 Fixes: nodejs#35189 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Refs: nodejs#35244 PR-URL: nodejs#35191 Fixes: nodejs#35189 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Fixes: nodejs#35189 PR-URL: nodejs#35191 Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Sep 14, 2020

aduh95 mentioned this pull request Sep 14, 2020

doc,tools: checkLinks.js does not cover api #35189

Closed

DerekNonGeneric added the blocked PRs that are blocked by other issues or PRs. label Sep 14, 2020

aduh95 force-pushed the use-md-extension branch from 00dc849 to 53a8ef3 Compare September 14, 2020 16:13

lpinca reviewed Sep 14, 2020

View reviewed changes

doc/api/crypto.md Outdated Show resolved Hide resolved

doc/api/n-api.md Outdated Show resolved Hide resolved

aduh95 force-pushed the use-md-extension branch from 5c545c2 to a9ad531 Compare September 14, 2020 20:36

aduh95 marked this pull request as ready for review September 14, 2020 20:38

aduh95 requested review from a team as code owners September 14, 2020 20:38

aduh95 requested a review from a team September 14, 2020 20:38

DerekNonGeneric added tools Issues and PRs related to the tools directory. author ready PRs that have at least one approval, no pending requests for changes, and a CI started. and removed blocked PRs that are blocked by other issues or PRs. labels Sep 14, 2020

DerekNonGeneric approved these changes Sep 16, 2020

View reviewed changes

DerekNonGeneric requested a review from lpinca September 16, 2020 11:03

DerekNonGeneric requested a review from a team September 16, 2020 12:13

gengjiawen approved these changes Sep 16, 2020

View reviewed changes

DerekNonGeneric reviewed Sep 16, 2020

View reviewed changes

tools/doc/markdown.js Outdated Show resolved Hide resolved

DerekNonGeneric added the pending label Sep 16, 2020

gengjiawen requested a review from richardlau September 16, 2020 13:11

Trott force-pushed the use-md-extension branch from a9ad531 to 8d27d13 Compare September 16, 2020 13:22

trivikr approved these changes Sep 17, 2020

View reviewed changes

aymen94 approved these changes Sep 17, 2020

View reviewed changes

aduh95 force-pushed the use-md-extension branch from 3c37b95 to 0677bbd Compare September 17, 2020 15:17

aduh95 force-pushed the use-md-extension branch from 93ae3d2 to ccbda32 Compare September 22, 2020 18:33

aduh95 force-pushed the use-md-extension branch 2 times, most recently from 45e287d to c8d000b Compare September 26, 2020 12:10

DerekNonGeneric removed the pending label Sep 26, 2020

DerekNonGeneric approved these changes Sep 26, 2020

View reviewed changes

aduh95 force-pushed the use-md-extension branch 2 times, most recently from 6388632 to 844ed1b Compare September 29, 2020 08:15

aduh95 force-pushed the use-md-extension branch from 844ed1b to 4605a10 Compare September 29, 2020 15:57

aduh95 mentioned this pull request Sep 30, 2020

feat: lint YAML comments in md files nodejs/remark-preset-lint-node#139

Merged

Trott approved these changes Sep 30, 2020

View reviewed changes

Trott added the request-ci Add this label to start a Jenkins CI on a PR. label Sep 30, 2020

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Sep 30, 2020

aduh95 mentioned this pull request Sep 30, 2020

Rule for ordering reference links nodejs/remark-preset-lint-node#140

Closed

aduh95 added 3 commits October 1, 2020 06:19

Trott force-pushed the use-md-extension branch from 4605a10 to 91837e9 Compare October 1, 2020 13:25

Trott merged commit 91837e9 into nodejs:master Oct 1, 2020

aduh95 deleted the use-md-extension branch October 1, 2020 13:38

danielleadams mentioned this pull request Oct 6, 2020

V14.13.1 proposal #35525

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: use .md extension for internal links #35191

doc: use .md extension for internal links #35191

aduh95 commented Sep 14, 2020 •

edited by targos

nodejs-github-bot commented Sep 14, 2020

aduh95 commented Sep 16, 2020

DerekNonGeneric commented Sep 16, 2020

gengjiawen commented Sep 16, 2020

Trott commented Sep 16, 2020

Trott commented Sep 16, 2020

aduh95 commented Sep 22, 2020

DerekNonGeneric left a comment

DerekNonGeneric Sep 26, 2020

aduh95 Sep 27, 2020

DerekNonGeneric Sep 28, 2020

wooorm Sep 29, 2020

DerekNonGeneric Sep 26, 2020

aduh95 Sep 27, 2020

DerekNonGeneric Sep 26, 2020

aduh95 Sep 27, 2020

DerekNonGeneric Sep 26, 2020

aduh95 Sep 27, 2020

aduh95 commented Sep 29, 2020

nodejs-github-bot commented Sep 30, 2020

Trott commented Oct 1, 2020

doc: use .md extension for internal links #35191

doc: use .md extension for internal links #35191

Conversation

aduh95 commented Sep 14, 2020 • edited by targos

Checklist

nodejs-github-bot commented Sep 14, 2020

aduh95 commented Sep 16, 2020

DerekNonGeneric commented Sep 16, 2020

gengjiawen commented Sep 16, 2020

Trott commented Sep 16, 2020

Trott commented Sep 16, 2020

aduh95 commented Sep 22, 2020

DerekNonGeneric left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduh95 commented Sep 29, 2020

nodejs-github-bot commented Sep 30, 2020

Trott commented Oct 1, 2020

aduh95 commented Sep 14, 2020 •

edited by targos