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.

richardlau

I'm not exactly sure what needs to change, but I had a quick look at the docs generated by this PR and it looks like the links in the left section now point to the *.md files.

You can get a built copy of the docs from the "misc / build-docs" check from this PR:

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

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

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

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

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

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 approved these changes Sep 16, 2020

View reviewed changes

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

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

richardlau requested changes Sep 17, 2020

View reviewed changes

aduh95 requested review from richardlau and removed request for a team September 18, 2020 07:41

richardlau approved these changes Sep 18, 2020

View reviewed changes

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

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

aduh95 mentioned this pull request Sep 22, 2020

V14.12.0 proposal #35285

Merged

4 tasks

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 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

Uh oh!

doc: use .md extension for internal links #35191

doc: use .md extension for internal links #35191

Uh oh!

Conversation

aduh95 commented Sep 14, 2020 • edited by targos Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

nodejs-github-bot commented Sep 14, 2020

Uh oh!

Uh oh!

Uh oh!

aduh95 commented Sep 16, 2020

Uh oh!

DerekNonGeneric commented Sep 16, 2020

Uh oh!

gengjiawen commented Sep 16, 2020

Uh oh!

Uh oh!

Trott commented Sep 16, 2020

Uh oh!

Trott commented Sep 16, 2020

Uh oh!

richardlau left a comment

Choose a reason for hiding this comment

Uh oh!

aduh95 commented Sep 22, 2020

Uh oh!

DerekNonGeneric left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduh95 commented Sep 29, 2020

Uh oh!

nodejs-github-bot commented Sep 30, 2020

Uh oh!

Trott commented Oct 1, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

aduh95 commented Sep 14, 2020 •

edited by targos

Loading