Add linting for the documentation and fix any current issues (#149)

Co-authored-by: Philipp Bammes <[email protected]>

.github/workflows/_lint-docs.yml

@@ -0,0 +1,14 @@
+name: Lint documentation
+
+on:
+  push:
+    paths:
+      - '**.md'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  wp-scripts-lint:
+    uses: inpsyde/reusable-workflows/.github/workflows/wp-scripts-lint.yml@main
+    with:
+      LINT_TOOLS: '["md-docs"]'

.gitignore

@@ -1,2 +1,5 @@
 ## PhpStorm
 .idea/
+
+## npm
+/node_modules/

README.md

@@ -45,3 +45,7 @@ groups here:
 * [Create plugin archive](./docs/archive-creation.md)
 * [Automatic release](./docs/automatic-release.md)
 * [DDEV Playwright](./docs/ddev-playwright.md)
+
+**Note:**
+
+Workflow files prefixed with `_` are specific to the repository and cannot be reused.

docs/archive-creation.md

@@ -12,7 +12,7 @@ To achieve that, the reusable workflow:
 6. Runs `wp dist-archive` to create the final archive (with builtin support for a `.distignore` file)
 7. Uploads it as an artifact for download or further processing
 
-## Simple usage example:
+## Simple usage example
 
 ```yml
 name: Create release package

docs/assets-compilation.md

@@ -2,7 +2,7 @@
 
 This workflow utilizes
 the [Composer Asset Compiler](https://github.com/inpsyde/composer-asset-compiler) to compile assets.
-For details, refer to https://github.com/inpsyde/composer-asset-compiler#pre-compilation.
+For details, refer to [Pre-compilation](https://github.com/inpsyde/composer-asset-compiler#pre-compilation).
 
 **Simplest possible example:**
 
@@ -16,9 +16,9 @@ jobs:
     uses: inpsyde/reusable-workflows/.github/workflows/build-assets-compilation.yml@main
 ```
 
-### Configuration parameters
+## Configuration parameters
 
-#### Inputs
+### Inputs
 
 | Name                  | Default                       | Description                                                                       |
 |-----------------------|-------------------------------|-----------------------------------------------------------------------------------|
@@ -30,7 +30,7 @@ jobs:
 | `COMPOSER_ARGS`       | `'--prefer-dist'`             | Set of arguments passed to Composer                                               |
 | `COMPILE_ASSETS_ARGS` | `'-v --env=root'`             | Set of arguments passed to Composer Asset Compiler                                |
 
-#### Secrets
+### Secrets
 
 | Name                  | Description                                                                              |
 |-----------------------|------------------------------------------------------------------------------------------|

docs/build-and-push-assets.md

@@ -51,7 +51,7 @@ is moved** to point to the commit that contains the compiled assets.
   to avoid running the workflow when no asset sources are changed. However, it should not be used
   for built branches and release branch strategies because the sync should happen on every push.
 
-## Simple usage example:
+## Simple usage example
 
 ```yml
 name: Build and push assets
@@ -192,8 +192,8 @@ The following table provides an overview when `COMPILE_SCRIPT_DEV` or `COMPILE_S
 |--------|--------------------|-----------------------|
 | `''`   | push to branch     | `COMPILE_SCRIPT_DEV`  |
 | `''`   | create release/tag | `COMPILE_SCRIPT_PROD` |
-| `dev`  | _not evaluated_    | `COMPILE_SCRIPT_DEV`  |
-| `prod` | _not evaluated_    | `COMPILE_SCRIPT_PROD` |
+| `dev`  | *not evaluated*    | `COMPILE_SCRIPT_DEV`  |
+| `prod` | *not evaluated*    | `COMPILE_SCRIPT_PROD` |
 
 **Example:** I want to push to a branch `production` and "production"-ready assets should be
 compiled:
@@ -260,7 +260,7 @@ same as the two commits would have been made as a single commit including both.
 > commit belongs to which "real" commit?
 
 As a side effect of using the
-recommended [concurrency settings] (https://docs.github.com/en/actions/using-jobs/using-concurrency)
+recommended [concurrency settings](https://docs.github.com/en/actions/using-jobs/using-concurrency)
 , the git history will be linear. The compilation commit would normally refer to the previous
 commit, whatever that is. In the case of cherry-picking or another non-linear branch merging, this "
 linearity" could be compromised. For this reason, the workflow adds to the commit message the commit
@@ -308,7 +308,7 @@ By passing a key associated with the GitHub user defined in the required `GITHUB
 workflow can install these packages.
 
 Please note that in such cases it is a good practice not to use a "personal" GitHub user, but an
-_ad-hoc_ "bot" user with an _ad-hoc_ private SSH key used only for the scope.
+*ad-hoc* "bot" user with an *ad-hoc* private SSH key used only for the scope.
 
 ---
 

docs/ddev-playwright.md

@@ -22,7 +22,7 @@ Use the DDEV env variables (`DDEV_ENV_VARS`) for debug flags of your project nee
 
 Also, it is possible to change some DDEV config values, such as the PHP version (`PHP_VERSION`).
 
-## Usage example:
+## Usage example
 
 ```yml
 name: Run Playwright tests via DDEV

docs/php.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD024 -->
+
 # Reusable workflows – PHP
 
 ## Coding standards analysis

docs/wp-scripts.md

@@ -67,7 +67,7 @@ jobs:
 ```
 
 ---
-**Note**
+**Note:**
 
 Stylelint [requires quotes](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#lint-style)
 around file glob patterns.