From f2751a63cca2cc9c93e5250532d4e18a3d4e22e7 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker Date: Fri, 15 Aug 2025 10:48:55 -0700 Subject: [PATCH] feat: use Docusaurus for docs site This is an experimental start of a documentation site for the CVE Record Format, built using Docusaurus. For now all I've done is started with the initial default template, deleted extra things we wouldn't use, and filled in some basic text and configuration. It'll need a lot more work on content before being ready to publish. Signed-off-by: Andrew Lilley Brinker --- site/.gitignore | 20 +++ site/README.md | 45 +++++++ .../2025-08-15-cve-record-format-blog.mdx | 8 ++ site/blog/authors.yml | 5 + site/blog/tags.yml | 9 ++ site/docs/concepts/_category_.json | 8 ++ site/docs/concepts/versions.md | 0 site/docs/intro.md | 5 + site/docusaurus.config.ts | 123 ++++++++++++++++++ site/package.json | 47 +++++++ site/sidebars.ts | 33 +++++ .../src/components/HomepageFeatures/index.tsx | 64 +++++++++ .../HomepageFeatures/styles.module.css | 6 + site/src/css/custom.css | 34 +++++ site/src/pages/index.module.css | 23 ++++ site/src/pages/index.tsx | 37 ++++++ site/static/.nojekyll | 0 site/tsconfig.json | 8 ++ 18 files changed, 475 insertions(+) create mode 100644 site/.gitignore create mode 100644 site/README.md create mode 100644 site/blog/2025-08-15-cve-record-format-blog.mdx create mode 100644 site/blog/authors.yml create mode 100644 site/blog/tags.yml create mode 100644 site/docs/concepts/_category_.json create mode 100644 site/docs/concepts/versions.md create mode 100644 site/docs/intro.md create mode 100644 site/docusaurus.config.ts create mode 100644 site/package.json create mode 100644 site/sidebars.ts create mode 100644 site/src/components/HomepageFeatures/index.tsx create mode 100644 site/src/components/HomepageFeatures/styles.module.css create mode 100644 site/src/css/custom.css create mode 100644 site/src/pages/index.module.css create mode 100644 site/src/pages/index.tsx create mode 100644 site/static/.nojekyll create mode 100644 site/tsconfig.json diff --git a/site/.gitignore b/site/.gitignore new file mode 100644 index 00000000000..b2d6de30624 --- /dev/null +++ b/site/.gitignore @@ -0,0 +1,20 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/site/README.md b/site/README.md new file mode 100644 index 00000000000..b04de422f74 --- /dev/null +++ b/site/README.md @@ -0,0 +1,45 @@ +# CVE Record Format Site + +This is the website for the CVE Record Format, which hosts documentation for +how to understand and use the format to create and interpret CVE Records. + +The site is built using [Docusaurus], a static website generator. + +## Installation + +```bash +npm install +``` + +## Local Development + +```bash +npx docusaurus start +``` + +This command starts a local development server and opens up a browser window. +Most changes are reflected live without having to restart the server. + +## Build + +```bash +npx docusaurus build +``` + +This command generates static content into the `build` directory. + +## Deployment + +Using SSH: + +```bash +USE_SSH=true npx docusaurus deploy +``` + +Not using SSH: + +```bash +GIT_USER= npx docusaurus deploy +``` + +[Docusaurus]: https://docusaurus.io/ diff --git a/site/blog/2025-08-15-cve-record-format-blog.mdx b/site/blog/2025-08-15-cve-record-format-blog.mdx new file mode 100644 index 00000000000..4b0a7e0cf03 --- /dev/null +++ b/site/blog/2025-08-15-cve-record-format-blog.mdx @@ -0,0 +1,8 @@ +--- +slug: blog-announcement +title: The CVE Record Format Blog is Alive! +authors: [ccoffin] +tags: [meta] +--- + +Test. diff --git a/site/blog/authors.yml b/site/blog/authors.yml new file mode 100644 index 00000000000..0962bc5b0dc --- /dev/null +++ b/site/blog/authors.yml @@ -0,0 +1,5 @@ +ccoffin: + name: Chris Coffin + title: QWG Co-Chair (MITRE) + url: https://github.com/ccoffin + page: true diff --git a/site/blog/tags.yml b/site/blog/tags.yml new file mode 100644 index 00000000000..deaea06a319 --- /dev/null +++ b/site/blog/tags.yml @@ -0,0 +1,9 @@ +release: + label: Release + permalink: /release + description: Announcements for new releases of the CVE Record Format + +meta: + label: Meta + permalink: /meta + description: Posts about the blog itself diff --git a/site/docs/concepts/_category_.json b/site/docs/concepts/_category_.json new file mode 100644 index 00000000000..034fcf0bf43 --- /dev/null +++ b/site/docs/concepts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Concepts", + "position": 2, + "link": { + "type": "generated-index", + "description": "Key concepts important to understand for the CVE Schema." + } +} diff --git a/site/docs/concepts/versions.md b/site/docs/concepts/versions.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/site/docs/intro.md b/site/docs/intro.md new file mode 100644 index 00000000000..4a9105c5a59 --- /dev/null +++ b/site/docs/intro.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# Introduction diff --git a/site/docusaurus.config.ts b/site/docusaurus.config.ts new file mode 100644 index 00000000000..2daaf185ae5 --- /dev/null +++ b/site/docusaurus.config.ts @@ -0,0 +1,123 @@ +import { themes as prismThemes } from "prism-react-renderer"; +import type { Config } from "@docusaurus/types"; +import type * as Preset from "@docusaurus/preset-classic"; + +// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) + +const config: Config = { + title: "CVE Record Format", + tagline: "Documentation for creating and using CVE Records", + favicon: "img/favicon.ico", + + // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future + future: { + v4: true, // Improve compatibility with the upcoming Docusaurus v4 + }, + + // Set the production url of your site here + url: "https://cveproject.github.io", + // Set the // pathname under which your site is served + // For GitHub pages deployment, it is often '//' + baseUrl: "/cve-schema", + + // GitHub pages deployment config. + // If you aren't using GitHub pages, you don't need these. + organizationName: "cveproject", // Usually your GitHub org/user name. + projectName: "cve-schema", // Usually your repo name. + + onBrokenLinks: "throw", + onBrokenMarkdownLinks: "warn", + + // Even if you don't use internationalization, you can use this field to set + // useful metadata like html lang. For example, if your site is Chinese, you + // may want to replace "en" with "zh-Hans". + i18n: { + defaultLocale: "en", + locales: ["en"], + }, + + presets: [ + [ + "classic", + { + docs: { + sidebarPath: "./sidebars.ts", + // Please change this to your repo. + // Remove this to remove the "edit this page" links. + editUrl: + "https://github.com/cveproject/cve-schema/tree/main/site/docs/", + }, + blog: { + showReadingTime: true, + feedOptions: { + type: ["rss", "atom"], + xslt: true, + }, + // Useful options to enforce blogging best practices + onInlineTags: "warn", + onInlineAuthors: "warn", + onUntruncatedBlogPosts: "warn", + }, + theme: { + customCss: "./src/css/custom.css", + }, + } satisfies Preset.Options, + ], + ], + + themeConfig: { + // Replace with your project's social card + image: "img/docusaurus-social-card.jpg", + navbar: { + title: "CVE Schema", + items: [ + { + type: "docSidebar", + sidebarId: "tutorialSidebar", + position: "left", + label: "Tutorial", + }, + { to: "/blog", label: "Blog", position: "left" }, + { + href: "https://github.com/cveproject/cve-schema", + label: "GitHub", + position: "right", + }, + ], + }, + footer: { + style: "dark", + links: [ + { + title: "Docs", + items: [ + { + label: "Guides", + to: "/docs/intro", + }, + ], + }, + { + title: "More", + items: [ + { + label: "Blog", + to: "/blog", + }, + { + label: "GitHub", + href: "https://github.com/cveproject/cve-schema", + }, + ], + }, + ], + copyright: `Copyright © ${new Date().getFullYear()} CVE Project`, + }, + prism: { + theme: prismThemes.github, + darkTheme: prismThemes.dracula, + }, + } satisfies Preset.ThemeConfig, +}; + +export default config; diff --git a/site/package.json b/site/package.json new file mode 100644 index 00000000000..fd50269777a --- /dev/null +++ b/site/package.json @@ -0,0 +1,47 @@ +{ + "name": "site", + "version": "0.0.0", + "private": true, + "scripts": { + "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" + }, + "dependencies": { + "@docusaurus/core": "3.8.1", + "@docusaurus/preset-classic": "3.8.1", + "@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": { + "@docusaurus/module-type-aliases": "3.8.1", + "@docusaurus/tsconfig": "3.8.1", + "@docusaurus/types": "3.8.1", + "typescript": "~5.6.2" + }, + "browserslist": { + "production": [ + ">0.5%", + "not dead", + "not op_mini all" + ], + "development": [ + "last 3 chrome version", + "last 3 firefox version", + "last 5 safari version" + ] + }, + "engines": { + "node": ">=18.0" + } +} diff --git a/site/sidebars.ts b/site/sidebars.ts new file mode 100644 index 00000000000..289713975cd --- /dev/null +++ b/site/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 + tutorialSidebar: [{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/site/src/components/HomepageFeatures/index.tsx b/site/src/components/HomepageFeatures/index.tsx new file mode 100644 index 00000000000..76b146c826c --- /dev/null +++ b/site/src/components/HomepageFeatures/index.tsx @@ -0,0 +1,64 @@ +import type { ReactNode } from "react"; +import clsx from "clsx"; +import Heading from "@theme/Heading"; +import styles from "./styles.module.css"; + +type FeatureItem = { + title: string; + description: ReactNode; +}; + +const FeatureList: FeatureItem[] = [ + { + title: "Uses JSON Schema", + description: ( + <> + The CVE Record Format is provided as a set of JSON Schema files, for + easy use and interopability with tools expecting JSON Schemas. + + ), + }, + { + title: "Collaboratively Maintained", + description: ( + <> + The CVE Record Format is maintained by the CVE Quality Working Group, + under a consensus-based process, which anyone can join. + + ), + }, + { + title: "Powered by RFDs", + description: ( + <> + The CVE Record Format evolves by a Request for Discussion (RFD) process, + where changes are proposed, discussed, and approved. + + ), + }, +]; + +function Feature({ title, description }: FeatureItem) { + return ( +
+
+ {title} +

{description}

+
+
+ ); +} + +export default function HomepageFeatures(): ReactNode { + return ( +
+
+
+ {FeatureList.map((props, idx) => ( + + ))} +
+
+
+ ); +} diff --git a/site/src/components/HomepageFeatures/styles.module.css b/site/src/components/HomepageFeatures/styles.module.css new file mode 100644 index 00000000000..e25342faded --- /dev/null +++ b/site/src/components/HomepageFeatures/styles.module.css @@ -0,0 +1,6 @@ +.features { + display: flex; + align-items: center; + padding: 2rem 0; + width: 100%; +} diff --git a/site/src/css/custom.css b/site/src/css/custom.css new file mode 100644 index 00000000000..a41266efbc5 --- /dev/null +++ b/site/src/css/custom.css @@ -0,0 +1,34 @@ +/** + * 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/site/src/pages/index.module.css b/site/src/pages/index.module.css new file mode 100644 index 00000000000..9f71a5da775 --- /dev/null +++ b/site/src/pages/index.module.css @@ -0,0 +1,23 @@ +/** + * CSS files with the .module.css suffix will be treated as CSS modules + * and scoped locally. + */ + +.heroBanner { + padding: 4rem 0; + text-align: center; + position: relative; + overflow: hidden; +} + +@media screen and (max-width: 996px) { + .heroBanner { + padding: 2rem; + } +} + +.buttons { + display: flex; + align-items: center; + justify-content: center; +} diff --git a/site/src/pages/index.tsx b/site/src/pages/index.tsx new file mode 100644 index 00000000000..95f61c82255 --- /dev/null +++ b/site/src/pages/index.tsx @@ -0,0 +1,37 @@ +import type { ReactNode } from "react"; +import clsx from "clsx"; +import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; +import Layout from "@theme/Layout"; +import HomepageFeatures from "@site/src/components/HomepageFeatures"; +import Heading from "@theme/Heading"; + +import styles from "./index.module.css"; + +function HomepageHeader() { + const { siteConfig } = useDocusaurusContext(); + return ( +
+
+ + {siteConfig.title} + +

{siteConfig.tagline}

+
+
+ ); +} + +export default function Home(): ReactNode { + const { siteConfig } = useDocusaurusContext(); + return ( + + +
+ +
+ + ); +} diff --git a/site/static/.nojekyll b/site/static/.nojekyll new file mode 100644 index 00000000000..e69de29bb2d diff --git a/site/tsconfig.json b/site/tsconfig.json new file mode 100644 index 00000000000..920d7a6523b --- /dev/null +++ b/site/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"] +}