Use Node 20 for docs only (#1009)

.github/workflows/pr.yml

@@ -48,12 +48,32 @@ jobs:
 
       - run: yarn build
 
-      - run: yarn docs:build
-
       - run: yarn checkchange --verbose
 
       - run: yarn test:unit
 
       - run: yarn test:func
 
       - run: yarn test:e2e
+
+  # The docs have a separate installation using Node 20 due to needing newer dependencies
+  docs:
+    name: build docs
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Install Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          cache: yarn
+          node-version: 20
+
+      - run: yarn --immutable
+        working-directory: ./docs
+
+      - run: yarn docs:build
+        working-directory: ./docs

.github/workflows/release.yml

@@ -22,8 +22,6 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v4
         with:
-          # Fetch all history (required for publishing which looks at history)
-          fetch-depth: 0
           # Don't save creds in the git config (so it's easier to override later)
           persist-credentials: false
 
@@ -64,12 +62,44 @@ jobs:
           NPM_AUTHTOKEN: ${{ secrets.NPM_AUTHTOKEN }}
           REPO_PAT: ${{ secrets.REPO_PAT }}
 
+  # The docs have a separate installation using Node 20 due to needing newer dependencies
+  docs:
+    name: Update docs
+
+    needs: build
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Needed by gh-pages publish
+      contents: write
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          # Don't save creds in the git config (so it's easier to override later)
+          persist-credentials: false
+
+      - name: Install Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          cache: yarn
+          node-version: 20
+
+      - run: yarn --immutable
+        working-directory: ./docs
+
+      - run: yarn docs:build
+        working-directory: ./docs
+
       - name: Update docs
         run: |
           # See previous step for explanation
           trap "git remote set-url origin '$(git remote get-url origin)'" EXIT
-          git remote set-url origin "https://$REPO_PAT@github.com/$GITHUB_REPOSITORY"
+          git remote set-url origin "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git"
 
           yarn release:docs
         env:
-          REPO_PAT: ${{ secrets.REPO_PAT }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        working-directory: ./docs

.gitignore

@@ -5,3 +5,8 @@ node_modules/
 .DS_Store
 lib/
 package-lock.json
+
+docs/.vuepress/.cache
+docs/.vuepress/.temp
+docs/.yarn/*
+!docs/.yarn/releases/

change/beachball-2f472ead-b99c-4a97-be7d-33c440d6f87b.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Update doc site to vuepress 2",
+  "packageName": "beachball",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

docs/.nvmrc

@@ -0,0 +1 @@
+20

docs/.vuepress/client.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+import { defineClientConfig } from 'vuepress/client';
+import { defineMermaidConfig } from 'vuepress-plugin-md-enhance/client';
+
+defineMermaidConfig({
+  // This can use a CSS variable because text is rendered in HTML tags
+  fontFamily: 'var(--font-family)',
+  themeVariables: {
+    // Background and border colors can't use CSS variables since they're rendered in SVG...
+    mainBkg: '#fff5cc', // node background
+    nodeBorder: '#cb9f0c',
+    edgeLabelBackground: '#f8de87',
+    // Some of these node colors are conditionally set in index.scss for dark mode...
+    // titleColor: 'red', // sub-graph title
+    // nodeTextColor: 'red', // yes
+    // secondaryColor: 'red', // edgeLabelBackground default
+    // tertiaryColor: 'red', // sub-graph backgrouns
+    // tertiaryBorderColor: 'red', // sub-graph border
+    // tertiaryTextColor: 'red', // sub-graph title
+    // clusterBkg: 'red', // sub-graph background
+    // clusterBorder: 'red', // sub-graph border
+  },
+  // some spacing options available under "flowchart"
+});
+
+export default defineClientConfig({
+  enhance: context => {
+    context.app.directive;
+  },
+});

docs/.vuepress/config.mjs

@@ -0,0 +1,48 @@
+// @ts-check
+import { viteBundler } from '@vuepress/bundler-vite';
+import { searchPlugin } from '@vuepress/plugin-search';
+import { defaultTheme } from '@vuepress/theme-default';
+import { defineUserConfig } from 'vuepress';
+import { mdEnhancePlugin } from 'vuepress-plugin-md-enhance';
+
+export default defineUserConfig({
+  title: 'beachball',
+  description: 'The Sunniest Semantic Version Bumper',
+  base: '/beachball/',
+  bundler: viteBundler(),
+  theme: defaultTheme({
+    navbar: [
+      { text: 'Home', link: '/' },
+      { text: 'Getting Started', link: '/overview/getting-started' },
+      { text: 'Github', link: 'https://github.com/microsoft/beachball' },
+    ],
+    sidebar: [
+      {
+        text: 'Overview',
+        collapsible: false,
+        children: ['/overview/getting-started', '/overview/installation', '/overview/configuration'],
+      },
+      {
+        text: 'Concepts',
+        collapsible: false,
+        children: [
+          '/concepts/bump-algorithm',
+          '/concepts/change-files',
+          '/concepts/ci-integration',
+          '/concepts/groups',
+        ],
+      },
+      {
+        text: 'Command Line Args',
+        collapsible: false,
+        children: ['/cli/options', '/cli/bump', '/cli/change', '/cli/check', '/cli/publish', '/cli/sync'],
+      },
+    ],
+  }),
+  plugins: [
+    mdEnhancePlugin({
+      mermaid: true,
+    }),
+    searchPlugin(),
+  ],
+});

docs/.vuepress/styles/index.scss

@@ -0,0 +1,38 @@
+// https://ecosystem.vuejs.press/themes/default/styles.html
+
+:root {
+  // link text
+  --vp-c-accent: #a17d08;
+  // homepage action
+  --vp-c-accent-bg: #cb9f0c;
+  // homepage action hover
+  --vp-c-accent-hover: #eab60b;
+
+  --graph-node-bg: #fff5cc;
+}
+
+[data-theme='dark'] {
+  --vp-c-accent: #ffd700;
+  --vp-c-accent-bg: #ffd700;
+
+  // fix mermaid colors in dark mode
+  .clusterLabel .nodeLabel {
+    color: var(--vp-c-text);
+  }
+
+  .label .nodeLabel,
+  .edgeLabel {
+    color: var(--vp-c-bg) !important;
+  }
+}
+
+p a code {
+  // make link text inside code visible
+  color: var(--vp-c-text);
+}
+
+.vp-sidebar a:hover,
+.vp-hero-action-button:hover {
+  // make sidebar and action links more obvious
+  text-decoration: underline;
+}