Docusaurus version of docs pages

.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://goharbor.io/> (logo wall)
-- <https://blog.rook.io/> (blog)
+- https://www.fluentd.org/testimonials (user testimonials)
+- https://goharbor.io/ (logo wall)
+- 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
-`00NN-project`.
+here: https://github.com/cncf/techdocs/tree/main/analyses under `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;