Merge pull request #8 from mitre-attack/autodocs

docs: Build and deploy docs

.github/workflows/ci.yml

@@ -118,3 +118,41 @@ jobs:
           # NPM_TOKEN: ${{ secrets.NPM_TOKEN }} DO NOT USE
           HUSKY: 0  # Temporarily disables all Git hooks
         run: npx semantic-release
+
+  deploy-docs:
+    needs: [publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Install schema dependencies
+        run: npm install
+        working-directory: ./
+
+      - name: Install docusaurus dependencies
+        run: npm install
+        working-directory: ./docusaurus
+
+      - name: Generate schema documentation
+        run: npm run gendocs
+        working-directory: ./docusaurus
+
+      - name: Build Docusaurus site
+        run: npm run build
+        working-directory: ./docusaurus
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          deploy_key: ${{ secrets.DEPLOY_KEY }}
+          publish_dir: ./docusaurus/build

docusaurus/.gitignore

@@ -0,0 +1,22 @@
+# 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*
+
+docs/*/*

docusaurus/README.md

@@ -0,0 +1,69 @@
+# ATT&CK Data Model Documentation
+
+This repository contains the automated documentation for the ATT&CK Data Model. The project
+leverages Zod schemas, defined in `zod/schemas/`, to generate Markdown files that are processed
+and served as static documentation using [Docusaurus](https://docusaurus.io/).
+
+The automation is handled by the `generate-docs.sh` script, which processes each `.schema.ts` file
+in the schema directory and uses the `zod2md` library to convert to Markdown. The output Markdown
+files are stored in the `docs/` directory.
+
+## Setup
+
+### Requirements
+- [Node.js](https://nodejs.org/) v18.20
+- [Docusaurus](https://docusaurus.io/) v3.5
+
+### Install dependences
+
+```bash
+$ npm install
+```
+
+## Generate Documentation
+
+The `generate-docs.sh` script is used to automate the process of converting Zod schemas into Markdown.
+
+```bash
+$ npm run autodocs
+```
+
+## Local Development
+
+The following command will start a local development server and open a browser window. Most changes will
+be reflected live without needing to restart the server.
+
+```bash
+$ npm run start
+```
+
+## Deployment
+
+1. Build the static files
+
+```bash
+$ npm run build
+```
+
+2. Serve contents
+
+```bash
+$ npm run serve
+```
+
+## Troubleshooting
+
+To clear the site's generated assets, caches, and build artifacts:
+```bash
+$ npm run clear
+```
+
+Deployment using SSH:
+```bash
+$ USE_SSH=true yarn deploy
+```
+
+Deployment without SSH:
+```bash
+$ GIT_USER=<Your GitHub username> yarn deploy
+```

docusaurus/blog/authors.yml

@@ -0,0 +1,9 @@
+mitreattack:
+  name: MITRE ATT&CK
+  title: A knowledge base for describing the behavior of adversaries
+  url: https://attack.mitre.org
+  image_url: img/attack.jpg
+  page: false
+  socials:
+    x: https://twitter.com/mitreattack
+    github: https://github.com/mitre-attack

docusaurus/blog/known-issues.md

@@ -0,0 +1,10 @@
+<!-- ---
+slug: known-issues
+title: ATT&CK v16 - October 2024
+authors: [mitreattack]
+---
+
+The following issues are known discrepancies and non-compliance within the current ATT&CK knowledge base.
+These issues reflect elements that do not conform to the Zod schemas and require changes to bring the
+knowledge base into full compliance. Your understanding and patience are appreciated as we work to
+make improvements. -->

docusaurus/docs/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+// automate the overview summary here

docusaurus/docusaurus.config.ts

@@ -0,0 +1,107 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'MITRE ATT&CK Data Model',
+  tagline: '',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://mitre-attack.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/attack-data-model/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'mitre-attack', // Usually your GitHub org/user name.
+  projectName: 'attack-data-model', // Usually your repo name.
+
+  onBrokenLinks: 'warn',
+  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',
+        },
+        // blog: {
+        //   showReadingTime: false,
+        //   path: 'blog',
+        //   routeBasePath: 'known-issues',
+        //   blogTitle: 'Known Issues',
+        // },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    navbar: {
+      title: 'ATT&CK Data Model',
+      logo: {
+        alt: 'MITRE ATT&CK Logo',
+        src: 'img/favicon.png',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'tutorialSidebar',
+          position: 'left',
+          label: 'ATT&CK Schemas',
+        },
+        // {
+        //   to: '/known-issues',
+        //   label: 'Known Issues',
+        //   position: 'left',
+        // },
+        {
+          href: 'https://github.com/mitre-attack/attack-data-model',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      links: [
+        {
+          label: 'ATT&CK Website',
+          href: 'https://attack.mitre.org',
+        },
+        {
+          label: 'Contact Us',
+          href: 'https://attack.mitre.org/resources/engage-with-attack/contact',
+        },
+        {
+          label: 'Terms of Use',
+          href: 'https://attack.mitre.org/resources/legal-and-branding/terms-of-use',
+        },
+        {
+          label: 'Privacy Policy',
+          href: 'https://attack.mitre.org/resources/legal-and-branding/privacy',
+        },
+      ],
+      style: 'dark',
+      copyright: `© ${new Date().getFullYear()}, The MITRE Corporation. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;