Docusaurus version of docs pages (#301)

.gitignore

@@ -1,3 +1,8 @@
+# Docusaurus - cSpell:disable-next-line
+.docusaurus
+.cache-loader
+/build
+
 # npm assets
 node_modules/
 package-lock.json

.markdown-link-check.json

@@ -15,5 +15,5 @@
   ],
   "timeout": "3s",
   "retryOn429": true,
-  "aliveStatusCodes": [200, 206]
+  "aliveStatusCodes": [200, 202, 206]
 }

.markdownlint.yaml

@@ -3,3 +3,4 @@
 
 list-marker-space: false
 no-inline-html: false
+no-bare-urls: false

docs/analysis/criteria.md

@@ -40,7 +40,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://prometheus.io/docs>
+- https://prometheus.io/docs
 
 ### New user content
 
@@ -66,7 +66,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://falco.org/docs/getting-started/>
+- https://falco.org/docs/getting-started/
 
 ### Content maintainability & site mechanics
 
@@ -90,7 +90,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://kubernetes.io/docs/>
+- https://kubernetes.io/docs/
 
 ### Content creation processes
 
@@ -107,9 +107,9 @@ We evaluate on the following:
 
 Examples:
 
-- <https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md> (clearly
+- https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly
   documented maintainers)
-- <https://thanos.io/tip/contributing/how-to-contribute-to-docs.md>
+- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md
 
 ### Inclusive language
 
@@ -140,7 +140,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://prometheus.io/community/>
+- https://prometheus.io/community/
 
 ### Beginner friendly issue backlog
 
@@ -154,7 +154,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://github.com/opentracing/opentracing.io/issues> (all of open tracing’s
+- https://github.com/opentracing/opentracing.io/issues (all of open tracing’s
   backlogs are well maintained!)
 
 ### New contributor getting started content
@@ -172,7 +172,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://github.com/helm/community>
+- https://github.com/helm/community
 
 ### Project governance documentation
 
@@ -184,7 +184,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md>
+- https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md
 
 ## Website
 
@@ -327,7 +327,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://helm.sh/>
+- https://helm.sh/
 
 ### Case studies/social proof
 
@@ -345,9 +345,9 @@ We evaluate on the following:
 
 Examples:
 
-- <https://www.fluentd.org/testimonials> (user testimonials)
+- https://www.fluentd.org/testimonials (user testimonials)
-- <https://goharbor.io/> (logo wall)
+- https://goharbor.io/ (logo wall)
-- <https://blog.rook.io/> (blog)
+- https://blog.rook.io/ (blog)
 
 ### SEO, Analytics and site-local search
 
@@ -385,7 +385,7 @@ We evaluate on the following:
 
 Example:
 
-- <https://kubernetes.io>
+- https://kubernetes.io
 
 ### Other
 

docs/analysis/templates/analysis.md

@@ -1,6 +1,6 @@
 ---
 title: _PROJECT_ Documentation Analysis
-tags: _PROJECT_
+tags: [_PROJECT_]
 created: YYYY-MM-DD
 modified: YYYY-MM-DD
 author: _NAME_ (@_HANDLE_)

docs/analysis/templates/implementation.md

@@ -1,6 +1,6 @@
 ---
 title: Implementing _PROJECT_ Doc Improvements
-tags: _PROJECT_
+tags: [_PROJECT_]
 ---
 
 <!-- markdownlint-disable no-duplicate-heading -->

docs/analysis/templates/issue.md

@@ -1,6 +1,6 @@
 ---
 title: _PROJECT_ Issue
-tags: _PROJECT_
+tags: [_PROJECT_]
 ---
 
 > AUTHOR NOTE: This template provides one possible format for the individual
@@ -29,8 +29,7 @@ Type:
 
 This issue tracks recommended changes resulting from an analysis of the etcd
 documentation commissioned by CNCF. The analysis and supporting documents are
-here: <https://github.com/cncf/techdocs/tree/main/analyses> under
+here: https://github.com/cncf/techdocs/tree/main/analyses under `00NN-project`.
-`00NN-project`.
 
 ## Possible Implementation
 

docs/analysis/templates/issues-list.md

@@ -1,6 +1,6 @@
 ---
 title: _PROJECT_ Umbrella Issue and Issues List
-tags: _PROJECT_
+tags: [_PROJECT_]
 ---
 
 ## Overview
@@ -21,11 +21,11 @@ tags: _PROJECT_
 
 This issue tracks recommended changes resulting from an analysis of the
 _PROJECT_ documentation commissioned by CNCF. The analysis and supporting
-documents are here: <https://github.com/cncf/techdocs/tree/main/analyses> under
+documents are here: https://github.com/cncf/techdocs/tree/main/analyses under
 `00NN-project`.
 
 The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo:
-<https://github.com/cncf/techdocs/issues>
+https://github.com/cncf/techdocs/issues
 
 ## Umbrella issue
 

docs/analytics.md

@@ -93,7 +93,7 @@ Follow these steps:
     measurement ID. Continuing from the previous step:
 
     - Select **Go to your GA4 property** from the **GA4 Setup Assistant** view
-      of your UA property.<br> This will open an analytics console onto your GA4
+      of your UA property.<br/>This will open an analytics console onto your GA4
       site tag. Perform the remaining steps from your GA4 console.
     - Select **Admin** > **Data stream**
     - Select the (only) data stream to view its details.

docs/repo-setup.md

@@ -1,5 +1,5 @@
 ---
-cSpell:ignore cncf
+cSpell:ignore: cncf
 ---
 
 # Repository setup

docs/versioning-documentation.md

@@ -1,6 +1,6 @@
 ---
 # prettier-ignore
-cSpell:ignore Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi
+cSpell:ignore: Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi
 ---
 
 # Technical Documentation Versioning with Hugo & Netlify
@@ -161,7 +161,7 @@ Scores high on:
 
 Same style of dropdown function as above, but made simpler because of the
 configuration:
-<https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html>
+https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html
 
 ```html
 <div
@@ -181,7 +181,7 @@ Pursley et al. (2020, L4-L9)[^4]
 The dropdown example is made simpler because the config is more complex and
 because the server setup is more complex.
 
-<https://github.com/kubernetes/website/blob/main/hugo.toml>
+https://github.com/kubernetes/website/blob/main/hugo.toml
 
 ```toml
 [[params.versions]]

docusaurus.config.ts

@@ -0,0 +1,90 @@
+// cSpell:ignore cncf
+
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const title = 'CNCF TechDocs';
+const repo = 'https://github.com/cncf/techdocs';
+
+const config: Config = {
+  title,
+  // tagline: '',
+  favicon:
+    'https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico', // TODO: localize?
+
+  // Production URL:
+  url: 'https://techdocs.netlify.app/', // TODO
+  baseUrl: '/',
+
+  // GitHub pages deployment config. TODO: this still useful?
+  organizationName: 'cncf',
+  projectName: 'techdocs',
+
+  onBrokenLinks: 'warn', // TODO: 'error' or 'throw' once we've fixed all links
+  onBrokenMarkdownLinks: 'warn',
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          editUrl: `${repo}/tree/main`,
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    // TODO: Replace with your project's social card
+    // image: 'img/docusaurus-social-card.jpg',
+    navbar: {
+      title,
+      logo: {
+        alt: 'Logo',
+        src: 'img/cncf-icon-color.svg',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'docSidebar',
+          position: 'left',
+          label: 'Docs',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          label: 'Privacy',
+          href: 'https://www.linuxfoundation.org/legal/privacy-policy',
+        },
+        {
+          label: 'Trademarks',
+          href: 'https://www.linuxfoundation.org/legal/trademark-usage',
+        },
+        {
+          label: 'GitHub',
+          href: repo,
+        },
+      ],
+      copyright: `Copyright © ${title} Authors ${new Date().getFullYear()} `,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

package.json

@@ -24,18 +24,41 @@
     "fix": "npm run seq -- $(npm -s run _list:fix:*)",
     "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ",
     "test": "npm run check",
-    "update:pkgs": "npx npm-check-updates -u"
+    "update:pkgs": "npx npm-check-updates -u",
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc"
   },
   "author": "CNCF",
   "license": "CC-BY-4.0",
   "NOTE": "We've pinned markdown-link-check to 3.12.2 due to a bug in 3.13.x stream, both in the devDeps below and the check:links script above. For details, see https://github.com/tcort/markdown-link-check/issues/369.",
+  "dependencies": {
+    "@docusaurus/core": "3.7.0",
+    "@docusaurus/preset-classic": "3.7.0",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
   "devDependencies": {
     "cspell": "^8.17.5",
     "markdown-link-check": "3.12.2",
     "markdownlint": "^0.37.4",
     "markdownlint-cli": "^0.44.0",
     "npm-check-updates": "^17.1.15",
-    "prettier": "^3.5.2"
+    "prettier": "^3.5.2",
+    "@docusaurus/module-type-aliases": "3.7.0",
+    "@docusaurus/tsconfig": "3.7.0",
+    "@docusaurus/types": "3.7.0",
+    "typescript": "~5.6.2"
   },
   "private": true,
   "spelling": "cSpell:ignore ACMR loglevel pkgs -",

sidebars.ts

@@ -0,0 +1,33 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+const sidebars: SidebarsConfig = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  docSidebar: [{ type: 'autogenerated', dirName: '.' }],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+export default sidebars;

src/css/custom.css

@@ -0,0 +1,30 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

src/pages/index.mdx

@@ -0,0 +1,3 @@
+import README from '../../README.md';
+
+<README />

static/img/cncf-icon-color.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 26.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="a" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 389 389" style="enable-background:new 0 0 389 389;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#0086FF;}
+	.st1{fill:#93EAFF;}
+</style>
+<g>
+	<path class="st0" d="M72.8,250.7h-48v112.6h112.2v-48.4H72.8V250.7z"/>
+	<path class="st0" d="M314.1,251.2v63.7h-64.3v48.4h112.2V250.7h-48.5L314.1,251.2z"/>
+	<path class="st0" d="M24.9,138.6h48.5l-0.5-0.5V74.5h64.3V26H24.9V138.6z"/>
+	<path class="st0" d="M249.9,26v48.4h64.3v64.2h48V26C362.1,26,249.9,26,249.9,26z"/>
+	<path class="st1" d="M243.5,138.6l-64.3-64.2h70.6V26H137.1v48.4l64.3,64.2H243.5z"/>
+	<path class="st1" d="M185.6,250.7h-42.2l53.2,53.2l10.5,11h-70.1v48.4h112.8v-49l-32.1-31.6L185.6,250.7z"/>
+	<path class="st1" d="M314.1,138.6v70l-11.1-11.1l-53.2-53.2V187l31.6,31.6l32.1,32.1h48.5V138.6H314.1L314.1,138.6z"/>
+	<path class="st1" d="M137.1,202.3l-63.8-63.7H24.9v112h48v-70l64.3,64.2V202.3z"/>
+</g>
+</svg>

tsconfig.json

@@ -0,0 +1,8 @@
+{
+  // This file is not used in compilation. It is here just for a nice editor experience.
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "exclude": [".docusaurus", "build"]
+}