Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.08%. Comparing base (7aaf9b4) to head (9ef70f7).
⚠️ Report is 6 commits behind head on main.

@@            Coverage Diff             @@
##             main   #62045      +/-   ##
==========================================
- Coverage   90.13%   90.08%   -0.06%     
==========================================
  Files         751      751              
  Lines      253639   254070     +431     
  Branches    47790    47900     +110     
==========================================
+ Hits       228618   228868     +250     
- Misses      16264    16411     +147     
- Partials     8757     8791      +34     

see 44 files with indirect coverage changes

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @avivkeller.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

cc @nodejs/build @nodejs/web-infra @nodejs/TSC for reviews

Can't quite verify.

➜  node git:(main) gh pr checkout 62045
Switched to branch 'doc/redesign'
➜  node git:(doc/redesign) make doc-only
mkdir -p out/doc/api
cp -r doc/api out/doc

added 374 packages in 2s
error: too many arguments for 'generate'. Expected 0 arguments but got 1.
make: *** [out/doc/api/addons.html] Error 1

@panva Sorry! I'm still trying to get the thread count to work on all CI machines, but the output from https://github.com/nodejs/node/actions/runs/25992332792?pr=62045 's artifacts have the generated docs.

A lot of the runners use slim machines, which it appears interfere with the generation, so I need to see which CI checks fail.

@avivkeller footnotes don't seem to work, I don't know if it's being tracked or not but leaving that here, also don't know if they don't work generally or as a side effect of the bundle here.

There are 100% docs where this is an improvement and it will take some getting used to. Very subjective.

Some oddities I notice upon first (well, first this time around) look, take it with a grain of salt, I'm very used to the old docs and it's easy to focus on what stands out really quickly. In that way I hope this might be valuable (non-blocking) feedback.

• method parameters/arguments are "attributes"? seems odd
• toc for method lists is barely parseable, consider having toc entries for methods only have the module.method(), i.e. don't list the potentially very long list of parameters
• non-heading main content switching between 14px and 16px font sizes - my poor brain can't grok this, i know there's just two sizes but because it's jumping around the two all over the place it feels inconsistent, eventho it is.
• what do you suggest to use in place of tables? the content width is just too tiny to fit any meaningful table.
• because the old class/property lists used a mix if no-background: Class: Name and class.property it was easy to see you're moving on. Now with just [C] and [P] but otherwise same style (and a 2px font size diff, ...) not so much, it sort of blends all together.

what	old	new
toc
table
interface list

@panva we've done rounds of feedback, and based on our current iteration, note:

method parameters/arguments are "attributes"? seems odd

The word "Attributes" allows us to use the same word consistently for these "typed lists", as they appear in several places where it's not easy to identify what they are describing.

toc for method lists is barely parseable, consider having toc entries for methods only have the module.method(), i.e. don't list the potentially very long list of parameters

We attempted this in the past, and unfortunately, the general consensus was that having the full parameter list is much more 'exact', as in, no two entries will be identical.

non-heading main content switching between 14px and 16px font sizes - my poor brain can't grok this, i know there's just two sizes but because it's jumping around the two all over the place it feels inconsistent, eventho it is.

The main prose is 16px. Inside of "typed lists", the font size is 14px.

what do you suggest to use in place of tables? the content width is just too tiny to fit any meaningful table.

The photo you shared is displaying a very large table. Smaller tables render fine. Such tables should be broken down, most likely.

because the old class/property lists used a mix if no-background: Class: Name and class.property it was easy to see you're moving on. Now with just [C] and [P] but otherwise same style (and a 2px font size diff, ...) not so much, it sort of blends all together.

I'm afraid I don't understand the concern. The "tags" refer to the type of the entry, similar to the text prefix.

@AugustinMauroy I have no idea what you are saying. That file should not be removed.

@avivkeller i was referencing to this discussion about this file nodejs/doc-kit#780 (comment)

At this point in time, we still need the /about page, since we don't put the overview on the index. But yes, a follow-up to move that would be worth a discussion.

I'm aware I said previously that we'd need to remove it when we land this generator, but we actually first need to generate a new home for the overview, or just leave it as is.

okay right !

In the meantime, @nodejs/build any suggestions for the memory issues on CI? We don't have any issues running on most machines, should we skip the docs build on these ones?

Opened nodejs/doc-kit#941 for parity

Hey @pimterry @MikeMcC399 @trivikr.

We've attempted to resolve all your concerns. We have a few pending changes (e.g. better light mode, a small UI fix, partial hydration), but I'd love a re-review on the current progress, and an approval if you feel that you are confident in the design at https://beta.docs.nodejs.org (or, for a better light mode coming soon, https://api-docs-tooling-khhh5bmq7-openjs.vercel.app/)

• the table-rendering issue Possible bug on Windows 25H2 doc-kit#909 on https://beta.docs.nodejs.org/url.html

this was fixed, and now i see it again too on Windows - suspect we regressed nodejs/nodejs.org#9015 possibly by nodejs/nodejs.org#9028

• the table-rendering issue Possible bug on Windows 25H2 doc-kit#909 on beta.docs.nodejs.org/url.html

this was fixed, and now i see it again too on Windows - suspect we regressed nodejs/nodejs.org#9015 possibly by nodejs/nodejs.org#9028

Landed!

I would recommend a more compact version for mobile.

I recommend dropping the stability index, or compacting it in the previous line. There is no need to call the module “API”, so you can just list this as “domain …. deprecated”.

This is a list on a mobile device: remove the padding and the boxes. While they are pretty, functional for this comes first.

QUIC should NOT be listed in the api docs yet... the API is still in flux and it's not built by default yet.

QUIC should NOT be listed in the api docs yet... the API is still in flux and it's not built by default yet.

+1

@jasnell that was a now resolved oversight in the preview environment

I would recommend a more compact version for mobile.

I suppose the menu paddings on the beginning (table of contents to header of sections) but Im against removing stability index on mobile, maybe we could reduce their sizes (padding, font size, idk)

I recommend dropping the stability index, or compacting it in the previous line. There is no need to call the module “API”, so you can just list this as “domain …. deprecated”.

Yeah for very very small screens we could indeed reduce a tiny bit more the paddings.

This is a list on a mobile device: remove the padding and the boxes. While they are pretty, functional for this comes first.

Sure.

Hey @mcollina @jasnell! Thanks for the feedback!

We've made some changes, such as making the index page and the about page one, see https://beta.docs.nodejs.org/. We can continue to iterate on specific designs of how to display the index information, but for now, does that resolve your concerns?

@mcollina we changed the index page to use a more response design:

cc @nodejs/web-infra all CI machines are working except MacOS, which ran out of memory when I set the minimum memory needed to run to 6GB and 8GB, even though we only take 4-5GB, any ideas?