Auto publish docs for the next branch when there are changes

.github/workflows/publish-docs-next.sh

@@ -0,0 +1,64 @@
+# Exit on first error, treat unset variables as errors
+set -eu
+
+BRANCH_NEXT="next"
+BRANCH_GH_PAGES="gh-pages"
+
+echo "BRANCH_NEXT: $BRANCH_NEXT"
+echo "BRANCH_GH_PAGES: $BRANCH_GH_PAGES"
+
+# Exit if the current branch is not the next branch
+if [[ $(git rev-parse --abbrev-ref HEAD) != "$BRANCH_NEXT" ]]; then
+  echo "This script can only be run on the $BRANCH_NEXT branch."
+  echo "Current branch: $(git rev-parse --abbrev-ref HEAD)"
+  exit 1
+fi
+
+# Keep track of the current commit sha
+LAST_COMMIT_ON_NEXT=$(git rev-parse --short HEAD)
+echo "LAST_COMMIT_ON_NEXT: $LAST_COMMIT_ON_NEXT"
+
+# Change the version to "next" before building the docs
+echo "export default \"next\";" > ./build/version.mjs
+
+echo ""
+echo "Building docs..."
+yarn build:docs
+
+# Undo the change to the version, to switch branches
+git checkout -- ./build/version.mjs
+
+echo ""
+echo "Switching to the $BRANCH_GH_PAGES branch..."
+git checkout $BRANCH_GH_PAGES
+
+echo ""
+echo "Replacing the existing \`next\` docs with a copy of the new docs..."
+rm -rf next && mv docs/ next/
+
+# The built files have links to the `master` branch on GitHub.
+# Find and replace those links to point to the next branch. Replace:
+#   - `/tree/master` with `/tree/$BRANCH_NEXT`
+#   - `/blob/master` with `/blob/$BRANCH_NEXT`
+echo ""
+echo "Replacing links to \`master\` with links to \`$BRANCH_NEXT\`..."
+BRANCH_NEXT_SLASH_ESCAPED=$(echo "$BRANCH_NEXT" | sed 's/\//\\\//g')
+find next/ -type f -exec sed -i -e "s/\/tree\/master/\/tree\/$BRANCH_NEXT_SLASH_ESCAPED/g" {} \;
+find next/ -type f -exec sed -i -e "s/\/blob\/master/\/blob\/$BRANCH_NEXT_SLASH_ESCAPED/g" {} \;
+
+# If there are changes in the built docs, commit and push them
+if ! git diff --quiet -- next/; then
+  echo ""
+  echo "Committing the changes..."
+  git add next/
+  git -c user.name="Josephus Paye II" -c user.email="j.paye96@gmail.com" \
+    commit -m "Add \`next\` docs for commit $LAST_COMMIT_ON_NEXT"
+
+  echo ""
+  echo "Pushing the changes to the $BRANCH_GH_PAGES branch..."
+  git push origin $BRANCH_GH_PAGES
+else
+  echo ""
+  echo "No changes to built docs, skipping publish"
+  exit 0
+fi

.github/workflows/publish-docs-next.yml

@@ -0,0 +1,56 @@
+name: Publish docs for `next` branch
+
+on:
+  push:
+    branches: [next]
+
+# Used to ensure only one instance of the workflow is running at a time, cancels existing runs when there's a new one.
+# See https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#concurrency.
+concurrency:
+  # `github.workflow` is workflow name, `github.ref` is current branch/tag identifier
+  group: ${{ format('{0}:{1}', github.workflow, github.ref) }}
+  cancel-in-progress: true
+
+jobs:
+  check_for_changes:
+    name: Check for changes
+    runs-on: ubuntu-22.04
+    outputs:
+      has_workflow_changes: ${{ steps.filter.outputs.workflow_changes }}
+      has_docs_changes: ${{ steps.filter.outputs.docs_changes }}
+      has_src_changes: ${{ steps.filter.outputs.src_changes }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+      - name: Check for Changes
+        uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            workflow_changes:
+              - '.github/workflows/publish-docs-next*'
+            docs_changes:
+              - 'docs-src/**'
+            src_changes:
+              - 'src/**'
+
+  publish_docs:
+    name: "Build and publish docs to GitHub Pages"
+    runs-on: "ubuntu-latest"
+    needs: ["check_for_changes"]
+    if: |
+      needs.check_for_changes.outputs.has_workflow_changes == 'true' ||
+      needs.check_for_changes.outputs.has_docs_changes == 'true' ||
+      needs.check_for_changes.outputs.has_src_changes == 'true'
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: next
+          fetch-depth: 0 # fetch all history so we can switch branches to `gh-pages`
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "yarn"
+      - run: yarn install --frozen-lockfile
+      - run: bash .github/workflows/publish-docs-next.sh

.gitignore

@@ -8,3 +8,4 @@ _reminder
 Thumbs.db
 npm-debug.log
 .DS_Store
+docs

Customization.md

@@ -25,7 +25,9 @@ You can customize the components by overriding Sass variables and importing the
 2. If you're using Vite, add the following to `vite.config.js` ([more details here](https://vitejs.dev/config/shared-options.html#css-preprocessoroptions)):
 
    ```js
-   const scssVariablesFile = path.resolve(__dirname, "./src/styles/variables.scss").replace(/\\/g, "/");
+   const scssVariablesFile = path
+     .resolve(__dirname, "./src/styles/variables.scss")
+     .replace(/\\/g, "/");
    export default defineConfig({
      css: {
        preprocessorOptions: {

build/vite.config.docs.mjs

@@ -6,6 +6,7 @@ import autoprefixer from "autoprefixer";
 import options from "./options.mjs";
 
 export default defineConfig({
+  base: "./", // Use relative paths for assets in built index.html
   plugins: [vue()],
   server: {
     port: 9000,

docs-src/App.vue

@@ -78,7 +78,9 @@ export default {
     },
 
     versionUrl() {
-      return `https://github.com/JosephusPaye/Keen-UI/releases/tag/v${this.version}`;
+      return this.version === "next"
+        ? "https://github.com/JosephusPaye/Keen-UI/tree/next"
+        : `https://github.com/JosephusPaye/Keen-UI/releases/tag/v${this.version}`;
     },
   },
 

docs-src/DocsBrand.vue

@@ -6,9 +6,9 @@
       class="keen-docs-brand__version"
       rel="noopener"
       target="_blank"
-      title="View release notes"
-      :href="versionUrl"
-      >v{{ version }}</a
+      :title="displayVersion.title"
+      :href="displayVersion.url"
+      >{{ displayVersion.label }}</a
     >
 
     <a
@@ -44,6 +44,16 @@ export default {
     versionUrl: String,
     repoUrl: String,
   },
+
+  computed: {
+    displayVersion() {
+      return {
+        url: this.versionUrl,
+        title: this.version === "next" ? "View `next` branch on Github" : "View release notes",
+        label: this.version === "next" ? "next" : `v${this.version}`,
+      };
+    },
+  },
 };
 </script>
 
@@ -65,6 +75,7 @@ export default {
   font-size: 0.9rem;
   opacity: 0.7;
   vertical-align: super;
+  padding-left: 0.4rem;
 
   &:hover,
   &:focus {

docs-src/DocsSidebar.vue

@@ -75,6 +75,20 @@ import DocsBrand from "./DocsBrand.vue";
 import UiIcon from "@/UiIcon.vue";
 import UiSelect from "@/UiSelect.vue";
 
+import version from "../build/version.mjs";
+
+const versions = [
+  { label: "0.8.x", value: "0.8.9" },
+  { label: "1.0.x", value: "1.0.1" },
+  { label: "1.1.x", value: "1.1.2" },
+  { label: "1.2.x", value: "1.2.1" },
+  { label: "1.3.x", value: "1.3.2" },
+  { label: "1.4.x", value: "1.4.0" },
+  { label: "next", value: "next" },
+];
+
+const selectedVersion = versions.find((v) => v.value === version) ?? versions[versions.length - 2];
+
 export default {
   components: {
     DocsBrand,
@@ -90,18 +104,8 @@ export default {
 
   data() {
     return {
-      versions: [
-        { label: "0.8.x", value: "0.8.9" },
-        { label: "1.0.x", value: "1.0.1" },
-        { label: "1.1.x", value: "1.1.2" },
-        { label: "1.2.x", value: "1.2.1" },
-        { label: "1.3.x", value: "1.3.2" },
-        { label: "1.4.x", value: "1.4.0" },
-      ],
-      selectedVersion: {
-        label: "1.4.x",
-        value: "1.4.0",
-      },
+      versions,
+      selectedVersion,
       menu,
     };
   },