ci: add file linting for size and name (#63)

See PR description for all changes

.github/CODEOWNERS

@@ -0,0 +1 @@
+/docs/ @RocketLeagueMapmaking/guide

.github/labeler.yml

@@ -0,0 +1,35 @@
+'section: blender':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/blender/**
+
+'section: decryption':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/decryption/**
+
+'section: get started':
+  - changed-files:
+    - any-glob-to-any-file: docs/essential/**
+
+'section: kismet':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/kismet/**
+
+'section: misc':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/misc/**
+
+'section: multiplayer':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/multiplayer/**
+
+'section: textures':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/textures/**
+
+'section: udk':
+  - changed-files:
+    - any-glob-to-any-file: docs/guide/udk/**
+
+config:
+  - changed-files:
+    - any-glob-to-any-file: docs/.vitepress/config/**

.github/workflows/deploy.yml

@@ -20,19 +20,34 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       docker_digest: ${{ steps.docker.outputs.digest }}
+    strategy:
+      matrix:
+        # Set the same version as in Dockerfile
+        node: [18]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install node.js v18
+      - name: Install node.js v${{ matrix.node }}
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: ${{ matrix.node }}
           cache: npm
 
       - name: Install dependencies
         run: npm ci
 
+        # Run lint and build first to make sure the site will still build
+        # since workflow dispatch can be run on failed builds
+      - name: Run eslint
+        run: npm run lint
+
+      - name: Run markdown lint
+        run: npm run lint-markdown
+
+      - name: Run file lint
+        run: npm run lint-files
+
       - name: Check guide build
         run: npm run docs:build
 
@@ -72,7 +87,7 @@ jobs:
           script: |
             cd ${{ vars.SSH_PROJECT_ROOT }}
             sh deployment/update_and_deploy.sh ${{ github.event.inputs.version }}
-            cd ..
+            cd ${{ vars.SSH_PROJECT_DUMMY_SCRIPT_ROOT }}
             sh move_dummyassets.sh
 
       - name: Send webhook result

.github/workflows/labeler.yml

@@ -0,0 +1,14 @@
+name: "Pull Request Labeler"
+on:
+  - pull_request_target
+
+jobs:
+  labeler:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          sync-labels: true

.github/workflows/preview.yml

@@ -24,6 +24,10 @@ jobs:
         runs-on: ubuntu-latest
         needs: [check-api-key]
         if: needs.check-api-key.outputs.api-key == 'true'
+        strategy:
+          matrix:
+            # Set the same version as in Dockerfile
+            node: [18]
         permissions:
             contents: read
             deployments: write
@@ -32,10 +36,10 @@ jobs:
             - name: Checkout
               uses: actions/checkout@v4
 
-            - name: Install node.js v18
+            - name: Install node.js v${{ matrix.node }}
               uses: actions/setup-node@v4
               with:
-                node-version: 18
+                node-version: ${{ matrix.node }}
                 cache: npm
 
             - name: Install dependencies

.github/workflows/test.yml

@@ -2,16 +2,20 @@ name: Test
 on: [push, pull_request]
 jobs:
   lint:
-    name: Lint
+    name: Lint & test v${{ matrix.node }}
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Run for both the node version used and the next major version
+        node: [18, 20]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Install node.js v18
+      - name: Install node.js v${{ matrix.node }}
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: ${{ matrix.node }}
           cache: npm
 
       - name: Install dependencies
@@ -23,6 +27,9 @@ jobs:
       - name: Run markdown lint
         run: npm run lint-markdown
 
+      - name: Run file lint
+        run: npm run lint-files
+
         # Broken links are checked by VitePress on building
         # Make sure that ignoreDeadlinks is enabled!
         # https://vitepress.dev/reference/site-config#ignoredeadlinks

.ls-lint.yml

@@ -0,0 +1,42 @@
+ls:
+  deployment:
+    .sh: snakecase
+
+  .github:
+    '{ISSUE_TEMPLATE,workflows}':
+      .yml: snakecase
+
+  docs:
+    .dir: lowercase
+    .md: snakecase
+
+    .vitepress:
+      .ts: lowercase
+
+      public:
+        .png: exists:0
+
+        # All icons should be snake case
+        icons:
+          .png: regex:logo_(\w|_|\d)+
+
+        images:
+          # TODO: add this when ls-lint adds this
+          # .png: not_regex:image\d+
+
+          # All images should be in the following folders only
+          '{blender,udk}/*':
+            .dir: regex:(basics|advanced|essential) | regex:(04_modeling|05_blender_course)
+
+    '{cheatsheet,essential,guide/**/}':
+      .md: regex:index|\d{2}_([a-z_])*
+
+      # Overwrite md rule only for the flowchart folder
+      flowchart_questions:
+        .md: snakecase
+
+ignore:
+  - .git
+  - node_modules
+  - docs/.vitepress/cache
+  - docs/.vitepress/dist

.markdownlint.json

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

CONTRIBUTING.md

@@ -15,13 +15,27 @@ Contribution should be performed through a number of simple steps:
 
 We have some minor style requirements for documentation additions:
 
-- Always proofread your submissions. PRs that contain spelling mistakes or incorrect grammar will be denied.
-- When naming your readme files and folders, use [snake_case](https://en.wikipedia.org/wiki/Snake_case) for file naming conventions.
+- Always proofread your submissions. PRs that contain spelling mistakes or incorrect grammar will be requested for changes.
+- All checks must pass before the pull request can be merged.
+- When adding folders:
+  - use lowercase for folder naming conventions.
+  - add an `index.md` file is present in all new `/docs/` folders, if this is needed. Usually you would describe the content in this folder or some general content that does not need a separate file.
+- When naming your files:
+  - use [snake_case](https://en.wikipedia.org/wiki/Snake_case) for file naming conventions. Only use lowercase for TypeScript files.
+  - If you are adding markdown files in the `docs` folder:
+    - use `\d{2}_([a-z_])*.md` for naming all other files in the `/cheatsheet/`, `/essential/` and `/guide/**/` folders.
+    - add the following frontmatter to new files:
+      - `title` (`string`): The topic of the current page.
+      - `advanced` (`boolean`): Whether this page is an advanced guide. Only needed on pages when a folder has an advanced section (`/guide/blender/` and `/guide/udk/`).
 - If you are changing / adding content related to UDK, check your changes in UDK (only follow the content you have written and not your own knowledge). Any PR with changes in UDK should be reviewed.
 - If you are adding image resources:
-  - pay attention to their file size: images above 5MB will not be accepted, and anything above 1MB should be reviewed.
-  - Images should be added in `/docs/.vitepress/public/images` and icons in `/docs/.vitepress/public/icons`
-- [Create an issue](https://github.com/rocketleaguemapmaking/RL-docs/issues/new/choose) for small contributions (such as fixing typos or broken links)
+  - pay attention to their file size: images above 1MB will fail the tests and should be reviewed. Use an online compressor tool or [Windows PowerToys' Image resizer](https://learn.microsoft.com/en-us/windows/powertoys/image-resizer) to make sure that the file size is below the limit.
+  - Images should be added in `/docs/.vitepress/public/images/{section}/` and icons in `/docs/.vitepress/public/icons`.
+  - Images and icons should have relevant file names to their content and be named in snake_case. Icons should also be prefixed by `logo_`.
+  - Images are not allowed directly in `/images/`, `/images/blender/` and `/images/udk/`, only the subdirectories of those folders.
+  - Image references in markdown should [have a good alt text](https://supercooldesign.co.uk/blog/how-to-write-good-alt-text). They can also have [a title](https://www.markdownguide.org/basic-syntax/#images-1) with a comment or small joke. Images of icons don't need to have an alt text.
+  - Images should have a line break (`---` with one white line above) between each other if no other text is between the images.
+- [Create an issue](https://github.com/rocketleaguemapmaking/RL-docs/issues/new/choose) for small contributions (such as fixing typos or broken links).
 
 # Development and local testing
 
@@ -53,9 +67,9 @@ The project utilises `vitepress` in order to create pages for our documentation,
 To share a local build of the current branch:
 
 1. Execute `npm install` from the root of the repository.
-2. Log into the rlmm / your own Cloudflare account with `npx wrangler login` and complete the oauth2 flow.
+2. Log into the RLMM / your own Cloudflare account with `npx wrangler login` and complete the oauth2 flow.
 3. Execute `npm run docs:build`
-4. Execute `npx wrangler pages publish ./docs/.vitepress/dist/ --project-name=rocketleaguemapmaking --branch=<branch>`.
+4. Execute `npx wrangler pages deploy ./docs/.vitepress/dist/ --project-name=rocketleaguemapmaking --branch=<branch>`.
 Replace `<branch>` with the name of the current branch.
 
 ## Theme
@@ -64,3 +78,11 @@ This guide uses a custom guide theme. The theme [`theme-rlmm`](https://theme-rlm
 
 - Any theme modification should be in `docs/.vitepress/theme/`
 - Feature requests and issues with the theme (components) should be opened in the [theme repository](https://github.com/rocketleaguemapmaking/theme-rlmm)
+
+Furthermore, this repo has the following `pageClass`es available:
+
+- `page-inline-images`: makes all images on the page display inline. This is used for pages with lists with an icon at the beginning of each item.
+
+The following components (not including the components registered by the theme) are also registered globally:
+
+- `DocFeatures`

docs/.vitepress/config/head.ts

@@ -27,7 +27,7 @@ export default <HeadConfig[]>[
     ],
     ['meta',
         {
-            name: 'apple-mobile-web-app-capable',
+            name: 'mobile-web-app-capable',
             content: 'yes'
         }
     ],
@@ -37,29 +37,39 @@ export default <HeadConfig[]>[
             content: 'black'
         }
     ],
-    ['link',
+
+    // OG links
+    // Not including the special Twitter links, because X...
+
+    ['meta',
         {
-            rel: 'apple-touch-icon',
-            href: '/icons/apple-touch-icon-152x152.png'
+            property: 'og:type',
+            content: 'website',
         }
     ],
-    ['link',
+    ['meta',
         {
-            rel: 'mask-icon',
-            href: '/icons/safari-pinned-tab.svg',
-            color: '#3eaf7c'
+            property: 'og:url',
+            content: 'https://rocketleaguemapmaking.com/',
         }
     ],
     ['meta',
         {
-            name: 'msapplication-TileImage',
-            content: '/icons/msapplication-icon-144x144.png'
+            property: 'og:title',
+            content: 'RLMM',
         }
     ],
     ['meta',
         {
-            name: 'msapplication-TileColor',
-            content: '#000000'
+            property: 'og:description',
+            content: '',
         }
     ],
+    // TODO: create a preview image
+    // ['meta',
+    //     {
+    //         property: 'og:image',
+    //         content: '',
+    //     }
+    // ],
 ]