feat(docs): introduced initial version of api docs system

[ovflowd]

Description

This PR introduces an initial version of a script that retrieves the Markdown files for each API version of the current non-EOL and non-Pending Node.js API docs.

This PR introduces the mechanisms that modifies the <!-- YAML --> API tags into an MDX Component for rendering the Metadata as in https://nodejs.org/api.

It also introduces mechanisms to create the Frontmatter of the Codebase.

This PR will also replace the current docs.tsx page into a template and remove all its garbage code.

Related Issues

Closes https://github.com/nodejs/nodejs.dev/issues/2611
Closes https://github.com/nodejs/nodejs.dev/issues/2630

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run npm run lint:js -- --fix and/or npm run lint:md -- --fix for my JavaScript and/or Markdown changes.
  • This is important as most of the cases your code changes might not be correctly linted
• I have run npm run test to check if all tests are passing, and/or npm run test -- -u to update snapshots if I created and/or updated React Components.
• I have checked that the build works locally and that npm run build work fine.
• I've covered new added functionality with unit tests if necessary.

[codecov-commenter]

Codecov Report

Merging #2680 (dbc044b) into main (62403e6) will decrease coverage by 18.68%.
The diff coverage is 32.53%.

@@             Coverage Diff             @@
##             main    #2680       +/-   ##
===========================================
- Coverage   87.51%   68.83%   -18.69%     
===========================================
  Files         100      119       +19     
  Lines         977     1325      +348     
  Branches      252      333       +81     
===========================================
+ Hits          855      912       +57     
- Misses        115      379      +264     
- Partials        7       34       +27     

Impacted Files	Coverage Δ
src/__fixtures__/page.tsx	100.00% <ø> (ø)
...components/ApiComponents/Components/ApiHeading.tsx	0.00% <0.00%> (ø)
...rc/components/ApiComponents/Components/ApiLink.tsx	0.00% <0.00%> (ø)
...ponents/ApiComponents/Components/Changes/index.tsx	0.00% <0.00%> (ø)
...ents/ApiComponents/Components/SourceLink/index.tsx	0.00% <0.00%> (ø)
...components/ApiComponents/Components/Span/index.tsx	0.00% <0.00%> (ø)
...nents/ApiComponents/Components/Stability/index.tsx	0.00% <0.00%> (ø)
src/components/ApiComponents/index.tsx	0.00% <0.00%> (ø)
src/components/DataTag/index.tsx	0.00% <0.00%> (ø)
src/components/Header/index.tsx	100.00% <ø> (ø)
... and 35 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[github-actions]

Please find a preview at: https://staging.nodejs.dev/2680/

[manishprivet]

Looks Good 🙌🏼

The only nit I had was that since there's no versioning here in this initial version, maybe we could mention the latest version of Node for which this documentation is for somewhere?

Also, the last page is returning blank for me: https://staging.nodejs.dev/2680/en/api/modules/

[ovflowd]

Also this might be a more specific issue to just our codebase, but its pretty old and changed hands several times, so many of these events we may have lost domain knowledge on if they are actually important how how to trigger them in a reliable way

Oh damn, it looks like MDX is trying to interpolate this piece as an actual JavaScript code 🤦 (https://github.com/nodejs/node/blob/main/doc/api/modules.md?plain=1#L276)

[github-actions]

Please find a preview at: https://staging.nodejs.dev/2680/

[manishprivet]

NIt: Codeblocks seem to have changed to a permanent light theme from a permanent dark theme in this PR. Is that intended? If yes, should it be part of this PR?

Before

After

[github-actions]

Please find a preview at: https://staging.nodejs.dev/2680/

[ovflowd]

Note.: For some reason when clicking on the API Docs button it still shows the legacy/cached page. But when I refresh the page it shows the new one.

I have no idea if this is a thing from Gatsby or Google Cloud 🤯

[manishprivet]

Redirects are working fine for me. However, navigating the side nav feels weird with Globals and Classes sections having links to a section of the Globals page (https://staging.nodejs.dev/2680/en/api/v18/globals). Maybe we can remove them altogether? Since they're also not present on the original website.

Also, maybe it's a problem with the original website itself, but some pages in Docs seem to have different titles in on the documentation homepage. E.g., See the docs homepage and assert page.
If it is intended, can we use the source of the page list that's being used here in the Sidebar?

[manishprivet]

Nit: There seems to be a Class: prefix for classes on the original website. Maybe we should add it here as well?

Edit

[ovflowd]

Nit: There seems to be a Class: prefix for classes on the original website. Maybe we should add it here as well?

Oh I removed them intentionally let me add them back!

[ovflowd]

Also, maybe it's a problem with the original website itself, but some pages in Docs seem to have different titles in on the documentation homepage. E.g., See the docs homepage and assert page.
If it is intended, can we use the source of the page list that's being used here in the Sidebar?

I don’t see any value in this, besides of extra work. Sorry, not gonna do 😅

Also, maybe it's a problem with the original website itself, but some pages in Docs seem to have different titles in on the documentation homepage.

Why would this be an issue? Links are the same. The titles here are sourced from the first Heading.

[ovflowd]

@manishprivet it is important to mention that the current Nodejs.org docs Sidebar comes from here.

But one of the main reasons the current PR does its Navigation the way it does it's to easily allow people to access Classes and Globals, linked directly to their paths. Clicking for example on "setImmediate" within the Navigation should redirect you to /api/v18/globals#setImmediate...somethingsomething.

[ovflowd]

@benhalverson @manishprivet I'm also updating the Search Bar to have better results

[github-actions]

Please find a preview at: https://staging.nodejs.dev/2680/

[ovflowd]

@mcollina @joesepi can we somehow clear the cache from G Cloud side? The latest builds are for some reason just not updating (both in terms of styling and actual pages that exist)

[ovflowd]

Trying to re-push as for some reason 3 commits where shown locally as not synced, but no idea.

[benhalverson]

@benhalverson @manishprivet I'm also updating the Search Bar to have better results

I like this. The PR is rather large now. Can the search results changes be in a follow up PR instead.

[benhalverson]

LGTM

[ovflowd]

I like this. The PR is rather large now. Can the search results changes be in a follow up PR instead.

I made changes to the SearchBar within this PR because otherwise, it would be hard to differentiate Learn from API pages, and the API pages title in the SearchBox were just the name of the module e.g. "fs".

So if you searched for "File system path" it would just show "fs", so it fell like a necessary change.

[ovflowd]

I will merge this PR as it is, as we can reiterate further improvements in style, content and features later. Such as, for example, the "Sidebar Version Selection".

In a very soon PR, I want to:

• Add the Sidebar Navigation Selector for Version
• Also, on the current page, the version they're seeing above the title.