doc: add possibility to patch static HTML files

[tniessen]

While it is great that our documentation is static, it does bring some downsides. For example, when a user selects an older version of Node.js from the dropdown menu at the top, they won't be able to switch to a newer version because the dropdown menu in the older version doesn't know about the newer version. We've also had significant formatting issues in some versions of the documentation, and there is no way to fix that apart from releasing a new version.

This PR is a suggestion that adds a single script tag to the end of the body, therefore not slowing down the page. The referenced file would be in the static/js directory in the website repository and could be changed at any time to apply arbitrary (visual) patches to static documentation files.

Again, this is just a suggestion. This is only useful if we add it as soon as possible, since it can only affect versions and releases that include this patch. I'd be happy to hear opinions!

My primary concern is adding a dependency on the nodejs.org domain -- however unlikely it may be that it will ever go away. That's why the script should only apply visual patches, not content patches, in my opinion. In rare cases when users do not have internet access and are looking at a local copy, the page should still work just fine. (We are already loading a stylesheet from Google servers so there is an external dependency already.)

I also fully understand if people feel like this adds unnecessary complexity. Again, the main point is that this is not something we can patch in later. We could even leave the JavaScript file empty, just to have the option of using this feature in the future. (Updating the version dropdown would be really neat, though.)

An alternative would be to just let static files be static files, and forget about them as soon as we release a new version. Or we could somehow patch them server-side, but I am not a huge fan of that approach.

Long story short, I am looking for opinions regarding this idea! Thank you!

cc @nodejs/website @nodejs/documentation

Checklist

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

[aduh95]

Suggested change

	<script src="https://nodejs.org/static/js/doc-patches.js"></script>
	<script src="https://nodejs.org/static/js/doc-patches.js" type="module"></script>
	<script src="https://nodejs.org/static/js/doc-patches.js" nomodule defer async></script>

[mscdex]

What exactly would be in this script if it's going to be included for every node version going forward? It seems like it'd quickly turn into a maintenance nightmare if the intent is to more or less backport doc fixes on the client side instead of relying on the traditional git-based process?

[tniessen]

What exactly would be in this script if it's going to be included for every node version going forward?

For example, a few lines to add newer versions to the incomplete dropdown menu shown by older versions. Primarily, it's about the ability to apply changes in the future without having to rebuild docs.

[Trott]

I guess this might solve the problem preventing #33466 from being workable. If so, I'd like that.

[tniessen]

@Trott I believe it would allow solving that problem.

[tniessen]

@nodejs/documentation If there's no interest in this feature, feel free to close this PR.

[Trott]

I very much like the idea of being able to solve the version picker problem. It's a not-insignificant UX issue that confuses/frustrates users who use the version picker. On the other hand, I wish we didn't have to couple it to an asset that doesn't live in this repo. This may cause a minor issue (error loading the script) for folks who build the docs locally and use them when offline. I think that's an acceptable trade-off though and I don't have a better idea, as is evidenced from #33466 stalling.

/ping @codebytere (who at least at one time was keen to solve the version picker problem)

[Trott]

Added blocked label because this can't land until the file is created on the website.

[Trott]

Needs a rebase but LGTM

[tniessen]

On the other hand, I wish we didn't have to couple it to an asset that doesn't live in this repo.

I'm not a fan of this either, I just can't think of any alternatives. Also, this won't solve the version picker problem for older versions without this patch.

[aduh95]

This may cause a minor issue (error loading the script) for folks who build the docs locally and use them when offline.

We could have the <script> tag added only if the docs are build with a CLI flag / some env variable, this way folks building the docs locally wouldn't be affected.

[tniessen]

We could have the <script> tag added only if the docs are build with a CLI flag / some env variable, this way folks building the docs locally wouldn't be affected.

True, but then we'd end up with multiple different versions of the docs. I believe that's something we'd like to avoid. If we do allow it, we don't even need to add this at all, and can just edit the HTML files of previous versions on nodejs.org.

[tniessen]

Closing due to the apparent lack of interest from Node.js.

[DerekNonGeneric]

I would prefer if we do not close this just yet as it is probably the only issue tracking the version picker problem.

[Trott]

I'm super-busy cleaning my floors right now, but I'm going to stop long enough to post a roadmap for landing this.

• Get the file on the website so the blocked label can be removed. I imagine it may be possible to get it on the website by opening a PR in the nodejs.org repository.
• Rebase and wait for green GitHub Actions results.
• I approved it and no one has objected and it's been more than 7 days. So once those other things are done, this can technically land. DARE YOU GO FOR IT??!!!!11!!111!!?????//!???!?!

[AugustinMauroy]

sorry, I have 404 error with this link https://nodejs.org/static/js/doc-patches.js are you sure about the link (I can made error)

[tniessen]

While this won't be solved within the API docs, it seems that the website rework team has an approach that works, even if it requires some additional complexity.