From a19ca6cbd23921da92c9c7d1027149bf348b7580 Mon Sep 17 00:00:00 2001 From: Brian Muenzenmeyer Date: Fri, 24 Jul 2026 13:43:16 -0500 Subject: [PATCH 1/2] Adds link to beta docs (#8998) * add navitem accent and beta docs * filter out 'Beta Docs' from expected navigation translations in tests * refactor test * align nav accent to secondary button --- apps/site/components/withNavBar.tsx | 13 ++++++++----- apps/site/hooks/useSiteNavigation.ts | 4 +++- apps/site/navigation.json | 6 ++++++ apps/site/tests/e2e/general-behavior.spec.ts | 13 +++++++++++-- apps/site/types/navigation.ts | 2 ++ packages/i18n/src/locales/en.json | 1 + .../Containers/NavBar/NavItem/index.module.css | 16 +++++++++++++++- .../src/Containers/NavBar/NavItem/index.tsx | 9 ++++++++- .../src/Containers/NavBar/index.stories.tsx | 6 ++++++ .../src/Containers/NavBar/index.tsx | 4 +++- 10 files changed, 63 insertions(+), 11 deletions(-) diff --git a/apps/site/components/withNavBar.tsx b/apps/site/components/withNavBar.tsx index 275419bbf18a8..722fb3ede57f0 100644 --- a/apps/site/components/withNavBar.tsx +++ b/apps/site/components/withNavBar.tsx @@ -54,11 +54,14 @@ const WithNavBar: FC = () => { ({ - link, - text: label, - target, - }))} + navItems={navigationItems.map( + ([, { label, link, target, accent }]) => ({ + link, + text: label, + target, + accent, + }) + )} pathname={pathname} as={Link} Logo={WithNodejsLogo} diff --git a/apps/site/hooks/useSiteNavigation.ts b/apps/site/hooks/useSiteNavigation.ts index aa7a2be8efb78..d0c8236010b45 100644 --- a/apps/site/hooks/useSiteNavigation.ts +++ b/apps/site/hooks/useSiteNavigation.ts @@ -19,6 +19,7 @@ type MappedNavigationEntry = { label: FormattedMessage; link: string; target?: HTMLAttributeAnchorTarget | undefined; + accent?: boolean; }; // Provides Context replacement for variables within the Link. This is also something that is not going @@ -44,13 +45,14 @@ const useSiteNavigation = () => { t.rich(label, context[key] || {}) as FormattedMessage; return Object.entries(entries).map( - ([key, { label, link, items, target }]): [ + ([key, { label, link, items, target, accent }]): [ string, MappedNavigationEntry, ] => [ key, { target, + accent, label: label ? getFormattedMessage(label, key) : '', link: link ? replaceLinkWithContext(link, context[key]) : '', items: items ? mapNavigationEntries(items, context) : [], diff --git a/apps/site/navigation.json b/apps/site/navigation.json index 65d0e9f69b295..c90136d5edbd8 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -20,6 +20,12 @@ "link": "https://nodejs.org/docs/latest/api/", "label": "components.containers.navBar.links.docs" }, + "betaDocs": { + "link": "https://beta.docs.nodejs.org/", + "label": "components.containers.navBar.links.betaDocs", + "target": "_blank", + "accent": true + }, "contribute": { "link": "https://github.com/nodejs/node/blob/main/CONTRIBUTING.md", "label": "components.containers.navBar.links.contribute", diff --git a/apps/site/tests/e2e/general-behavior.spec.ts b/apps/site/tests/e2e/general-behavior.spec.ts index 813fabf5ed209..fc0ca9107daa9 100644 --- a/apps/site/tests/e2e/general-behavior.spec.ts +++ b/apps/site/tests/e2e/general-behavior.spec.ts @@ -10,6 +10,9 @@ const locators = { mobileMenuToggleName: englishLocale.components.containers.navBar.controls.toggle, navLinksLocator: `[aria-label="${englishLocale.components.containers.navBar.controls.toggle}"] + div`, + // The Beta Docs link renders untranslated (English) across locales, so we + // match on its English label to skip it during translation checks. + betaDocsName: englishLocale.components.containers.navBar.links.betaDocs, // Global UI controls languageDropdownName: englishLocale.components.common.languageDropdown.label, themeToggleName: englishLocale.components.header.buttons.theme, @@ -55,8 +58,14 @@ const verifyTranslation = async (page: Page, locale: Locale | string) => { // Verify each navigation link text matches an expected translation for (const link of links) { - const linkText = await link.textContent(); - expect(expectedTexts).toContain(linkText!.trim()); + const linkText = (await link.textContent())!.trim(); + // Skip the Beta Docs link: it renders untranslated (English) across + // locales and has no translation entry in most locale files, so it + // won't appear in `expectedTexts` for non-English locales (e.g. es). + if (linkText === locators.betaDocsName) { + continue; + } + expect(expectedTexts).toContain(linkText); } }; diff --git a/apps/site/types/navigation.ts b/apps/site/types/navigation.ts index 5f3d4db1fbe70..b12e85e4c0ac2 100644 --- a/apps/site/types/navigation.ts +++ b/apps/site/types/navigation.ts @@ -16,6 +16,7 @@ export type NavigationKeys = | 'about' | 'download' | 'docs' + | 'betaDocs' | 'getInvolved' | 'certification' | 'learn' @@ -26,6 +27,7 @@ export type NavigationEntry = { link?: string; items?: Record; target?: HTMLAttributeAnchorTarget | undefined; + accent?: boolean; }; export type SiteNavigation = { diff --git a/packages/i18n/src/locales/en.json b/packages/i18n/src/locales/en.json index 6c8466e119bf2..72694ac172947 100644 --- a/packages/i18n/src/locales/en.json +++ b/packages/i18n/src/locales/en.json @@ -36,6 +36,7 @@ "about": "About", "download": "Download", "docs": "Docs", + "betaDocs": "Beta Docs", "guides": "Guides", "learn": "Learn", "security": "Security", diff --git a/packages/ui-components/src/Containers/NavBar/NavItem/index.module.css b/packages/ui-components/src/Containers/NavBar/NavItem/index.module.css index 7b49c39378c02..8c1d47bb58f5c 100644 --- a/packages/ui-components/src/Containers/NavBar/NavItem/index.module.css +++ b/packages/ui-components/src/Containers/NavBar/NavItem/index.module.css @@ -6,7 +6,8 @@ gap-2 rounded-sm px-3 - py-2; + py-2 + motion-safe:transition-colors; .label { @apply text-base @@ -45,6 +46,19 @@ } } + &.accent { + @apply bg-transparent + ring-1 + ring-neutral-200 + ring-inset + dark:ring-neutral-900; + + &:hover { + @apply bg-neutral-200 + dark:bg-neutral-900; + } + } + &.footer { .label { @apply text-neutral-800 diff --git a/packages/ui-components/src/Containers/NavBar/NavItem/index.tsx b/packages/ui-components/src/Containers/NavBar/NavItem/index.tsx index c57c2f3fc410b..848e6d98c45d1 100644 --- a/packages/ui-components/src/Containers/NavBar/NavItem/index.tsx +++ b/packages/ui-components/src/Containers/NavBar/NavItem/index.tsx @@ -15,6 +15,7 @@ type NavItemProps = { type?: NavItemType; className?: string; target?: HTMLAttributeAnchorTarget | undefined; + accent?: boolean; pathname: string; active?: boolean; @@ -27,12 +28,18 @@ const NavItem: FC> = ({ children, className, target, + accent, ...props }) => ( ; Logo?: ElementType; as: LinkLike; @@ -92,7 +93,7 @@ const NavBar: FC> = ({
{navItems && navItems.length > 0 && (
- {navItems.map(({ text, link, target }) => ( + {navItems.map(({ text, link, target, accent }) => ( > = ({ key={link} href={link} target={target} + accent={accent} > {text} From 36f4983b7516e933f5b047bb1f85ac97337f5989 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Fri, 24 Jul 2026 16:35:38 -0300 Subject: [PATCH 2/2] feat: create beta API docs announcement post (#9002) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: create api docs beta announcement blog post * feat: add ack section * Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Brian Muenzenmeyer * fix: remove markdown from new features * fix: review * feat: add llms.txt point * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Guilherme Araújo * chore: update post datetime --------- Signed-off-by: Brian Muenzenmeyer Signed-off-by: Guilherme Araújo Co-authored-by: Brian Muenzenmeyer Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- apps/site/authors.json | 5 +++ .../blog/announcements/new-api-docs-beta.md | 37 +++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 apps/site/pages/en/blog/announcements/new-api-docs-beta.md diff --git a/apps/site/authors.json b/apps/site/authors.json index e3901173461df..03624328fa640 100644 --- a/apps/site/authors.json +++ b/apps/site/authors.json @@ -113,6 +113,11 @@ "name": "Giovanny Gongora", "website": "https://github.com/Gioyik" }, + "Guilherme Araújo": { + "id": "araujogui", + "name": "Guilherme Araújo", + "website": "https://github.com/araujogui" + }, "Isaac Schlueter": { "id": "isaacs", "name": "Isaac Schlueter", diff --git a/apps/site/pages/en/blog/announcements/new-api-docs-beta.md b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md new file mode 100644 index 0000000000000..bf8f6fc4fc3d6 --- /dev/null +++ b/apps/site/pages/en/blog/announcements/new-api-docs-beta.md @@ -0,0 +1,37 @@ +--- +date: '2026-07-24T19:00:00.000Z' +category: announcements +title: Check out the New Node.js API Documentation Preview +layout: blog-post +author: Guilherme Araújo +--- + +We've been rebuilding how Node.js generates and presents its API documentation, and a preview is now live at [beta.docs.nodejs.org](https://beta.docs.nodejs.org/). Before it becomes the default, we want as many people as possible to use it for real work and tell us what you think. + +## What's different for readers + +The content itself hasn't changed: every page is generated from the same Markdown files in the [nodejs/node](https://github.com/nodejs/node) repository that power the current docs. The features you rely on today made the trip too: light and dark themes, ESM/CJS switching and copy buttons on snippets, stability badges, version history, and the Markdown version of every page. + +The redesign goes deeper than visuals, though: navigation, layout, and readability were all reworked so that finding and understanding an API takes less effort. On top of that, the beta adds things the current docs have never had: + +- **Search**: For the first time, the API docs have built-in search. A search box on every page, with a keyboard shortcut, lets you jump anywhere in the API without a detour through a search engine. +- **One design across the project**: The API docs now share the design system of the nodejs.org website, with a persistent sidebar listing every module, an always-visible per-page table of contents, and a layout that works on small screens. +- **llms.txt**: We've already shipped [llms.txt](https://nodejs.org/llms.txt), giving AI tools a clean, structured entry point to the API reference. + +And that's not the whole list: the beta also ships features like reading times and announcement bars. + +We also care about the needs of every user, and we pay attention to the ones that are easy to overlook. Every page stays usable even with JavaScript disabled and offline. + +## Under-the-hood + +The redesigned documentation is built with [doc-kit](https://github.com/nodejs/doc-kit), a standalone tool developed by the Node.js Project to replace the previous legacy documentation generator. + +For more information on doc-kit and its capabilities for other projects, please refer to [its repository](https://github.com/nodejs/doc-kit). This will also be the place where bug reports, feature requests, and other tasks should be tracked. + +## We need your feedback + +While we are proud to state that the redesigned documentation is entering its final stage of development, feedback is still a crucial part of this migration, and we'd love to hear your thoughts on this process. Please open an issue on the [nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues) repository with anything you find, big or small. + +## Acknowledgments + +None of this would exist without the [Node.js Web Team](https://github.com/nodejs/web-team/blob/main/MEMBERS.md), whose members designed, built, and reviewed everything described in this post. Thanks as well to the Node.js community and the collaborators who have already helped by reviewing, testing, and making suggestions along the way. Thank you all for making this possible.