Repository: node
Issue: Redesign of the Node.js API Docs
Labels: doc

Hey, y'all 👋 with the redesign of the Node.js Website done. We're ready to move our efforts into revamping the design of the Node.js API docs and its build process.

We understand this is code owned by Node.js Core, so we're (@nodejs/web-infra) opening an issue here.

## Overview

### Revamp of Tooling

- We intend to modernize the current tooling of the Node.js API docs (https://github.com/nodejs/node/tree/main/tools/doc), migrating from the current manual code into something more modern:
  - We intend to transform (in-memory, during build-time, no source change) the raw Markdown into MDX
  - Replace the YAML metadata (in-memory, during build-time, no source change) to references of MDX Metadata
    - This is similar to what we did with an MVP on the `nodejs/nodejs.dev` repository as seen [here](https://github.com/nodejs/nodejs.dev/blob/main/util-node/apiDocsTransformUtils.js) and [here](https://github.com/nodejs/nodejs.dev/blob/main/util-node/getApiDocsData.js)
  - The MDX gets converted into JSX, allowing us to use React Components on the codebase, such as on the Node.js Website
  - Finally, we use `ReactDOM` (Server) to compile the JSX into plain HTML (initial rendering), which is then embedded in the HTML templates, making each page an HTML file. (Source MD file -> Target HTML file as it has been done so far)
    - The file names will be the same
    - The JavaScript client-side code is then built for that specific page, tree-shaken, minimized, and stored on a target `.js` file
      - These JS files have a static filename but are linked within the HTML with a unique `query param and hash` to signal to the Browser that these are different versions.
    - All these output HTML and JS files are stored in the already defined `out` folder (as described on the `make-doc` Makefile step of the Node.js build process)
  - This revamp of the tooling allows more modern frameworks and libraries to be adopted.

#### Tooling Dependencies

- We aim to use [`preact`](https://preactjs.com/) as a JSX library (+ DOM rendering) since it's pretty much React but lightweight, it has pretty much 1:1 to React's API, and since the API docs are extremely simple statically generated page, we don't need anything fancier
- We aim to use [`Vite`](https://vitejs.dev/) for the build process, transpiling/compilation and output to HTML files, and for the availability of HMR/Dev Server. This will be an experiment.
- We aim to use [`MDX`](https://mdxjs.com/) to parse and transform the markdown into MDX/JSX.
- All other old dependencies would be removed/unnecessary. Some other devDependencies, like `semver,` might be needed.

### Revamp of Design

After the revamp of tooling is done, we have a 1:1 feature to the old generation of API docs, and we can generate the same API docs with the same styles, same layout, and same components (the HTML snippets transformed into React Components), we can proceed with the revamp of styles.

This means we would adopt [these designs based on the Node.js Website redesign](https://www.figma.com/file/pu1vZPqNIM7BePd6W8APA5/Node.js?type=design&node-id=422-7923&mode=design&t=BOhJRW4h80KF6fnJ-0) into the API Docs. These designs may still change and are pending @nodejs/tsc approval)

This part is blocked by the monorepo transformation of the Node.js Website repository, which would allow all the existing components to be bundled into a UI components package.

We aim to use [Shiki](https://shiki.matsu.io/) as we use on the Node.js Website for the CodeBoxes and [Tailwind](https://tailwindcss.com/) and [Radix UI](https://www.radix-ui.com/) for Component tooling and a11y as we've done on the Node.js Website.

This would fundamentally course-correct the current design of the API Docs. Note that we aim to add a Search box (as we've done on the Node.js Website) and restructure the API Docs as [described on this initiative of the Next-10 initiative](https://github.com/nodejs/next-10/issues/166).

#### It is part of the redesign of the Node.js API Docs:

- Applying the new styles, components, and UI as envisioned on Figma
- Better Navigation as envisioned on Figmas, which is doable by the newly revamped tooling (see the `nodejs/nodejs.dev` tooling attached above as a reference)
- Search input / Search boxes for the content of the API docs
- Better Table of Contents and overall reading based on the Figma designs

## What is this issue about?

Keeping track of the efforts, communication, feedback, and progress of the revamp of the tooling and redesign of the API Docs is a sort of "Epic" for the whole initiative.

### What's next?

Gathering initial feedback, consensus-seeking with Core Collaborators, and starting to delegate work on both fronts. Any support is welcome.

## F.A.Q.

#### Are we going to translate the API docs?

No. It's an impossible and unmaintainable task. There is too much risk and work, and API docs get outdated fast. There is no merit in translating the API docs.

#### Can I help with the work on the API docs tooling?

Yes and no. We're more than open for feedback, ideas and code review, but the big chunk of work will be done by the Web Infra team which has a good knowledge of the tooling changes needed to be done and a good envisioning of what should be done.

#### Can I help with the redesign?

Yes! Implementation of components, designs, etc, is more than welcome! The actual components will reside on this repository and the Node.js Website. The API docs will only import the components/use them as the source will be on the Node.js Website repository.

#### Is there any timeline?

Not yet. We want to reach a consensus first and have a good understanding that the overall community is happy with these proposed changes + the proposed dependencies we want to use, such as MDX.

#### With MDX are the source files changing?

No. The transform into MDX will happen only in memory during the build time as a build-step. So that we can transform the non-conforming YAML metadata into something React can use. The source files will be untouched.

#### What are the problems with the current tooling?

-   The current tooling does not support React.
-   It has numerous limitations that hinder the implementation of desired features in the website redesign.
-   The tooling is considered messy to update and not friendly for newcomers.
-   It makes redesigning the API docs unintuitive and almost impossible without encountering significant blockers.