feat(web): add web generator

[avivkeller]

Fixes #7.

This PR adds the web generator.

Tasks / Issues

P1 – Must Complete Before Merge

• Add more items (anyone can do this as they review¹)

P2 – Must complete before migration

• Visualize the extends keyword
• The History component does not show HTML, see entry.changes aren't converted to HTML #326
• Some typed lists are not rendered as tables, see Lint Typed Lists #348
• Add more items (anyone can do this as they review¹)

P3 – Can Be Done in a Follow-up

• Remove mustache dependency
• Adding a tooltip/expand to the DataTag
• Use new Orama UI
• Add more items (anyone can do this as they review¹)

Get a preview

node bin/cli.mjs generate -t orama-db -i "/node/doc/api/*.md" -o "./out" # If you want search functionality
node bin/cli.mjs generate -t web -i "/node/doc/api/*.md" -o "./out" --index "/node/doc/api/index.md" # Specifying `--index` is optional, but recommended
npx serve out # You can serve the output, or just open one of the files in your browser. Serving is required for using search.

Footnotes

1. Add things as they appear, or leave review comments. ↩ ↩² ↩³

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 53.89507% with 580 lines in your changes missing coverage. Please review.

Project coverage is 70.54%. Comparing base (6fa7d1b) to head (2e3f96d).

✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...nerators/jsx-ast/utils/createSignatureElements.mjs	30.37%	149 Missing ⚠️
src/generators/web/index.mjs	39.55%	81 Missing ⚠️
src/generators/jsx-ast/utils/buildContent.mjs	47.01%	71 Missing ⚠️
src/generators/web/build/generate.mjs	22.36%	59 Missing ⚠️
src/generators/web/build/css.mjs	24.19%	47 Missing ⚠️
src/generators/jsx-ast/utils/buildBarProps.mjs	36.92%	40 Missing and 1 partial ⚠️
src/generators/web/build/bundle.mjs	24.52%	40 Missing ⚠️
src/generators/jsx-ast/index.mjs	26.00%	37 Missing ⚠️
src/generators/orama-db/index.mjs	54.34%	21 Missing ⚠️
src/utils/queries/index.mjs	71.73%	10 Missing and 3 partials ⚠️
... and 8 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #285      +/-   ##
==========================================
- Coverage   72.12%   70.54%   -1.58%     
==========================================
  Files         117      128      +11     
  Lines        9984    10926     +942     
  Branches      597      633      +36     
==========================================
+ Hits         7201     7708     +507     
- Misses       2780     3211     +431     
- Partials        3        7       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[avivkeller]

🎉 The code now dehydrates to the client so it can render without JavaScript!

[AugustinMauroy]

🎉 The code now dehydrates to the client so it run without JavaScript!

Wow 😵‍💫 and what about codetab

[avivkeller]

It rehydrates and runs with JS, but if you don't have JS, you can still view the docs. I used React's SSRing

[avivkeller]

@AugustinMauroy and I got search to finally work 🎉

[avivkeller]

@nodejs/nodejs-website @nodejs/web-infra ChangeHistory and SideBar aren't implemented yet, so this is still a draft, but it's ready for you to take a look, so feel free to review :-)

[avivkeller]

@ovflowd Did something change on the main branch that required a fast-forward? I've undone that commit to see if it fixes the deployment.

[ovflowd]

@ovflowd Did something change on the main branch that required a fast-forward? I've undone that commit to see if it fixes the deployment.

Please don't undo the commit lol

[ovflowd]

It was just updated vercel permissions that needed to be fixed.

[avivkeller]

Ahh I see, apologies.

[avivkeller]

I've re-requested review from previous web-team reviewers, since this PR has undergone substantial changes since the last code review comment.

I'm pleased to feel that this PR is in a place where it can land with minimal adjustments (where a follow-up tracking improvements can be made, see the list of improvements in the PR description).

[AugustinMauroy]

focusing a title make a ugly focus ring maybe upstream issue

[avivkeller]

We have the same thing on https://nodejs.org, and I quite like it.

[ovflowd]

Can we pin the remaining feedback items to be impl?:

• feat(web): add web generator #285 (comment)
• feat(web): add web generator #285 (comment)

And verify previous feedback was not missed accidentaly (I'd recommend @avivkeller going through the numerous comments I and Dario made xD)

[ovflowd]

(FYI Im only going to review the code once the remaining features are impl)

[avivkeller]

Noted. I'll go through all the comments, and pin this the things still needing to be implemented in the PR description, sorted by priority.

[avivkeller]

To some of the comments that needed an additional reply:

(@AugustinMauroy) "I think we should fix this on the node/nodejs.org side, but shouldn't the numerical index of the StabilityIndex component be at the top left?"

(@dario-piotrowicz) "the history selector's focus-visible style is barely noticeable in light mode"

(@dario-piotrowicz) "the Toggle navigation menu element is not very accessible, it has a role of button and an aria-label, but it doesn't seem like it is interactable via keyboard (tab navigation + enter)" (nodejs/nodejs.org has an issue open)

(@ovflowd)
"We should document what C, M, E (and the different versions of "C") mean somewhere. Either by a hover tooltip or "about this documentation""
"I think I have an idea for solving the "what are these "S", "C", "M"...""

(@avivkeller) "Adding a tooltip/expand to the DataTag, which explains what it refers to"

(@avivkeller) "Improving the UX of the Mobile Table Design" (nodejs/nodejs.org has an issue open)

These, if determined to be issues, are in https://github.com/nodejs/nodejs.org. Please open an issue there, if not already. Any changes there will be reflected in the @node-core/ui-components package, so I don't believe they block this PR, since, they are upstream issues.

(@dario-piotrowicz) "I personally think the stability alter boxes should include the word stability"

Have we reached consensus on whether or not to implement this? Perhaps as a title?

(@ovflowd) "Maybe also add a <hr /> between top level things (classes, idk)"

I don't think that's really needed, do you insist?

(@ovflowd) "Ah and some stuff seems to not be using the new table yet:"

See nodejs/node#59019

(@ovflowd) "It'd be great if we could also have a navbar 🤔 but maybe not (and not a blocker can be a folow-up)"

Do you want me to just copy the current navbar from https://github.com/nodejs/nodejs.org? Or, should this fetch https://github.com/nodejs/nodejs.org/blob/main/apps/site/navigation.json#L2.

(@ovflowd) "Can we make a visual representation of the extends?"

I'm still not sure how this would look? Would it be like a signature code block that's just

MyClass extends MySuperClass

(@ovflowd) "Shouldn't the ToC of file system include also the methods and classes? 🤔"

I've upped the depth.

(@avivkeller) "The History component does not show HTML"

(@avivkeller) _"Some typed lists are not rendered as tables"

This isn't an issue with this generator, so IMO it shouldn't block it.

See #326
See nodejs/node#59019 + #348