diff --git a/.gitignore b/.gitignore index 7807fd3..5e24fb0 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 6356956..b595fba 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 6eb808e..4a8c589 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 51c7870..8ce5107 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 524a7ee..5581011 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 0c89420..c4c7f05 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 a1d81d0..b3da121 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 49c8742..89c251c 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 2e7d5e7..6ece103 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 f3ee269..e58fb20 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 5acdc30..2a17b22 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 0000000..d82780f --- /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 1bf1be2..fa7cfe8 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 0000000..df293d7 --- /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 0000000..2bc6a4c --- /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 0000000..28955dd --- /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 0000000..3000a4f --- /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 0000000..a68a7ca Binary files /dev/null and b/static/img/favicon.ico differ diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..920d7a6 --- /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"] +}