doc: rename module pages

[aduh95]

Using a "Modules:" prefix groups all the related pages together when
using alphabetical order.

This is a first PR in attempt to improve package documentation. More changes are coming as discussed in nodejs/modules#539, I've decided to split into several PRs to ease the code review.

Refs: nodejs/modules#539

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[jasnell]

I'm generally -1 on this given that it will break existing links to docs in http://nodejs.org. If we can find a way of aliasing renamed pages first, so that existing links can be forwarded, that would be ideal.

[guybedford]

Agreed it should be possible to do this without changing the existing URLs. Most importantly for the CommonJS modules.md section, but also for the esm.md section. Could we just change the title texts?

[aduh95]

That's right, I haven't thought of that! I have implemented @guybedford's suggestion, PTAL.

[guybedford]

This looks like a good start to me, in particular renaming the existing Modules section to Modules: CommonJS Modules seems like an important change to get through at this point.

[GeoffreyBooth]

@jasnell Do you know who the best person to talk to would be about the mechanics of the docs generation? In particular I'm wondering if anyone can advise us on how to create redirect links so that we can feel free to move or rename sections without breaking links.

[jasnell]

Unfortunately no. I've never done any digging into that part of the code

[richardlau]

Docs are built statically as part of the release process and then copied across to the staging server (see

node/Makefile

Lines 1092 to 1097 in bcfb176

	# Note: this is strictly for release builds on release machines only.
	doc-upload: doc
	ssh $(STAGINGSERVER)"mkdir -p nodejs/$(DISTTYPEDIR)/$(FULLVERSION)/docs/"
	chmod -R ug=rw-x+X,o=r+X out/doc/
	scp -pr out/doc/*$(STAGINGSERVER):nodejs/$(DISTTYPEDIR)/$(FULLVERSION)/docs/
	ssh $(STAGINGSERVER)"touch nodejs/$(DISTTYPEDIR)/$(FULLVERSION)/docs.done"

) (they go live when the release is promoted). When the promotion happens the appropriate latest- link (see https://nodejs.org/docs/) is updated to point to the version uploaded.

I think redirects for the website are handled via https://github.com/nodejs/build/blob/master/ansible/www-standalone/resources/config/nodejs.org. That's completely outside of the docs generation process and I'm not sure there's that many people who understand how that's deployed.

[aduh95]

@jasnell I've updated the PR to address your comment, would be willing to dismiss your objection or to rephrase it if this PR still needs work from me?

[aduh95]

Could this be labeled Author ready?

[GeoffreyBooth]

@aduh95 This needs a rebase, probably because of #34747.

[aduh95]

Rebased on master, should be good now!

[GeoffreyBooth]

This looks good to me. @Trott are you okay with the current language?

[Trott]

This looks good to me. @Trott are you okay with the current language?

Yes.

[Trott]

Landed in 22e3ada