From 1a6925862c6fdad95d9e8c1b9503ab2470053bf5 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 17 Mar 2025 11:10:44 -0400 Subject: [PATCH] Docusaurus version of docs pages Signed-off-by: Patrice Chalin --- .gitignore | 5 ++ .markdown-link-check.json | 2 +- .markdownlint.yaml | 1 + docs/analysis/criteria.md | 28 +++---- docs/analysis/templates/analysis.md | 2 +- docs/analysis/templates/implementation.md | 2 +- docs/analysis/templates/issue.md | 5 +- docs/analysis/templates/issues-list.md | 6 +- docs/analytics.md | 2 +- docs/repo-setup.md | 2 +- docs/versioning-documentation.md | 6 +- docusaurus.config.ts | 90 ++++++++++++++++++++++ package.json | 27 ++++++- sidebars.ts | 33 ++++++++ src/css/custom.css | 30 ++++++++ src/pages/index.mdx | 3 + static/img/cncf-icon-color.svg | 19 +++++ static/img/favicon.ico | Bin 0 -> 15086 bytes tsconfig.json | 8 ++ 19 files changed, 241 insertions(+), 30 deletions(-) create mode 100644 docusaurus.config.ts create mode 100644 sidebars.ts create mode 100644 src/css/custom.css create mode 100644 src/pages/index.mdx create mode 100644 static/img/cncf-icon-color.svg create mode 100644 static/img/favicon.ico create mode 100644 tsconfig.json diff --git a/.gitignore b/.gitignore index 7807fd3a..5e24fb0d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,8 @@ +# Docusaurus - cSpell:disable-next-line +.docusaurus +.cache-loader +/build + # npm assets node_modules/ package-lock.json diff --git a/.markdown-link-check.json b/.markdown-link-check.json index 63569567..b595fbad 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -15,5 +15,5 @@ ], "timeout": "3s", "retryOn429": true, - "aliveStatusCodes": [200, 206] + "aliveStatusCodes": [200, 202, 206] } diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 6eb808e6..4a8c5893 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -3,3 +3,4 @@ list-marker-space: false no-inline-html: false +no-bare-urls: false diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 51c78708..8ce51070 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -40,7 +40,7 @@ We evaluate on the following: Example: -- +- https://prometheus.io/docs ### New user content @@ -66,7 +66,7 @@ We evaluate on the following: Example: -- +- https://falco.org/docs/getting-started/ ### Content maintainability & site mechanics @@ -90,7 +90,7 @@ We evaluate on the following: Example: -- +- https://kubernetes.io/docs/ ### Content creation processes @@ -107,9 +107,9 @@ We evaluate on the following: Examples: -- (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 ### Inclusive language @@ -140,7 +140,7 @@ We evaluate on the following: Example: -- +- https://prometheus.io/community/ ### Beginner friendly issue backlog @@ -154,7 +154,7 @@ We evaluate on the following: Example: -- (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 ### Project governance documentation @@ -184,7 +184,7 @@ We evaluate on the following: Example: -- +- https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md ## Website @@ -327,7 +327,7 @@ We evaluate on the following: Example: -- +- https://helm.sh/ ### Case studies/social proof @@ -345,9 +345,9 @@ We evaluate on the following: Examples: -- (user testimonials) -- (logo wall) -- (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 ### Other diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 524a7eef..55810114 100644 --- a/docs/analysis/templates/analysis.md +++ b/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_) diff --git a/docs/analysis/templates/implementation.md b/docs/analysis/templates/implementation.md index 0c894201..c4c7f055 100644 --- a/docs/analysis/templates/implementation.md +++ b/docs/analysis/templates/implementation.md @@ -1,6 +1,6 @@ --- title: Implementing _PROJECT_ Doc Improvements -tags: _PROJECT_ +tags: [_PROJECT_] --- diff --git a/docs/analysis/templates/issue.md b/docs/analysis/templates/issue.md index a1d81d0e..b3da121d 100644 --- a/docs/analysis/templates/issue.md +++ b/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: under -`00NN-project`. +here: https://github.com/cncf/techdocs/tree/main/analyses under `00NN-project`. ## Possible Implementation diff --git a/docs/analysis/templates/issues-list.md b/docs/analysis/templates/issues-list.md index 49c87426..89c251c1 100644 --- a/docs/analysis/templates/issues-list.md +++ b/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: 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 ## Umbrella issue diff --git a/docs/analytics.md b/docs/analytics.md index 2e7d5e76..6ece103d 100644 --- a/docs/analytics.md +++ b/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.
This will open an analytics console onto your GA4 + of your UA property.
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. diff --git a/docs/repo-setup.md b/docs/repo-setup.md index f3ee269a..e58fb202 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -1,5 +1,5 @@ --- -cSpell:ignore cncf +cSpell:ignore: cncf --- # Repository setup diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index 5acdc303..2a17b221 100644 --- a/docs/versioning-documentation.md +++ b/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 ```html
+https://github.com/kubernetes/website/blob/main/hugo.toml ```toml [[params.versions]] diff --git a/docusaurus.config.ts b/docusaurus.config.ts new file mode 100644 index 00000000..d82780fe --- /dev/null +++ b/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; diff --git a/package.json b/package.json index 1bf1be2c..fa7cfe8a 100644 --- a/package.json +++ b/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 -", diff --git a/sidebars.ts b/sidebars.ts new file mode 100644 index 00000000..df293d74 --- /dev/null +++ b/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; diff --git a/src/css/custom.css b/src/css/custom.css new file mode 100644 index 00000000..2bc6a4cf --- /dev/null +++ b/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); +} diff --git a/src/pages/index.mdx b/src/pages/index.mdx new file mode 100644 index 00000000..28955ddb --- /dev/null +++ b/src/pages/index.mdx @@ -0,0 +1,3 @@ +import README from '../../README.md'; + + diff --git a/static/img/cncf-icon-color.svg b/static/img/cncf-icon-color.svg new file mode 100644 index 00000000..3000a4fd --- /dev/null +++ b/static/img/cncf-icon-color.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + diff --git a/static/img/favicon.ico b/static/img/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..a68a7ca9b9e0e54a8b3b526c46a5189b8f1b18f6 GIT binary patch literal 15086 zcmeHOF>4%06ni}nVZ|0*_qj$z0n<5xA1tkGxOf}?VH)R z?`H1+)*yqMH-U5)etsX|BLL`jr{~uJUQ*k2(%k>WHGmx&@Bxh>6WAu<_SLb9z-31O zcVHAP-@p3|&-O>r^4GV|qOq9YE^|K3Ix^MjQ_g)u$^3Pz4?(M_M{r!5-3;O&Tww?EPi}?HURb9KdCJ*;o+g;dN zCV#=5V{GSEYOCYU{WLdA<3BI=W%5tKeOdfdabE`il-w81KQ;H({JAFNy2=vvS9geO zu$}>RHlcnzd-%lWAkX zCRw-A`s5ht63>6p+{JaJb&6-yYZGd>-!Xf0_K}<-Sb* zDY!3-e=6?F;GdHFqWP!ho|?bN1-zfch4zDGpL_qXMgDZ< z)LGl2-(Rfwo6qM}{LOgOy+3-B*AKm$q5JYMT4es=926&QumbOoIPb2GRRm%pfa0Kf z+tMfOWE~({=NH+8?efXG)aM-#yLu>LZ~ zA?xiNd#tx|1lE8T*I2LN6b3*Ha_jjtccFkWK|C;40x@iq=8`!kB?XnYm%=I-lep77b zlNvt;J2ieRc4PcM?-!^E+qn*j&+|^wV84-lh_RY)EIxZ=`!3g!e5X_GCp^#kvd8M@ zX1t_t!m6%6D~~ySMB;m}F$Ul85rJ>mS=ZJS-}FJbr6GRB&d3vD4r=3H@zEBW?56ub z9CsxR@YUGn*Uf8&_w*%BY1baV^r5fE&}WHn+O@+seS|ReJ~40BTs6Yi^8I&Zp0Q$K$MU*nz%&sA#t%5~Q~2U6n4VvAUD zJrr4g2+npLWyE}dV(r;AnQf!aWAV-LvNpd;_3z@Ze{tWx0(*_FJo6^E$^8PvAwXtJ zanb1)lZ}3HzS%FvISKZQW6X-Zi>&BOvZtN%Y`8JbhMVL5F#oqd#Q*w7NH&(8?U&CL zF7H#&U(Cc_#bxhPSUCvs;NwE8Nn~yE(~Vjv`F#Ptqjs972a@srMCom<}p&k!0e?0z|4-b@o zwSLrjY0I%F=U%kC=5LylmAw|L*}9qa1?&}%7VF>4(c=DL?wZi`l7C~I;xvy&1n8|v jdHgoOqgy0*0S2!C`bPk}BzwODJmz+iAE-}_XWRb)Px+3q literal 0 HcmV?d00001 diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..920d7a65 --- /dev/null +++ b/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"] +}