Add cheatsheets to the guide (#65)

Author: ghostrider-05

.github/workflows/deploy.yml

@@ -18,6 +18,10 @@ on:
         description: "Send a webhook message in the #website channel after deployment"
         type: boolean
         default: true
+      run_linting:
+        description: "Run the linting scripts on the documentation"
+        type: boolean
+        default: true
 jobs:
   build:
     name: Build image
@@ -45,12 +49,15 @@ jobs:
         # since workflow dispatch can be run on failed builds
       - name: Run eslint
         run: npm run lint
+        if: inputs.run_linting
 
       - name: Run markdown lint
         run: npm run lint-markdown
+        if: inputs.run_linting
 
       - name: Run file lint
         run: npm run lint-files
+        if: inputs.run_linting
 
       - name: Check guide build
         run: npm run docs:build

.ls-lint.yml

@@ -21,8 +21,7 @@ ls:
           .png: regex:logo_(\w|_|\d)+
 
         images:
-          # TODO: add this when ls-lint adds this
-          # .png: not_regex:image\d+
+          .png: not_regex:image\d+
 
           # All images should be in the following folders only
           '{blender,udk}/*':

.markdownlint.json

@@ -4,5 +4,6 @@
     "MD025": false,
     "MD029": false,
     "MD033": false,
-    "MD034": false
+    "MD034": false,
+    "MD045": false
 }

README.md

@@ -25,6 +25,7 @@ To update the site on the host machine, run [the `deploy` workflow](https://gith
 - push (default: `true`). Controls whether to push the built image to Docker hub. If `deploy` is enabled and `push` is disabled, the server will use an already pushed image with the same `version`, or fail.
 - deploy (default: `true`). Disable this to only build (and push) the Docker Image without deploying it.
 - webhook message (default: `true`): send a Discord message with the deployment details when the workflow is finished.
+- run linting (default: `true`): run all linting scripts before deploying the site.
 
 See the GitHub documentation for [how to run a workflow manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow#running-a-workflow).  
 

docs/.vitepress/config/cms/blocks.ts

@@ -1,14 +1,115 @@
-import { DecapCmsField } from 'vite-plugin-decap-cms'
+import { createField, DecapCmsField, fieldToSnakeCase, Options } from 'vite-plugin-decap-cms'
+
+import * as fields from './fields/'
+
+type Block = NonNullable<NonNullable<Options['script']>['markdownEditorComponents']>[number]
+
+interface ComponentBlockOptions {
+    id: string
+    label: string
+    props: DecapCmsField[]
+    templateField?: {
+        label: string
+        labelSingular: string
+        nameLabel?: string
+        contentLabel?: string
+        names?: string[]
+    }
+}
+
+// TODO: fix enters while transitioning
+function createComponentBlock (options: ComponentBlockOptions): Block {
+    const { id, label, props, templateField } = options
+
+    interface ComponentData {
+        templates: {
+            name: string | null;
+            content: string;
+        }[]
+        props: Record<string, unknown>
+    }
+
+    return {
+        id,
+        label,
+        pattern: new RegExp(`^<${id}(.*)>((.|\\n)*?)<\\/${id}>$`, 'm'),
+        fields: [
+            props.length > 0 ? createField('object', {
+                name: 'props',
+                label: 'Properties',
+                required: false,
+                collapsed: true,
+                fields: props.map(fieldToSnakeCase),
+            }) : undefined,
+            templateField != undefined ? createField('list', {
+                name: 'templates',
+                label: templateField.label,
+                label_singular: templateField.labelSingular,
+                allow_add: true,
+                required: false,
+                min: 1,
+                fields: [
+                    createField(templateField.names ? 'select' : 'string', {
+                        name: 'name',
+                        required: false,
+                        label: templateField.nameLabel ?? 'Name',
+                        // @ts-expect-error Errors bc of 'options' not in the string options
+                        options: templateField.names,
+                    }),
+                    createField('markdown', {
+                        name: 'content',
+                        required: true,
+                        label: templateField.contentLabel ?? 'Content',
+                    }),
+                ].filter((n): n is NonNullable<typeof n> => n != undefined),
+            }) : undefined,
+        ].filter(n => n) as Block['fields'],
+        fromBlock: function (match): ComponentData {
+            const props = match.at(1), slots = match.at(2)
+
+            return {
+                props: props != undefined
+                    ? props.split(/(?= :)(?<=")/)
+                        .map(str => str.trim().replace(':', '').split('=', 2))
+                        .reduce((obj, value) => ({ ...obj, [value[0]]: value[1] }), {})
+                    : {},
+                templates: slots != undefined
+                    ? slots.split('</template>').filter(str => str.length).map((slot) => {
+                        const results = /^<template #(.*)>(.*)/ms.exec(slot) ?? []
+                        const name = results.at(1)
+
+                        return {
+                            name: name ?? null,
+                            content: results.at(2) ?? slot,
+                        }
+                    }) : [],
+            }
+        },
+        toBlock: function (data: ComponentData) {
+            const templates = data.templates.map(({ name, content }) => {
+                return `<template${name ? ` #${name}` : ''}>\n${content}\n</template>`
+            })
+
+            const props = Object.entries(data.props)
+                .reduce((str, prop) => str + ` :${prop[0]}="${prop[1]}"`, ' ')
+
+            return `<${id}${props}>\n${templates}\n</${id}>`
+        },
+        toPreview: function () {
+            return ''
+        },
+    }
+}
 
 type BlockFields = { summary?: string, contents: string, type: string }
 
-export const customContainerBlock = {
+const customContainerBlock: Block = {
     id: 'custom-block',
-    label: 'Custom block',
+    label: 'Custom comtainer',
     fields: [
         {
             name: 'type',
-            label: 'Type of block',
+            label: 'Type of comtainer',
             widget: 'select',
             required: true,
             options: [
@@ -34,9 +135,8 @@ export const customContainerBlock = {
             widget: 'markdown'
         }
     ] satisfies DecapCmsField[],
-    // @ts-expect-error Needs flag to work
     pattern: /^:::(\w+)(.*?)\n(.*?)\n^:::$/ms,
-    fromBlock: function (match: RegExpMatchArray): BlockFields {
+    fromBlock: function (match): BlockFields {
         return {
             type: match[1],
             summary: match[2],
@@ -50,3 +150,37 @@ export const customContainerBlock = {
         return `:::${data.type} ${data.summary}\n${data.contents}\n:::`
     },
 }
+
+export default [
+    customContainerBlock,
+    createComponentBlock({
+        id: 'steps',
+        label: 'Steps component',
+        templateField: {
+            label: 'Steps',
+            labelSingular: 'step',
+        },
+        props: fields.stepsProperties,
+    }),
+    createComponentBlock({
+        id: 'tabs',
+        label: 'Tabs component',
+        templateField: {
+            label: 'Tabs',
+            labelSingular: 'tab',
+            nameLabel: 'Id',
+        },
+        props: fields.tabsProperties,
+    }),
+    createComponentBlock({
+        id: 'ActionBlock',
+        label: 'Action block component',
+        templateField: {
+            label: 'Content',
+            labelSingular: 'content',
+            names: ['left', 'right'],
+            nameLabel: 'Position',
+        },
+        props: [],
+    }),
+]

docs/.vitepress/config/cms/collections.ts

@@ -4,11 +4,12 @@ import { type DecapCmsCollection } from 'vite-plugin-decap-cms'
 import sidebar, { type Sidebar } from '../sidebar'
 
 import {
-    createFeaturePageField,
+    createFeaturesField,
     createHomePageFields,
+    createNotificationConfigFields,
     createSiteConfigFields,
-    createTeamPageField,
-} from './fields'
+    createTeamsField,
+} from './fields/'
 
 import {
     createAdvancedCollections,
@@ -46,6 +47,14 @@ export default function (): DecapCmsCollection[] {
                 },
                 additionalFields: createHomePageFields(),
             },
+            {
+                name: 'Notifications',
+                file: 'docs/.vitepress/config/data/notifications.json',
+                overwrites: {
+                    deleted: true,
+                },
+                additionalFields: createNotificationConfigFields(),
+            },
         ], {
             collection: {
                 create: false,
@@ -61,7 +70,11 @@ export default function (): DecapCmsCollection[] {
                     hidden: true,
                 },
                 additionalFields: [
-                    createTeamPageField(),
+                    createTeamsField({
+                        name: 'teams',
+                        label: 'Teams',
+                        label_singular: 'team',
+                    }),
                 ]
             },
             {
@@ -71,7 +84,7 @@ export default function (): DecapCmsCollection[] {
                     hidden: true,
                 },
                 additionalFields: [
-                    createFeaturePageField({
+                    createFeaturesField({
                         name: 'collision_types',
                         label: 'Collision types',
                         label_singular: 'type',
@@ -85,7 +98,7 @@ export default function (): DecapCmsCollection[] {
                     hidden: true,
                 },
                 additionalFields: [
-                    createFeaturePageField({
+                    createFeaturesField({
                         name: 'next_actions',
                         label: 'Next actions',
                         label_singular: 'action',
@@ -140,7 +153,8 @@ export default function (): DecapCmsCollection[] {
                 return createFolderCollection({
                     base,
                     label: config.text ?? items[0].text!,
-                    mediaFolder: '',
+                    description: config.description,
+                    mediaFolder: config.mediaFolder,
                 })
             }),
     ]

docs/.vitepress/config/cms/fields/components.ts

@@ -0,0 +1,29 @@
+import { createField } from 'vite-plugin-decap-cms'
+
+export const stepsProperties = [
+    createField('string', {
+        name: 'color',
+        label: 'Color',
+        required: false,
+    }),
+]
+
+export const tabsProperties = [
+    createField('list', {
+        name: 'tabs',
+        label: 'Tab names',
+        label_singular: 'name',
+        allow_add: true,
+        required: true,
+    }),
+    createField('string', {
+        name: 'startTab',
+        label: 'Start tab name',
+        required: false,
+    }),
+    createField('string', {
+        name: 'searchParam',
+        label: 'Search parameter',
+        required: false,
+    }),
+]