Skip to content

feat(jsx): add jsx generator #273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

feat(jsx): add jsx generator #273

wants to merge 7 commits into from

Conversation

avivkeller
Copy link
Member

@avivkeller avivkeller commented May 17, 2025

This PR introduces a jsx generator that transforms Markdown AST and metadata entries into a JSX (recma) AST (with a root of Program), which can then be compiled by the react-web generator from #7.

The JSX generator produces AST that assumes the following components have been implemented:

  • CodeBox: Implementation matches nodejs.org CodeBox
  • CodeTabs: Implementation matches nodejs.org CodeTabs
  • Blockquote: Import from @node-core/ui-components/Common/Blockquote
  • AlertBox: Import from @node-core/ui-components/Common/AlertBox
  • CircularIcon: Accepts:
    • symbol: Icon emblem (e.g., "C" or "E")
    • color: Icon color (e.g., "red" or "#FFFFF")
    Design
  • ChangeHistory: Similar to @node-core/ui-components/Common/Select, accepts:
    • changes: Array of { versions: string[], label: string, url?: string } (where versions[] contains semver strings like v1.2.3)
    Design
  • NavBar: Wrapper of @node-core/ui-components/Containers/NavBar, accepts no props
  • Footer: Wrapper of @node-core/ui-components/Containers/Footer, accepts no props
  • Article: Import from @node-core/ui-components/Containers/Article
  • SideBar: Similar to @node-core/ui-components/Container/SideBar, accepts:
    • versions: Array of versions (e.g., v20.0.0) where the document exists
    • currentVersion: Current documentation version (e.g., v20.1.0)
    • currentPage: Current page (e.g., async_context.html) for highlighting in the sidebar
    • docPages: Array of [{ title: string, headings: [title, hash][], doc: string }] pairs (e.g., { title: "Globals", headers: [["someGlobal", "#some-global"]], doc: "globals.html"})
    Design
  • MetaBar: Wrapper of @node-core/ui-components/Containers/MetaBar, accepts:
    • headings: Array of { depth: number, value: string } for table of contents
    • addedIn: Version when doc/module was added (e.g., v0.10.0)
    • readingTime: String like "9 min read"
    • viewAs: Array of ["Type", "URL"] pairs (currently only supports ["JSON", "globals.json"])
    • editThisPage: GitHub URL for editing the page

As a reminder, the Figma design is:
image

As of 5/26/25, the generated AST is: https://aviv.sh/hostables/nodejs/1748274862-jsx-ast.json

Copy link
Member

@AugustinMauroy AugustinMauroy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting basic, don't miss to add some test

@avivkeller
Copy link
Member Author

I'm working on skipping the MDX and going to straight to JSX, so I'll add lots of tests when that's started

@avivkeller avivkeller changed the title [WIP] mdx generator [WIP] jsx generator May 18, 2025
@avivkeller avivkeller force-pushed the wip/mdx-generator branch 2 times, most recently from 60922b4 to d2bd5f4 Compare May 18, 2025 23:42
@avivkeller
Copy link
Member Author

avivkeller commented May 19, 2025

This uses pnpm for now, see #236 for reference. If we do adopt pnpm, it would be a seperate PR, this is just for development.

@avivkeller avivkeller linked an issue May 20, 2025 that may be closed by this pull request
@avivkeller avivkeller changed the title [WIP] jsx generator feat(jsx): add jsx generator May 21, 2025
@avivkeller avivkeller marked this pull request as ready for review May 22, 2025 00:24
@avivkeller avivkeller force-pushed the wip/mdx-generator branch from 8020c31 to 60e76e5 Compare May 22, 2025 00:24
@avivkeller avivkeller requested a review from a team as a code owner May 22, 2025 00:24
@avivkeller avivkeller force-pushed the wip/mdx-generator branch from ef09a04 to a002cc3 Compare May 22, 2025 21:14
Copy link
Member

@ovflowd ovflowd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've left a final round of comments; After that LGTM. But only approving the PR once the git-deps issue is addressed (either by the upstream npm publish or incorporating git-deps on @.pkgjs/@.nodejs)

@avivkeller avivkeller requested a review from anonrig May 26, 2025 17:46
@AugustinMauroy
Copy link
Member

maybe add little bit more test

@avivkeller avivkeller dismissed anonrig’s stale review May 27, 2025 13:06

This review was specific to a security concern, which has since been resolved.

@avivkeller avivkeller requested review from ovflowd and canerakdas May 27, 2025 13:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add mdx-react generator
6 participants