feat: add learn content to the node.js website (nodejs#6064)

* feat: sidenav support recursive items

* feat: added learn layout

* feat: added learn navigation

* feat: added new translation ids

* feat: mark docs as archive

* chore: improved styles, use grid system

* feat: added learn pages, removed duplicated/outdated guides

* chore: added images

* meta: crowdin no translations for learn

* chore: updated redirects

* meta: no need of package-name for private package

* Apply suggestions from code review

Co-authored-by: canerakdas <[email protected]>
Signed-off-by: Claudio W <[email protected]>

* style: use flexboxes

* chore: self-code-review and adjustments

---------

Signed-off-by: Claudio W <[email protected]>
Co-authored-by: canerakdas <[email protected]>

Author: ovflowd

components/SideNavigation.tsx

@@ -21,15 +21,25 @@ const SideNavigation: FC<SideNavigationProps> = ({
 
   const sideNavigationItems = getSideNavigation(navigationKey, context);
 
-  const getLinkClassName = (href: string) =>
-    classNames({ active: isCurrentLocaleRoute(href) });
+  const getLinkClasses = (href: string, level: number) =>
+    classNames({ active: isCurrentLocaleRoute(href), level });
 
   return (
     <nav aria-label="secondary">
       <ul>
-        {sideNavigationItems.map((item, key) => (
-          <li key={key} className={getLinkClassName(item.link)}>
+        {sideNavigationItems.map(item => (
+          <li key={item.key} className={getLinkClasses(item.link, item.level)}>
             <LocalizedLink href={item.link}>{item.text}</LocalizedLink>
+
+            {item.items.length > 0 && (
+              <ul>
+                {item.items.map(({ link, level, text, key }) => (
+                  <li key={key} className={getLinkClasses(link, level)}>
+                    <LocalizedLink href={link}>{text}</LocalizedLink>
+                  </li>
+                ))}
+              </ul>
+            )}
           </li>
         ))}
       </ul>

crowdin.yml

@@ -8,6 +8,7 @@ files:
     content_segmentation: 0
     ignore:
       - /pages/en/blog/**/*.md
+      - /pages/en/learn/**/*.md
       - /pages/en/docs/guides/**/*.md
       - /pages/en/download/index.md
       - /pages/en/download/current.md
@@ -22,6 +23,7 @@ files:
     content_segmentation: 0
     ignore:
       - /pages/en/blog/**/*.mdx
+      - /pages/en/learn/**/*.mdx
       - /pages/en/docs/guides/**/*.mdx
     languages_mapping:
       two_letters_code:

hooks/useNavigation.tsx

@@ -6,6 +6,15 @@ import type { NavigationEntry, NavigationKeys } from '@/types';
 // Translation Context for FormattedMessage
 type Context = Record<string, Record<string, string | JSX.Element | undefined>>;
 
+// These are mapped navigation entries. Navigation Entries can have sub-entries
+type MappedItems = {
+  text: JSX.Element;
+  link: string;
+  key: string;
+  level: number;
+  items: MappedItems[];
+};
+
 // Provides Context replacement for variables within the Link. This is also something that is not going
 // to happen in the future with `nodejs/nodejs.dev` codebase
 const replaceLinkWithContext = (
@@ -24,8 +33,9 @@ const replaceLinkWithContext = (
 export const useNavigation = () => {
   const mapNavigationEntries = (
     entries: Record<string, NavigationEntry>,
-    context?: Context
-  ) => {
+    context?: Context,
+    level = 0
+  ): MappedItems[] => {
     const getContext = (key: string) => (context && context[key]) || {};
 
     const getFormattedMessage = (translationId: string, key: string) => (
@@ -35,20 +45,23 @@ export const useNavigation = () => {
     return Object.entries(entries).map(([key, item]) => ({
       text: getFormattedMessage(item.translationId, key),
       link: replaceLinkWithContext(item.link, getContext(key)),
+      items: item.items
+        ? mapNavigationEntries(item.items, context, level + 1)
+        : [],
+      level,
       key: key,
     }));
   };
 
   return {
     navigationItems: mapNavigationEntries(siteNavigation),
-    getSideNavigation: (section: NavigationKeys, context?: Context) =>
-      mapNavigationEntries(
-        // We need the parent and their items when making a side navigation
-        {
-          [section]: siteNavigation[section],
-          ...siteNavigation[section].items,
-        },
+    getSideNavigation: (section: NavigationKeys, context?: Context) => {
+      const { items, translationId, link } = siteNavigation[section];
+
+      return mapNavigationEntries(
+        { [section]: { translationId, link }, ...items },
         context
-      ),
+      );
+    },
   };
 };

i18n/locales/ar.json

@@ -18,7 +18,7 @@
   "components.navigation.docs.links.es6": "ES6 and beyond",
   "components.navigation.docs.links.apiLts": "{fullLtsNodeVersion} API {spanLts}",
   "components.navigation.docs.links.apiCurrent": "{fullCurrentNodeVersion} API",
-  "components.navigation.docs.links.guides": "Guides",
+  "components.navigation.docs.links.guides": "Guides {spanGuides}",
   "components.navigation.docs.links.dependencies": "Dependencies",
   "components.navigation.getInvolved.links.collabSummit": "Collab Summit",
   "components.navigation.getInvolved.links.contribute": "Contribute",
@@ -69,9 +69,42 @@
   "components.common.card.announcement": "Announcements",
   "components.common.card.release": "Releases",
   "components.common.card.vulnerability": "Vulnerabilities",
-  "components.home.homeDownloadButton.download": "Download {version} {isLts, select, true {lts} other {current}}",
+  "components.home.homeDownloadButton.download": "{version} {isLts, select, true {LTS} other {Current}}",
   "components.home.homeDownloadButton.tagline": "{isLts, select, true {Recommended For Most Users} other {Latest Features}}",
   "components.home.homeDownloadButton.changelog": "Changelog",
   "components.home.homeDownloadButton.otherDownloads": "Other Downloads",
-  "components.home.homeDownloadButton.apiDocs": "API Docs"
+  "components.home.homeDownloadButton.apiDocs": "API Docs",
+  "components.header.links.learn": "Learn",
+  "components.header.links.learn.gettingStarted": "Getting Started",
+  "components.header.links.learn.gettingStarted.introductionToNodejs": "Introduction to Node.js",
+  "components.header.links.learn.gettingStarted.howToInstallNodejs": "How to install Node.js",
+  "components.header.links.learn.gettingStarted.howMuchJavascriptDoYouNeedToKnowToUseNodejs": "How much JavaScript do you need to know to use Node.js?",
+  "components.header.links.learn.gettingStarted.differencesBetweenNodejsAndTheBrowser": "Differences between Node.js and the Browser",
+  "components.header.links.learn.gettingStarted.theV8JavascriptEngine": "The V8 JavaScript Engine",
+  "components.header.links.learn.gettingStarted.anIntroductionToTheNpmPackageManager": "An introduction to the NPM package manager",
+  "components.header.links.learn.gettingStarted.ecmascript2015Es6AndBeyond": "ECMAScript 2015 (ES6) and beyond",
+  "components.header.links.learn.gettingStarted.nodejsTheDifferenceBetweenDevelopmentAndProduction": "Node.js, the difference between development and production",
+  "components.header.links.learn.gettingStarted.nodejsWithTypescript": "Node.js with TypeScript",
+  "components.header.links.learn.gettingStarted.nodejsWithWebassembly": "Node.js with WebAssembly",
+  "components.header.links.learn.asynchronousWork": "Asynchronous Work",
+  "components.header.links.learn.asynchronousWork.asynchronousFlowControl": "Asynchronous flow control",
+  "components.header.links.learn.asynchronousWork.overviewOfBlockingVsNonBlocking": "Overview of Blocking vs Non-Blocking",
+  "components.header.links.learn.asynchronousWork.javascriptAsynchronousProgrammingAndCallbacks": "JavaScript Asynchronous Programming and Callbacks",
+  "components.header.links.learn.asynchronousWork.discoverJavaScriptTimers": "Discover JavaScript Timers",
+  "components.header.links.learn.asynchronousWork.understandingProcessnexttick": "Understanding process.nextTick()",
+  "components.header.links.learn.asynchronousWork.understandingSetimmediate": "Understanding setImmediate()",
+  "components.header.links.learn.asynchronousWork.theNodejsEventEmitter": "The Node.js Event emitter",
+  "components.header.links.learn.manipulatingFiles": "Manipulating Files",
+  "components.header.links.learn.manipulatingFiles.nodejsFileStats": "Node.js file stats",
+  "components.header.links.learn.manipulatingFiles.nodejsFilePaths": "Node.js File Paths",
+  "components.header.links.learn.manipulatingFiles.workingWithFileDescriptorsInNodejs": "Working with file descriptors in Node.js",
+  "components.header.links.learn.manipulatingFiles.readingFilesWithNodejs": "Reading files with Node.js",
+  "components.header.links.learn.manipulatingFiles.writingFilesWithNodejs": "Writing files with Node.js",
+  "components.header.links.learn.manipulatingFiles.workingWithFoldersInNodejs": "Working with folders in Node.js",
+  "components.header.links.learn.commandLine": "Command Line",
+  "components.header.links.learn.commandLine.runNodejsScriptsFromTheCommandLine": "Run Node.js scripts from the command line",
+  "components.header.links.learn.commandLine.howToReadEnvironmentVariablesFromNodejs": "How to read environment variables from Node.js",
+  "components.header.links.learn.commandLine.howToUseTheNodejsRepl": "How to use the Node.js REPL",
+  "components.header.links.learn.commandLine.outputToTheCommandLineUsingNodejs": "Output to the command line using Node.js",
+  "components.header.links.learn.commandLine.acceptInputFromTheCommandLineInNodejs": "Accept input from the command line in Node.js"
 }

i18n/locales/de.json

@@ -18,7 +18,7 @@
   "components.navigation.docs.links.es6": "ES6 and beyond",
   "components.navigation.docs.links.apiLts": "{fullLtsNodeVersion} API {spanLts}",
   "components.navigation.docs.links.apiCurrent": "{fullCurrentNodeVersion} API",
-  "components.navigation.docs.links.guides": "Guides",
+  "components.navigation.docs.links.guides": "Guides {spanGuides}",
   "components.navigation.docs.links.dependencies": "Dependencies",
   "components.navigation.getInvolved.links.collabSummit": "Collab Summit",
   "components.navigation.getInvolved.links.contribute": "Contribute",
@@ -69,9 +69,42 @@
   "components.common.card.announcement": "Announcements",
   "components.common.card.release": "Releases",
   "components.common.card.vulnerability": "Vulnerabilities",
-  "components.home.homeDownloadButton.download": "Download {version} {isLts, select, true {lts} other {current}}",
+  "components.home.homeDownloadButton.download": "{version} {isLts, select, true {LTS} other {Current}}",
   "components.home.homeDownloadButton.tagline": "{isLts, select, true {Recommended For Most Users} other {Latest Features}}",
   "components.home.homeDownloadButton.changelog": "Changelog",
   "components.home.homeDownloadButton.otherDownloads": "Other Downloads",
-  "components.home.homeDownloadButton.apiDocs": "API Docs"
+  "components.home.homeDownloadButton.apiDocs": "API Docs",
+  "components.header.links.learn": "Learn",
+  "components.header.links.learn.gettingStarted": "Getting Started",
+  "components.header.links.learn.gettingStarted.introductionToNodejs": "Introduction to Node.js",
+  "components.header.links.learn.gettingStarted.howToInstallNodejs": "How to install Node.js",
+  "components.header.links.learn.gettingStarted.howMuchJavascriptDoYouNeedToKnowToUseNodejs": "How much JavaScript do you need to know to use Node.js?",
+  "components.header.links.learn.gettingStarted.differencesBetweenNodejsAndTheBrowser": "Differences between Node.js and the Browser",
+  "components.header.links.learn.gettingStarted.theV8JavascriptEngine": "The V8 JavaScript Engine",
+  "components.header.links.learn.gettingStarted.anIntroductionToTheNpmPackageManager": "An introduction to the NPM package manager",
+  "components.header.links.learn.gettingStarted.ecmascript2015Es6AndBeyond": "ECMAScript 2015 (ES6) and beyond",
+  "components.header.links.learn.gettingStarted.nodejsTheDifferenceBetweenDevelopmentAndProduction": "Node.js, the difference between development and production",
+  "components.header.links.learn.gettingStarted.nodejsWithTypescript": "Node.js with TypeScript",
+  "components.header.links.learn.gettingStarted.nodejsWithWebassembly": "Node.js with WebAssembly",
+  "components.header.links.learn.asynchronousWork": "Asynchronous Work",
+  "components.header.links.learn.asynchronousWork.asynchronousFlowControl": "Asynchronous flow control",
+  "components.header.links.learn.asynchronousWork.overviewOfBlockingVsNonBlocking": "Overview of Blocking vs Non-Blocking",
+  "components.header.links.learn.asynchronousWork.javascriptAsynchronousProgrammingAndCallbacks": "JavaScript Asynchronous Programming and Callbacks",
+  "components.header.links.learn.asynchronousWork.discoverJavaScriptTimers": "Discover JavaScript Timers",
+  "components.header.links.learn.asynchronousWork.understandingProcessnexttick": "Understanding process.nextTick()",
+  "components.header.links.learn.asynchronousWork.understandingSetimmediate": "Understanding setImmediate()",
+  "components.header.links.learn.asynchronousWork.theNodejsEventEmitter": "The Node.js Event emitter",
+  "components.header.links.learn.manipulatingFiles": "Manipulating Files",
+  "components.header.links.learn.manipulatingFiles.nodejsFileStats": "Node.js file stats",
+  "components.header.links.learn.manipulatingFiles.nodejsFilePaths": "Node.js File Paths",
+  "components.header.links.learn.manipulatingFiles.workingWithFileDescriptorsInNodejs": "Working with file descriptors in Node.js",
+  "components.header.links.learn.manipulatingFiles.readingFilesWithNodejs": "Reading files with Node.js",
+  "components.header.links.learn.manipulatingFiles.writingFilesWithNodejs": "Writing files with Node.js",
+  "components.header.links.learn.manipulatingFiles.workingWithFoldersInNodejs": "Working with folders in Node.js",
+  "components.header.links.learn.commandLine": "Command Line",
+  "components.header.links.learn.commandLine.runNodejsScriptsFromTheCommandLine": "Run Node.js scripts from the command line",
+  "components.header.links.learn.commandLine.howToReadEnvironmentVariablesFromNodejs": "How to read environment variables from Node.js",
+  "components.header.links.learn.commandLine.howToUseTheNodejsRepl": "How to use the Node.js REPL",
+  "components.header.links.learn.commandLine.outputToTheCommandLineUsingNodejs": "Output to the command line using Node.js",
+  "components.header.links.learn.commandLine.acceptInputFromTheCommandLineInNodejs": "Accept input from the command line in Node.js"
 }

i18n/locales/en.json

@@ -18,7 +18,7 @@
   "components.navigation.docs.links.es6": "ES6 and beyond",
   "components.navigation.docs.links.apiLts": "{fullLtsNodeVersion} API {spanLts}",
   "components.navigation.docs.links.apiCurrent": "{fullCurrentNodeVersion} API",
-  "components.navigation.docs.links.guides": "Guides",
+  "components.navigation.docs.links.guides": "Guides {spanGuides}",
   "components.navigation.docs.links.dependencies": "Dependencies",
   "components.navigation.getInvolved.links.collabSummit": "Collab Summit",
   "components.navigation.getInvolved.links.contribute": "Contribute",
@@ -69,9 +69,42 @@
   "components.common.card.announcement": "Announcements",
   "components.common.card.release": "Releases",
   "components.common.card.vulnerability": "Vulnerabilities",
-  "components.home.homeDownloadButton.download": "Download {version} {isLts, select, true {lts} other {current}}",
+  "components.home.homeDownloadButton.download": "{version} {isLts, select, true {LTS} other {Current}}",
   "components.home.homeDownloadButton.tagline": "{isLts, select, true {Recommended For Most Users} other {Latest Features}}",
   "components.home.homeDownloadButton.changelog": "Changelog",
   "components.home.homeDownloadButton.otherDownloads": "Other Downloads",
-  "components.home.homeDownloadButton.apiDocs": "API Docs"
+  "components.home.homeDownloadButton.apiDocs": "API Docs",
+  "components.header.links.learn": "Learn",
+  "components.header.links.learn.gettingStarted": "Getting Started",
+  "components.header.links.learn.gettingStarted.introductionToNodejs": "Introduction to Node.js",
+  "components.header.links.learn.gettingStarted.howToInstallNodejs": "How to install Node.js",
+  "components.header.links.learn.gettingStarted.howMuchJavascriptDoYouNeedToKnowToUseNodejs": "How much JavaScript do you need to know to use Node.js?",
+  "components.header.links.learn.gettingStarted.differencesBetweenNodejsAndTheBrowser": "Differences between Node.js and the Browser",
+  "components.header.links.learn.gettingStarted.theV8JavascriptEngine": "The V8 JavaScript Engine",
+  "components.header.links.learn.gettingStarted.anIntroductionToTheNpmPackageManager": "An introduction to the NPM package manager",
+  "components.header.links.learn.gettingStarted.ecmascript2015Es6AndBeyond": "ECMAScript 2015 (ES6) and beyond",
+  "components.header.links.learn.gettingStarted.nodejsTheDifferenceBetweenDevelopmentAndProduction": "Node.js, the difference between development and production",
+  "components.header.links.learn.gettingStarted.nodejsWithTypescript": "Node.js with TypeScript",
+  "components.header.links.learn.gettingStarted.nodejsWithWebassembly": "Node.js with WebAssembly",
+  "components.header.links.learn.asynchronousWork": "Asynchronous Work",
+  "components.header.links.learn.asynchronousWork.asynchronousFlowControl": "Asynchronous flow control",
+  "components.header.links.learn.asynchronousWork.overviewOfBlockingVsNonBlocking": "Overview of Blocking vs Non-Blocking",
+  "components.header.links.learn.asynchronousWork.javascriptAsynchronousProgrammingAndCallbacks": "JavaScript Asynchronous Programming and Callbacks",
+  "components.header.links.learn.asynchronousWork.discoverJavaScriptTimers": "Discover JavaScript Timers",
+  "components.header.links.learn.asynchronousWork.understandingProcessnexttick": "Understanding process.nextTick()",
+  "components.header.links.learn.asynchronousWork.understandingSetimmediate": "Understanding setImmediate()",
+  "components.header.links.learn.asynchronousWork.theNodejsEventEmitter": "The Node.js Event emitter",
+  "components.header.links.learn.manipulatingFiles": "Manipulating Files",
+  "components.header.links.learn.manipulatingFiles.nodejsFileStats": "Node.js file stats",
+  "components.header.links.learn.manipulatingFiles.nodejsFilePaths": "Node.js File Paths",
+  "components.header.links.learn.manipulatingFiles.workingWithFileDescriptorsInNodejs": "Working with file descriptors in Node.js",
+  "components.header.links.learn.manipulatingFiles.readingFilesWithNodejs": "Reading files with Node.js",
+  "components.header.links.learn.manipulatingFiles.writingFilesWithNodejs": "Writing files with Node.js",
+  "components.header.links.learn.manipulatingFiles.workingWithFoldersInNodejs": "Working with folders in Node.js",
+  "components.header.links.learn.commandLine": "Command Line",
+  "components.header.links.learn.commandLine.runNodejsScriptsFromTheCommandLine": "Run Node.js scripts from the command line",
+  "components.header.links.learn.commandLine.howToReadEnvironmentVariablesFromNodejs": "How to read environment variables from Node.js",
+  "components.header.links.learn.commandLine.howToUseTheNodejsRepl": "How to use the Node.js REPL",
+  "components.header.links.learn.commandLine.outputToTheCommandLineUsingNodejs": "Output to the command line using Node.js",
+  "components.header.links.learn.commandLine.acceptInputFromTheCommandLineInNodejs": "Accept input from the command line in Node.js"
 }