From 35be8b5558e0b4102f652f629360ce1d21e3c884 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Fri, 5 Apr 2024 15:34:23 -0400 Subject: [PATCH 1/7] refactor: ECS code cleanup --- src/Twigpack.php | 22 +++++++++++----------- src/helpers/Manifest.php | 14 ++++++-------- src/services/Manifest.php | 4 ++-- src/translations/en/twigpack.php | 2 +- src/variables/ManifestVariable.php | 6 +++--- 5 files changed, 23 insertions(+), 25 deletions(-) diff --git a/src/Twigpack.php b/src/Twigpack.php index 81b2548..f11f2a1 100644 --- a/src/Twigpack.php +++ b/src/Twigpack.php @@ -11,22 +11,22 @@ namespace nystudio107\twigpack; -use nystudio107\twigpack\services\Manifest as ManifestService; -use nystudio107\twigpack\models\Settings; -use nystudio107\twigpack\variables\ManifestVariable; - use Craft; use craft\base\Plugin; use craft\events\DeleteTemplateCachesEvent; + use craft\events\PluginEvent; use craft\events\RegisterCacheOptionsEvent; use craft\events\TemplateEvent; use craft\services\Plugins; use craft\services\TemplateCaches; use craft\utilities\ClearCaches; -use craft\web\twig\variables\CraftVariable; use craft\web\Application; +use craft\web\twig\variables\CraftVariable; use craft\web\View; +use nystudio107\twigpack\models\Settings; +use nystudio107\twigpack\services\Manifest as ManifestService; +use nystudio107\twigpack\variables\ManifestVariable; use yii\base\Event; use yii\web\NotFoundHttpException; @@ -160,7 +160,7 @@ protected function installEventListeners() Event::on( View::class, View::EVENT_BEFORE_RENDER_PAGE_TEMPLATE, - function (TemplateEvent $event) { + function(TemplateEvent $event) { self::$templateName = $event->template; } ); @@ -168,7 +168,7 @@ function (TemplateEvent $event) { Event::on( CraftVariable::class, CraftVariable::EVENT_INIT, - function (Event $event) { + function(Event $event) { /** @var CraftVariable $variable */ $variable = $event->sender; $variable->set('twigpack', ManifestVariable::class); @@ -178,7 +178,7 @@ function (Event $event) { Event::on( TemplateCaches::class, TemplateCaches::EVENT_AFTER_DELETE_CACHES, - function (DeleteTemplateCachesEvent $event) { + function(DeleteTemplateCachesEvent $event) { // Invalidate the caches when template caches are deleted $this->clearAllCaches(); } @@ -187,7 +187,7 @@ function (DeleteTemplateCachesEvent $event) { Event::on( Plugins::class, Plugins::EVENT_AFTER_INSTALL_PLUGIN, - function (PluginEvent $event) { + function(PluginEvent $event) { if ($event->plugin === $this) { // Invalidate our caches after we've been installed $this->clearAllCaches(); @@ -198,7 +198,7 @@ function (PluginEvent $event) { Event::on( ClearCaches::class, ClearCaches::EVENT_REGISTER_CACHE_OPTIONS, - function (RegisterCacheOptionsEvent $event) { + function(RegisterCacheOptionsEvent $event) { Craft::debug( 'ClearCaches::EVENT_REGISTER_CACHE_OPTIONS', __METHOD__ @@ -213,7 +213,7 @@ function (RegisterCacheOptionsEvent $event) { // delay attaching event handler to the view component after it is fully configured $app = Craft::$app; if ($app->getConfig()->getGeneral()->devMode) { - $app->on(Application::EVENT_BEFORE_REQUEST, function () use ($app) { + $app->on(Application::EVENT_BEFORE_REQUEST, function() use ($app) { $app->getView()->on(View::EVENT_END_BODY, [$this, 'injectErrorEntry']); }); } diff --git a/src/helpers/Manifest.php b/src/helpers/Manifest.php index 6d4fecc..c8d0e11 100644 --- a/src/helpers/Manifest.php +++ b/src/helpers/Manifest.php @@ -307,7 +307,6 @@ public static function getModule(array $config, string $moduleName, string $type */ public static function getModuleHash(array $config, string $moduleName, string $type = 'modern', bool $soft = false) { - $moduleHash = ''; try { // Get the module entry @@ -342,8 +341,7 @@ public static function getModuleEntry( string $moduleName, string $type = 'modern', bool $soft = false - ) - { + ) { $module = null; // Get the manifest file $manifest = self::getManifestFile($config, $type); @@ -579,10 +577,10 @@ protected static function getFileContents(string $path, callable $callback = nul $dependency = new ChainedDependency([ 'dependencies' => [ new FileDependency([ - 'fileName' => $path + 'fileName' => $path, ]), - $dependency - ] + $dependency, + ], ]); } // Set the cache duration based on devMode @@ -595,7 +593,7 @@ protected static function getFileContents(string $path, callable $callback = nul $cacheKeySuffix = $settings->cacheKeySuffix ?? ''; $file = $cache->getOrSet( self::CACHE_KEY . $cacheKeySuffix . $path, - function () use ($path, $callback) { + function() use ($path, $callback) { $result = null; $contents = null; if (UrlHelper::isAbsoluteUrl($path)) { @@ -673,7 +671,7 @@ protected static function getHttpResponseCode($url, $context) protected static function combinePaths(string ...$paths): string { $last_key = count($paths) - 1; - array_walk($paths, function (&$val, $key) use ($last_key) { + array_walk($paths, function(&$val, $key) use ($last_key) { switch ($key) { case 0: $val = rtrim($val, '/ '); diff --git a/src/services/Manifest.php b/src/services/Manifest.php index f0cd48c..03a6c1b 100644 --- a/src/services/Manifest.php +++ b/src/services/Manifest.php @@ -11,10 +11,10 @@ namespace nystudio107\twigpack\services; -use nystudio107\twigpack\Twigpack; +use craft\base\Component; use nystudio107\twigpack\helpers\Manifest as ManifestHelper; -use craft\base\Component; +use nystudio107\twigpack\Twigpack; use yii\web\NotFoundHttpException; diff --git a/src/translations/en/twigpack.php b/src/translations/en/twigpack.php index f51151b..81ca87d 100644 --- a/src/translations/en/twigpack.php +++ b/src/translations/en/twigpack.php @@ -19,5 +19,5 @@ '{name} plugin loaded' => '{name} plugin loaded', 'Manifest file not found at: {manifestPath}' => 'Manifest file not found at: {manifestPath}', 'Module does not exist in the manifest: {moduleName}' => 'Module does not exist in the manifest: {moduleName}', - 'File does not exist: {path}' => 'File does not exist: {path}' + 'File does not exist: {path}' => 'File does not exist: {path}', ]; diff --git a/src/variables/ManifestVariable.php b/src/variables/ManifestVariable.php index 23db300..56deb6d 100644 --- a/src/variables/ManifestVariable.php +++ b/src/variables/ManifestVariable.php @@ -11,14 +11,14 @@ namespace nystudio107\twigpack\variables; -use nystudio107\twigpack\Twigpack; - use craft\helpers\Template; -use yii\web\NotFoundHttpException; +use nystudio107\twigpack\Twigpack; use Twig\Markup; +use yii\web\NotFoundHttpException; + /** * @author nystudio107 * @package Twigpack From 1104788af03eca37ef9ec2de17b293aafd71c1b0 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Fri, 5 Apr 2024 15:41:48 -0400 Subject: [PATCH 2/7] refactor: PHPstan code cleanup --- src/Twigpack.php | 36 +++++++++++++----------------- src/helpers/Manifest.php | 6 ++--- src/services/Manifest.php | 15 ++++++------- src/variables/ManifestVariable.php | 36 ++++++++++++++---------------- 4 files changed, 43 insertions(+), 50 deletions(-) diff --git a/src/Twigpack.php b/src/Twigpack.php index f11f2a1..1907b7a 100644 --- a/src/Twigpack.php +++ b/src/Twigpack.php @@ -14,7 +14,6 @@ use Craft; use craft\base\Plugin; use craft\events\DeleteTemplateCachesEvent; - use craft\events\PluginEvent; use craft\events\RegisterCacheOptionsEvent; use craft\events\TemplateEvent; @@ -27,7 +26,6 @@ use nystudio107\twigpack\models\Settings; use nystudio107\twigpack\services\Manifest as ManifestService; use nystudio107\twigpack\variables\ManifestVariable; - use yii\base\Event; use yii\web\NotFoundHttpException; @@ -53,41 +51,38 @@ class Twigpack extends Plugin /** * @var string */ - public static $templateName; + public static $templateName = ''; // Static Methods // ========================================================================= - - /** - * @inheritdoc - */ - public function __construct($id, $parent = null, array $config = []) - { - $config['components'] = [ - 'manifest' => ManifestService::class, - ]; - - parent::__construct($id, $parent, $config); - } - - // Public Properties - // ========================================================================= - /** * @var string */ public $schemaVersion = '1.0.0'; + // Public Properties + // ========================================================================= /** * @var bool */ public $hasCpSection = false; - /** * @var bool */ public $hasCpSettings = false; + /** + * @inheritdoc + */ + public function __construct($id, $parent = null, array $config = []) + { + $config['components'] = [ + 'manifest' => ManifestService::class, + ]; + + parent::__construct($id, $parent, $config); + } + // Public Methods // ========================================================================= @@ -127,6 +122,7 @@ public function clearAllCaches() public function injectErrorEntry() { if (Craft::$app->getResponse()->isServerError || Craft::$app->getResponse()->isClientError) { + /** @var Settings $settings */ $settings = self::$plugin->getSettings(); if (!empty($settings->errorEntry) && $settings->useDevServer) { try { diff --git a/src/helpers/Manifest.php b/src/helpers/Manifest.php index c8d0e11..da19969 100644 --- a/src/helpers/Manifest.php +++ b/src/helpers/Manifest.php @@ -139,7 +139,7 @@ public static function getCssInlineTags(string $path, array $attributes = []): s public static function getCriticalCssTags(array $config, $name = null, array $attributes = []): string { // Resolve the template name - $template = Craft::$app->getView()->resolveTemplate($name ?? Twigpack::$templateName ?? ''); + $template = Craft::$app->getView()->resolveTemplate($name ?? Twigpack::$templateName); if ($template) { $name = self::combinePaths( pathinfo($template, PATHINFO_DIRNAME), @@ -473,7 +473,7 @@ public static function getFileFromManifest(array $config, string $fileName, stri } try { if (is_file($localPath)) { - return self::getFile($localPath) ?? ''; + return self::getFile($localPath); } } catch (Exception $e) { Craft::error($e->getMessage(), __METHOD__); @@ -653,7 +653,7 @@ function() use ($path, $callback) { */ protected static function getHttpResponseCode($url, $context) { - $headers = @get_headers($url, 0, $context); + $headers = @get_headers($url, false, $context); if (empty($headers)) { return '404'; } diff --git a/src/services/Manifest.php b/src/services/Manifest.php index 03a6c1b..961d420 100644 --- a/src/services/Manifest.php +++ b/src/services/Manifest.php @@ -13,9 +13,8 @@ use craft\base\Component; use nystudio107\twigpack\helpers\Manifest as ManifestHelper; - use nystudio107\twigpack\Twigpack; - +use Twig\Error\LoaderError; use yii\web\NotFoundHttpException; /** @noinspection MissingPropertyAnnotationsInspection */ @@ -68,7 +67,7 @@ public function getCssInlineTags(string $path, array $attributes = []): string * @param array $attributes additional HTML key/value pair attributes to add to the resulting tag * * @return string - * @throws \Twig\Error\LoaderError + * @throws LoaderError */ public function getCriticalCssTags($name = null, $config = null, array $attributes = []): string { @@ -92,8 +91,8 @@ public function getCssRelPreloadPolyfill(): string /** * Return the HTML tags to include the JavaScript module * - * @param string $moduleName - * @param bool $async + * @param string $moduleName + * @param bool $async * @param null|array $config * @param array $attributes additional HTML key/value pair attributes to add to the resulting tag * @@ -125,7 +124,7 @@ public function getSafariNomoduleFix(array $attributes = []): string * * @param string $moduleName * @param string $type - * @param null $config + * @param ?array $config * * @return null|string * @throws NotFoundHttpException @@ -143,7 +142,7 @@ public function getModule(string $moduleName, string $type = 'modern', $config = * * @param string $moduleName * @param string $type - * @param null $config + * @param ?array $config * * @return null|string * @throws NotFoundHttpException @@ -173,7 +172,7 @@ public function getFile(string $path): string * * @param string $fileName * @param string $type - * @param null $config + * @param ?array $config * * @return string */ diff --git a/src/variables/ManifestVariable.php b/src/variables/ManifestVariable.php index 56deb6d..d7501de 100644 --- a/src/variables/ManifestVariable.php +++ b/src/variables/ManifestVariable.php @@ -12,11 +12,9 @@ namespace nystudio107\twigpack\variables; use craft\helpers\Template; - use nystudio107\twigpack\Twigpack; - +use Twig\Error\LoaderError; use Twig\Markup; - use yii\web\NotFoundHttpException; /** @@ -38,7 +36,7 @@ class ManifestVariable public static function includeCssRelPreloadPolyfill(): Markup { return Template::raw( - Twigpack::$plugin->manifest->getCssRelPreloadPolyfill() ?? '' + Twigpack::$plugin->manifest->getCssRelPreloadPolyfill() ); } @@ -53,7 +51,7 @@ public static function includeCssRelPreloadPolyfill(): Markup public function includeCssModule(string $moduleName, bool $async = false, array $attributes = []): Markup { return Template::raw( - Twigpack::$plugin->manifest->getCssModuleTags($moduleName, $async, null, $attributes) ?? '' + Twigpack::$plugin->manifest->getCssModuleTags($moduleName, $async, null, $attributes) ); } @@ -68,7 +66,7 @@ public function includeCssModule(string $moduleName, bool $async = false, array public function includeInlineCssTags(string $path, array $attributes = []): Markup { return Template::raw( - Twigpack::$plugin->manifest->getCssInlineTags($path, $attributes) ?? '' + Twigpack::$plugin->manifest->getCssInlineTags($path, $attributes) ); } @@ -80,18 +78,18 @@ public function includeInlineCssTags(string $path, array $attributes = []): Mark * @param array $attributes additional HTML key/value pair attributes to add to the resulting tag * * @return Markup - * @throws \Twig\Error\LoaderError + * @throws LoaderError */ public function includeCriticalCssTags($name = null, array $attributes = []): Markup { return Template::raw( - Twigpack::$plugin->manifest->getCriticalCssTags($name, null, $attributes) ?? '' + Twigpack::$plugin->manifest->getCriticalCssTags($name, null, $attributes) ); } /** - * @param string $moduleName - * @param bool $async + * @param string $moduleName + * @param bool $async * @param array $attributes additional HTML key/value pair attributes to add to the resulting tag * * @return null|Markup @@ -100,7 +98,7 @@ public function includeCriticalCssTags($name = null, array $attributes = []): Ma public function includeJsModule(string $moduleName, bool $async = false, array $attributes = []) { return Template::raw( - Twigpack::$plugin->manifest->getJsModuleTags($moduleName, $async, null, $attributes) ?? '' + Twigpack::$plugin->manifest->getJsModuleTags($moduleName, $async, null, $attributes) ); } @@ -109,7 +107,7 @@ public function includeJsModule(string $moduleName, bool $async = false, array $ * * @param string $moduleName * @param string $type - * @param null $config + * @param null $config * * @return null|Markup * @throws NotFoundHttpException @@ -117,7 +115,7 @@ public function includeJsModule(string $moduleName, bool $async = false, array $ public function getModuleUri(string $moduleName, string $type = 'modern', $config = null) { return Template::raw( - Twigpack::$plugin->manifest->getModule($moduleName, $type, $config) ?? '' + Twigpack::$plugin->manifest->getModule($moduleName, $type, $config) ); } @@ -126,7 +124,7 @@ public function getModuleUri(string $moduleName, string $type = 'modern', $confi * * @param string $moduleName * @param string $type - * @param null $config + * @param null $config * * @return null|Markup * @throws NotFoundHttpException @@ -134,7 +132,7 @@ public function getModuleUri(string $moduleName, string $type = 'modern', $confi public function getModuleHash(string $moduleName, string $type = 'modern', $config = null) { return Template::raw( - Twigpack::$plugin->manifest->getModuleHash($moduleName, $type, $config) ?? '' + Twigpack::$plugin->manifest->getModuleHash($moduleName, $type, $config) ); } @@ -148,7 +146,7 @@ public function getModuleHash(string $moduleName, string $type = 'modern', $conf public function includeSafariNomoduleFix(array $attributes = []): Markup { return Template::raw( - Twigpack::$plugin->manifest->getSafariNomoduleFix($attributes) ?? '' + Twigpack::$plugin->manifest->getSafariNomoduleFix($attributes) ); } @@ -162,7 +160,7 @@ public function includeSafariNomoduleFix(array $attributes = []): Markup public function includeFile(string $path): Markup { return Template::raw( - Twigpack::$plugin->manifest->getFile($path) ?? '' + Twigpack::$plugin->manifest->getFile($path) ); } @@ -171,14 +169,14 @@ public function includeFile(string $path): Markup * * @param string $fileName * @param string $type - * @param null $config + * @param null $config * * @return Markup */ public function includeFileFromManifest(string $fileName, string $type = 'legacy', $config = null): Markup { return Template::raw( - Twigpack::$plugin->manifest->getFileFromManifest($fileName, $type, $config) ?? '' + Twigpack::$plugin->manifest->getFileFromManifest($fileName, $type, $config) ); } } From c933d79284588b82fe4533102a06e910a5e72ccf Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Fri, 5 Apr 2024 15:56:57 -0400 Subject: [PATCH 3/7] refactor: Updated docs to use node 20 & a new sitemap plugin --- docs/.gitignore | 2 + docs/Dockerfile | 6 +- docs/Makefile | 82 +- docs/README.md | 74 + docs/docs/.vitepress/config.js | 24 - docs/docs/.vitepress/config.ts | 48 + .../theme/{SidebarBottom.vue => NYSLogo.vue} | 11 +- docs/docs/.vitepress/theme/custom.css | 4 + docs/docs/.vitepress/theme/index.js | 42 - docs/docs/.vitepress/theme/index.ts | 42 + docs/docs/@types/shims.d.ts | 7 + .../{resources => public}/img/nys-logo.svg | 0 docs/docs/public/img/plugin-logo.svg | 27 + docs/docs/vite.config.js | 26 - docs/docs/vite.config.ts | 26 + docs/package-lock.json | 5188 +++++++++++------ docs/package.json | 8 +- docs/tsconfig.json | 16 + 18 files changed, 3823 insertions(+), 1810 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/docs/.vitepress/config.js create mode 100644 docs/docs/.vitepress/config.ts rename docs/docs/.vitepress/theme/{SidebarBottom.vue => NYSLogo.vue} (81%) delete mode 100644 docs/docs/.vitepress/theme/index.js create mode 100644 docs/docs/.vitepress/theme/index.ts create mode 100644 docs/docs/@types/shims.d.ts rename docs/docs/{resources => public}/img/nys-logo.svg (100%) create mode 100644 docs/docs/public/img/plugin-logo.svg delete mode 100644 docs/docs/vite.config.js create mode 100644 docs/docs/vite.config.ts create mode 100644 docs/tsconfig.json diff --git a/docs/.gitignore b/docs/.gitignore index 26d6131..41eaf24 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,4 @@ /vendor /node_modules +/docs/.vitepress/dist +/docs/.vitepress/cache diff --git a/docs/Dockerfile b/docs/Dockerfile index 3dba116..f73791f 100644 --- a/docs/Dockerfile +++ b/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/ diff --git a/docs/Makefile b/docs/Makefile index d9ef19d..7caf20c 100644 --- a/docs/Makefile +++ b/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/twigpack +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/twigpack/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 update 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: docker install update - ${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 -update: docker - ${DOCKERRUN} \ - update -npm: docker - ${DOCKERRUN} \ - $(filter-out $@,$(MAKECMDGOALS)) +# 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 +# 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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..fb9f7f3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,74 @@ +# `twigpack` docs + +This buildchain is a self-contained build system for the `twigpack` 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. diff --git a/docs/docs/.vitepress/config.js b/docs/docs/.vitepress/config.js deleted file mode 100644 index 65955a6..0000000 --- a/docs/docs/.vitepress/config.js +++ /dev/null @@ -1,24 +0,0 @@ -module.exports = { - title: 'Twigpack Plugin Documentation', - description: 'Documentation for the Twigpack plugin', - base: '/docs/twigpack/', - lang: 'en-US', - head: [ - ['meta', { content: 'https://github.com/nystudio107', property: 'og:see_also', }], - ['meta', { content: 'https://www.youtube.com/channel/UCOZTZHQdC-unTERO7LRS6FA', property: 'og:see_also', }], - ['meta', { content: 'https://www.facebook.com/newyorkstudio107', property: 'og:see_also', }], - ], - themeConfig: { - repo: 'nystudio107/craft-twigpack', - docsDir: 'docs/docs', - docsBranch: 'v1', - algolia: { - apiKey: 'd1b7baa35f1ccbaeb2e5f343f555fe4a', - indexName: 'twigpack' - }, - editLinks: true, - editLinkText: 'Edit this page on GitHub', - lastUpdated: 'Last Updated', - sidebar: 'auto', - }, -}; diff --git a/docs/docs/.vitepress/config.ts b/docs/docs/.vitepress/config.ts new file mode 100644 index 0000000..d9ed550 --- /dev/null +++ b/docs/docs/.vitepress/config.ts @@ -0,0 +1,48 @@ +import {defineConfig} from 'vitepress' + +export default defineConfig({ + title: 'Twigpack Plugin', + description: 'Documentation for the Twigpack plugin', + base: '/docs/twigpack/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-twigpack/edit/develop/docs/docs/:path', + text: 'Edit this page on GitHub' + }, + algolia: { + appId: '4Q1XLYYORS', + apiKey: '62bbd46c6e5480c2fa8f8eda43a427fd', + indexName: 'twigpack', + searchParameters: { + facetFilters: ["version:v1"], + }, + }, + lastUpdatedText: 'Last Updated', + sidebar: [], + nav: [ + {text: 'Home', link: 'https://nystudio107.com/plugins/twigpack'}, + {text: 'Store', link: 'https://plugins.craftcms.com/twigpack'}, + {text: 'Changelog', link: 'https://nystudio107.com/plugins/twigpack/changelog'}, + {text: 'Issues', link: 'https://github.com/nystudio107/craft-twigpack/issues'}, + { + text: 'v1', items: [ + {text: 'v5', link: 'https://nystudio107.com/docs/twigpack/'}, + {text: 'v4', link: 'https://nystudio107.com/docs/twigpack/v4/'}, + {text: 'v1', link: '/'}, + ], + }, + ] + }, +}); diff --git a/docs/docs/.vitepress/theme/SidebarBottom.vue b/docs/docs/.vitepress/theme/NYSLogo.vue similarity index 81% rename from docs/docs/.vitepress/theme/SidebarBottom.vue rename to docs/docs/.vitepress/theme/NYSLogo.vue index a2691f3..5a69068 100644 --- a/docs/docs/.vitepress/theme/SidebarBottom.vue +++ b/docs/docs/.vitepress/theme/NYSLogo.vue @@ -6,18 +6,15 @@ target="_blank" rel="noopener" > - + /> -