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]

@nodejs/collaborators @nodejs/web-infra @nodejs/nodejs-website

If you could be so kind as to review https://api-docs-tooling.vercel.app/ and come up with a list of things that still need to be completed, it would be helpful. I know it's a bit tedious, but it'll help with the development significantly.

Note that we are aware of the following issues:

• The History component does not show HTML, see entry.changes aren't converted to HTML #326
• Unix Manual URLs are not linked, see fix(parser): transform man pages #349
• Some typed lists are not rendered as tables, see Lint Typed Lists #348
• "Copy to clipboard" notifications don't show, see feat(ui): move more Toast logic nodejs.org#7973
• The width of certain pages is larger than the viewport

Note that we are in the process of making the following improvements:

• Increasing the depth of the right-hand side ToC
• Adding a tooltip/expand to the DataTag, which explains what it refers to (@ovflowd, would you mind opening an issue in nodejs/nodejs.org?)
• A visualization of the extends keyword (which, I still need to design)
• Improving the UX of the Mobile Table Design, see Poor Table UX on Mobile nodejs.org#7656

[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).