refactor: Update to latest docs platform

docs/.gitignore

@@ -1,2 +1,4 @@
 /vendor
 /node_modules
+/docs/.vitepress/dist
+/docs/.vitepress/cache

docs/Dockerfile

@@ -1,5 +1,7 @@
-ARG TAG=14-alpine
-FROM nystudio107/node-dev-base:$TAG
+ARG TAG=20-alpine
+FROM node:$TAG
+
+RUN npm install -g npm@^10.0.0
 
 WORKDIR /app/
 

docs/Makefile

@@ -1,45 +1,47 @@
-TAG?=14-alpine
-CONTAINER?=$(shell basename $(dir $(CURDIR)))-docs
-DOCKERRUN=docker container run \
-	--name ${CONTAINER} \
-	--rm \
-	-p 3002:3002 \
-	-t \
-	-v `pwd`:/app \
-	${CONTAINER}:${TAG}
-DOCSDEST?=../../../sites/nystudio107/web/docs/icalendar
+MAJOR_VERSION?=1
+TAG?=20-alpine
+CONTAINER?=$(shell basename $(dir $(CURDIR)))-v${MAJOR_VERSION}-docs
+DOCS_DEV_PORT?=400${MAJOR_VERSION}
+DOCS_DEST?=../../../sites/nystudio107/web/docs/icalendar/v1
+IMAGE_INFO=$(shell docker image inspect $(CONTAINER):$(TAG))
+IMAGE_NAME=${CONTAINER}:${TAG}
+DOCKER_RUN=docker container run --rm -it -v "${CURDIR}":/app
 
-.PHONY: docker build dev fix install lint clean npm
+.PHONY: build clean dev fix image-build image-check lint npm ssh
 
-docker:
-	docker build \
-		. \
-		-t ${CONTAINER}:${TAG} \
-		--build-arg TAG=${TAG} \
-		--no-cache
-build: clean docker install
-	${DOCKERRUN} \
-		run docs:build
-	rm -rf ${DOCSDEST}
-	mv ./docs/.vitepress/dist ${DOCSDEST}
-dev: docker install
-	${DOCKERRUN} \
-		run docs:dev
-fix: docker install
-	${DOCKERRUN} \
-		run docs:fix
-install: docker
-	${DOCKERRUN} \
-		install
-lint: docker install
-	${DOCKERRUN} \
-		run docs:lint
+# Perform a dist build via npm run docs:build
+build: image-check
+	${DOCKER_RUN} --name ${CONTAINER}-$@ ${IMAGE_NAME} run docs:build
+	rm -rf ${DOCS_DEST}
+	mv ./docs/.vitepress/dist ${DOCS_DEST}
+# Remove node_modules/ & package-lock.json
 clean:
 	rm -rf node_modules/
 	rm -f package-lock.json
-npm: docker
-	${DOCKERRUN} \
-		$(filter-out $@,$(MAKECMDGOALS))
+# Run the development server via npm run docs:dev
+dev: image-check
+	${DOCKER_RUN} --name ${CONTAINER}-$@ -e DOCS_DEV_PORT="${DOCS_DEV_PORT}" -p ${DOCS_DEV_PORT}:${DOCS_DEV_PORT} ${IMAGE_NAME} run docs:dev
+# Fix the docs with textlint via npm run docs:fix
+fix: image-check
+	${DOCKER_RUN} --name ${CONTAINER}-$@ ${IMAGE_NAME} run docs:fix
+# Build the Docker image & run npm install
+image-build:
+	docker build . -t ${IMAGE_NAME} --build-arg TAG=${TAG} --no-cache
+	${DOCKER_RUN} --name ${CONTAINER}-$@ ${IMAGE_NAME} install
+# Ensure the image has been created
+image-check:
+ifeq ($(IMAGE_INFO), [])
+image-check: image-build
+endif
+# Lint the docs with textlint via npm run docs:lint
+lint: image-check
+	${DOCKER_RUN} --name ${CONTAINER}-$@ ${IMAGE_NAME} run docs:lint
+# Run the passed in npm command
+npm: image-check
+	${DOCKER_RUN} --name ${CONTAINER}-$@ ${IMAGE_NAME} $(filter-out $@,$(MAKECMDGOALS)) $(MAKEFLAGS)
+# Open a shell inside of the container
+ssh: image-check
+	${DOCKER_RUN} --name ${CONTAINER}-$@ --entrypoint=/bin/sh ${IMAGE_NAME}
 %:
 	@:
 # ref: https://stackoverflow.com/questions/6273608/how-to-pass-argument-to-makefile-from-command-line

docs/README.md

@@ -0,0 +1,74 @@
+# `icalendar` docs
+
+This buildchain is a self-contained build system for the `icalendar` documentation.
+
+## Overview
+
+The buildchain uses [VitePress](https://vitepress.dev/) via a Docker container to facilitate writing the docs as [markdown](https://vitepress.dev/guide/markdown), linting them via [textlint](https://textlint.github.io/), building them as HTML files with bundled assets, and publishing them automatically via a [GitHub action](https://docs.github.com/en/actions).
+
+It also uses a [Rollup](https://rollupjs.org/) [sitemap plugin](https://github.com/aminnairi/rollup-plugin-sitemap) to generate a `sitemap.xml` for the generated docs.
+
+The markdown sources for the docs and assets are in the `docs/docs/` directory.
+
+The built distribution docs are created via the `build-and-deploy-docs.yaml`
+
+## Prerequisites
+
+To run the buildchain for development purposes:
+
+- You must have [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or the equivalent) installed
+
+## Commands
+
+This buildchain uses `make` as an interface to the buildchain. The following commands are available from the `buildchain/` directory:
+
+- `make image-build` - Build the Docker image & run `npm install`. This command must be run once before using the Docker container.
+- `make dev` - Start Vite HMR dev server while writing/editing the docs. Click on the link displayed in the terminal to open the docs up
+- `make lint` - Run `textlint` on the docs, reporting on any errors and warnings
+- `make fix` - Run `textlint` on the docs, automatically fixing any errors, and reporting any warnings
+- `make clean` - Remove `node_modules/` and `package-lock.json` to start clean (need to run `make image-build` after doing this, see below)
+- `make npm XXX` - Run an `npm` command inside the container, e.g.: `make npm run lint` or `make npm install`
+- `make ssh` - Open up a shell session into the buildchain Docker container
+- `make build` - Do a local distribution build of the docs; normally not needed since they are built & deployed via GitHub action
+
+## Docs versioning
+
+Each major version of the plugin corresponds to a major version of Craft.
+
+Each major version of the plugin has separate documentation that needs to be updated when changes span plugin versions.
+
+The latest version of the docs that correspond to the latest version of the plugin is always the root of the docs tree, with older versions appearing in sub-directories:
+
+```
+│ index.html
+├── v4
+│   └── index.html
+├── v3
+│   └── index.html
+```
+
+The docs are entirely separate, but linked to eachother via a version menu, configured in the `docs/docs/.vitepress/config.ts` file.
+
+## Algolia Docsearch
+
+The docs uses [Algolia Docsearch](https://docsearch.algolia.com/) to index them, and allow for easy searching via a search field with auto-complete.
+
+Algolia Docsearch is configured in the `docs/docs/.vitepress/config.ts` file.
+
+## textlint
+
+The buildchain uses [textlint](https://textlint.github.io/) to automatically fix errors on build, and also issue writing style warnings.
+
+`textlint` automatically uses any rules added to the `docs/package.json` file, which can be overridden or customized via the `docs/.textlintrc.js` file.
+
+See the [textlint docs](https://textlint.github.io/docs/getting-started.html) for details.
+
+## Overriding environment variables
+
+The `Makefile` contains sane defaults for most things, but you can override them via environment variables if you need to.
+
+For instance, if you want to change the `DOCS_DEST` environment variable to change where `make build` builds the docs locally, you can set it before running any buildchain `make` commands:
+```bash
+env DOCS_DEST=../path/to/some/dir make build
+```
+...or use any other method for [setting environment variables](https://www.twilio.com/blog/how-to-set-environment-variables.html). This environment variable needs to be set in the shell where you run the buildchain's various `make` commands from, so setting it in your project's `.env` file won't work.

docs/docs/.vitepress/config.ts

@@ -0,0 +1,48 @@
+import {defineConfig} from 'vitepress'
+
+export default defineConfig({
+  title: 'iCalendar Plugin',
+  description: 'Documentation for the iCalendar plugin',
+  base: '/docs/icalendar/v1/',
+  lang: 'en-US',
+  head: [
+    ['meta', {content: 'https://github.com/nystudio107', property: 'og:see_also',}],
+    ['meta', {content: 'https://twitter.com/nystudio107', property: 'og:see_also',}],
+    ['meta', {content: 'https://youtube.com/nystudio107', property: 'og:see_also',}],
+    ['meta', {content: 'https://www.facebook.com/newyorkstudio107', property: 'og:see_also',}],
+  ],
+  themeConfig: {
+    socialLinks: [
+      {icon: 'github', link: 'https://github.com/nystudio107'},
+      {icon: 'twitter', link: 'https://twitter.com/nystudio107'},
+    ],
+    logo: '/img/plugin-logo.svg',
+    editLink: {
+      pattern: 'https://github.com/nystudio107/craft-icalendar/edit/develop/docs/docs/:path',
+      text: 'Edit this page on GitHub'
+    },
+    algolia: {
+      appId: 'AE3HRUJFEW',
+      apiKey: '7a365dc6dfe977be2c9588eb3ed5da26',
+      indexName: 'icalendar',
+      searchParameters: {
+        facetFilters: ["version:v1"],
+      },
+    },
+    lastUpdatedText: 'Last Updated',
+    sidebar: [],
+    nav: [
+      {text: 'Home', link: 'https://nystudio107.com/plugins/icalendar'},
+      {text: 'Store', link: 'https://plugins.craftcms.com/icalendar'},
+      {text: 'Changelog', link: 'https://nystudio107.com/plugins/icalendar/changelog'},
+      {text: 'Issues', link: 'https://github.com/nystudio107/craft-icalendar/issues'},
+      {
+        text: 'v1', items: [
+          {text: 'v5', link: 'https://nystudio107.com/docs/icalendar/'},
+          {text: 'v4', link: 'https://nystudio107.com/docs/icalendar/v4/'},
+          {text: 'v1', link: '/'},
+        ],
+      },
+    ]
+  },
+});

docs/docs/.vitepress/theme/SidebarBottom.vue → docs/docs/.vitepress/theme/NYSLogo.vue

@@ -6,18 +6,15 @@
       target="_blank"
       rel="noopener"
     >
-    <img
-        src="/resources/img/nys-logo.svg"
+      <img
+        src="/img/nys-logo.svg"
         aria-label="nystudio107 logo"
-        />
+      />
     </a>
   </div>
 </template>
 
-<script>
-export default {
-  name: "SidebarBottom"
-}
+<script setup>
 </script>
 
 <style scoped>

docs/docs/.vitepress/theme/custom.css

@@ -10,3 +10,7 @@
 .DocSearch {
     --docsearch-primary-color: var(--c-brand) !important;
 }
+
+a > img {
+    display: inline-block;
+}

docs/docs/.vitepress/theme/index.ts

@@ -0,0 +1,42 @@
+import Theme from 'vitepress/theme'
+import {h, watch} from 'vue'
+import './custom.css'
+
+import NYSLogo from './NYSLogo.vue';
+
+// Could also come from .env
+const GA_ID = 'UA-69117511-1';
+
+export default {
+  ...Theme,
+  Layout() {
+    return h(Theme.Layout, null, {
+        'aside-bottom': () => h(NYSLogo)
+      }
+    )
+  },
+  enhanceApp: (ctx) => {
+    // Google analytics integration
+    if (import.meta.env.PROD && GA_ID && typeof window !== 'undefined') {
+      (function (i, s, o, g, r, a, m) {
+        i['GoogleAnalyticsObject'] = r
+        i[r] = i[r] || function () {
+          (i[r].q = i[r].q || []).push(arguments)
+        }
+        i[r].l = 1 * new Date()
+        a = s.createElement(o)
+        m = s.getElementsByTagName(o)[0]
+        a.async = 1
+        a.src = g
+        m.parentNode.insertBefore(a, m)
+      })(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga')
+      ga('create', GA_ID, 'auto')
+      ga('set', 'anonymizeIp', true)
+      // Send a page view any time the route changes
+      watch(ctx.router.route, (newValue, oldValue) => {
+        ga('set', 'page', newValue.path)
+        ga('send', 'pageview')
+      })
+    }
+  }
+}

docs/docs/@types/shims.d.ts

@@ -0,0 +1,7 @@
+declare module "*.vue" {
+  import Vue from 'vue';
+  export default Vue;
+}
+
+declare module 'rollup-plugin-sitemap';
+declare module 'NYSLogo';

docs/docs/index.md

@@ -12,7 +12,7 @@ Provides tools for parsing & formatting the RFC 2445 iCalendar (.ics) specificat
 
 ## Requirements
 
-This plugin requires Craft CMS 3.0.0 or later or Craft CMS 4.0.0 or later.
+This plugin requires Craft CMS 3.0.0 or later
 
 ## Installation
 
@@ -157,7 +157,7 @@ END:VCALENDAR
 {% endspaceless %}
 ```
 
-**N.B.:** For the above code, if you're running a version of Twig older than 2.9, you'll need to use `{% filter rfc2445 %}` instead.
+**N.B.:** For the above code, if you’re running a version of Twig older than 2.9, you’ll need to use `{% filter rfc2445 %}` instead.
 
 This will output:
 ```