Merge pull request #351 from Lombiq/issue/OSOE-744

OSOE-744: Add wrapper for the markdownlint-cli2 action

.github/actions/markdown-lint/action.yml

@@ -0,0 +1,72 @@
+name: Markdown Linting
+description: >
+  Lints markdown files by wrapping the markdownlint-cli2 action
+  (https://github.com/DavidAnson/markdownlint-cli2-action).
+
+# When updating defaults here also update them in the `markdown-lint` workflow. These parameters are passed on directly
+# to the markdownlint-cli2 action, see: https://github.com/DavidAnson/markdownlint-cli2-action/blob/main/action.yml.
+inputs:
+  config:
+    description: Path to a file to use for the base configuration object (defaults to "lombiq.markdownlint.json").
+    default: 'lombiq.markdownlint.json'
+    required: false
+  fix:
+    description: Whether to fix issues automatically for the rules that support it (any truthy value enables).
+    default: ''
+    required: false
+  globs:
+    description: Glob expression(s) of files to lint (newline-delimited).
+    default: '**/*.{md,markdown}'
+    required: false
+  separator:
+    description: String to use as a separator for the "globs" input (defaults to newline).
+    default: "\n"
+    required: false
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Markdown Linting
+      # When upgrading, also update Lombiq.NodeJs.Extensions to use the corresponding version of the markdownlint
+      # package.
+      uses: DavidAnson/markdownlint-cli2-action@b4c9feab76d8025d1e83c653fa3990936df0e6c8 # v16.0.0
+      with:
+        config: ${{ inputs.config }}
+        fix: ${{ inputs.fix }}
+        globs: ${{ inputs.globs }}
+        separator: ${{ inputs.separator }}
+
+    - name: Setup Scripts
+      shell: pwsh
+      run: (Resolve-Path "${{ github.action_path }}/../../../Scripts").Path >> $Env:GITHUB_PATH
+
+    - name: Copy files updated by markdown-lint automatic fixes
+      if: inputs.fix == 'true'
+      id: markdown-lint-fix-files
+      shell: pwsh
+      run: |
+        $artifactFolder = [System.Guid]::NewGuid()
+        $files = git diff --name-only '*.md' '*.markdown'
+        $files | ForEach-Object {
+          $destination = "$artifactFolder/$PSItem"
+          New-Item -ItemType File -Path $destination -Force
+          Copy-Item -Path $PSItem -Destination $destination -Force
+        }
+
+        Set-GitHubOutput 'has-fixes' ($files.Length -gt 0).ToString().ToLower()
+        Set-GitHubOutput 'artifact-path' $artifactFolder
+
+    - name: Upload files fixed by markdown-lint
+      uses: Lombiq/GitHub-Actions/.github/actions/upload-artifact@dev
+      if: inputs.fix == 'true' && steps.markdown-lint-fix-files.outputs.has-fixes == 'true'
+      with:
+        name: markdown-lint-fixed-files
+        path: ${{ steps.markdown-lint-fix-files.outputs.artifact-path }}
+        retention-days: 1
+
+    - name: Fail workflow if markdown-lint fixes were made
+      if: inputs.fix == 'true' && steps.markdown-lint-fix-files.outputs.has-fixes == 'true'
+      shell: pwsh
+      run: |
+        Write-Output '::error::Some files were modified by markdown-lint and are available to download as artifacts.'
+        exit 1

.github/actions/markdown-lint/lombiq.markdownlint.json

@@ -0,0 +1,9 @@
+// When updating, also update the same configuration file in Lombiq.NodeJs.Extensions.
+{
+    "default": true,
+    "MD004": { "style": "dash" },
+    "MD013": false,
+    "MD033": { "allowed_elements": [ "kbd" ] },
+    "MD049": { "style": "underscore" },
+    "MD050": { "style": "asterisk" }
+}

.github/actions/spelling/dictionaries/Lombiq.common.txt

@@ -71,6 +71,7 @@ linting
 loglevel
 lombiq
 lucene
+markdownlint
 mediafield
 mediatheme
 mentoring

.github/actions/yaml-lint/action.yml

@@ -1,7 +1,6 @@
 name: YAML Linting
 description: Runs a linter on YAML files.
 
-
 inputs:
   config-file-path:
     description: 'Path to the yamllint configuration file'
@@ -14,7 +13,7 @@ inputs:
     default: '.'
 
 runs:
-  using: "composite"
+  using: 'composite'
   steps:
     - name: Run yamllint
       run: yamllint -c "${{ inputs.config-file-path }}" "${{ inputs.search-path }}"

.github/workflows/markdown-lint-this-repo.yml

@@ -0,0 +1,17 @@
+name: Markdown Linting
+
+# Runs for PRs opened for any branch, and pushes to the dev branch.
+on:
+  pull_request:
+  push:
+    branches:
+      - dev
+
+jobs:
+  markdown-linting:
+    name: Markdown Linting
+    uses: Lombiq/GitHub-Actions/.github/workflows/markdown-lint.yml@dev
+    with:
+      globs: '**/*.{md,markdown};!License.md'
+      separator: ';'
+      fix: true

.github/workflows/markdown-lint.yml

@@ -0,0 +1,62 @@
+name: Markdown Linting
+
+on:
+  workflow_call:
+    secrets:
+      CHECKOUT_TOKEN:
+        required: false
+        description: >
+          The GitHub token to authenticate checkout. Pass in a GitHub personal access token if authenticated submodules
+          are used.
+
+    # When updating defaults here also update them in the `markdown-lint` action.
+    inputs:
+      cancel-workflow-on-failure:
+        description: When set to "true", it will cancel the current workflow run with all jobs if this workflow fails.
+        type: string
+        default: 'true'
+      config:
+        description: Path to a file to use for the base configuration object (defaults to "lombiq.markdownlint.json").
+        type: string
+        default: '.github/actions/markdown-lint/lombiq.markdownlint.json'
+      fix:
+        description: Whether to fix issues automatically for the rules that support it (any truthy value enables).
+        type: string
+        default: ''
+      globs:
+        description: Glob expression(s) of files to lint (newline-delimited).
+        type: string
+        default: '**/*.{md,markdown}'
+      separator:
+        description: String to use as a separator for the "globs" input (defaults to newline).
+        type: string
+        default: "\n"
+      timeout-minutes:
+        type: number
+        default: 1
+        description: Configuration for the timeout-minutes parameter of the workflow.
+
+jobs:
+  markdown-linting:
+    name: Markdown Linting
+    runs-on: ubuntu-22.04
+    timeout-minutes: ${{ inputs.timeout-minutes }}
+    steps:
+      - name: Checkout
+        uses: Lombiq/GitHub-Actions/.github/actions/checkout@dev
+        with:
+          token: ${{ secrets.CHECKOUT_TOKEN }}
+
+      - name: Markdown Linting
+        uses: Lombiq/GitHub-Actions/.github/actions/markdown-lint@dev
+        with:
+          config: ${{ inputs.config }}
+          fix: ${{ inputs.fix }}
+          globs: ${{ inputs.globs }}
+          separator: ${{ inputs.separator }}
+
+      - name: Cancel Workflow on Failure
+        if: failure() && inputs.cancel-workflow-on-failure == 'true'
+        uses: Lombiq/GitHub-Actions/.github/actions/cancel-workflow@dev
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/spelling-this-repo.yml

@@ -15,3 +15,7 @@ jobs:
     with:
       additional-dictionaries: |
         cspell:companies/src/companies.txt
+      additional-configuration-source-prefixes: >
+        {
+          "lombiq-lgha": "https://raw.githubusercontent.com/Lombiq/GitHub-Actions/dev/.github/actions/spelling/"
+        }

.github/workflows/spelling.yml

@@ -104,7 +104,7 @@ jobs:
         run: |
           git config --global user.email "you@example.com"
           git config --global user.name "Your Name"
-          Remove-Item .\.git\ -recurse -force
+          Remove-Item .\.git\ -Recurse -Force
           git init .
           git add .
           git commit -m 'stub commit -- includes submodules'

.github/workflows/yaml-lint.yml

@@ -19,7 +19,7 @@ on:
         description: If set to "true", this will cancel the current workflow run with all jobs if this workflow fails.
         required: false
         type: string
-        default: "true"
+        default: 'true'
       config-file-path:
         description: 'Path to the yamllint configuration file'
         required: true

Docs/Actions.md

@@ -29,10 +29,12 @@ In addition to the below short explanations, check out the inline documentation
 - `cancel-workflow`: Cancels the current workflow run, i.e. all jobs. Useful if you want to cancel the rest of the workflow when one job fails. Suitable workflows in this project expose this functionality via the `cancel-workflow-on-failure` parameter.
 - `check-merge-conflict`: Labels and comments on pull requests with merge conflicts.
 - `create-jira-issues-for-community-activities`: Creates Jira issues for community activities happening on GitHub, like issues, discussions, and pull requests being opened. Pull requests are only taken into account if they're not already related to a Jira issue (by starting their title with a Jira issue key).
+- `markdown-lint`: Checks for linting errors in markdown files, allowing for an optional configuration file to be used. Based on the [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2-action) action.
 - `publish-nuget`: Publishes the content of the current directory as a NuGet package.
 - `update-github-issue-and-pull-request`: Adds the Jira issue key prefix and link to pull requests as well as a Fixes reference to a GitHub issue, if a suitable one is found.
 - `verify-submodule-pull-request`: Assuming that the current repository is a submodule in another repository, this action verifies that a pull request with a matching issue code has been opened there as well.
 - `spelling`: Checks for spelling mistakes in a repository. Check out [this action's own documentation](SpellCheckingConfiguration.md) on how to use it and contribute to the configuration and dictionaries.
+- `yaml-lint`: Checks for linting errors in YAML-files, allowing for an optional configuration file to be used.
 
 ## Azure hosting
 

Docs/Workflows.md

@@ -25,12 +25,13 @@ These features are designed to reduce resource usage (like paid GitHub Actions m
 ## Productivity
 
 - [Create Jira issues for community activities](Workflows/Productivity/CreateJiraIssuesForCommunityActivities.md)
+- [Markdown linting](Workflows/Productivity/MarkdownLinting.md)
 - [Post-pull request checks automation](Workflows/Productivity/PostPullRequestChecksAutomation.md)
 - [Publish NuGet package](Workflows/Productivity/PublishNuGetPackage.md)
 - [Spell-checking](Workflows/Productivity/SpellChecking.md)
 - [Validate pull request](Workflows/Productivity/ValidatePullRequest.md)
 - [Validate submodule](Workflows/Productivity/ValidateSubmodule.md)
-- [Lint YAML files](Workflows/Productivity/YamlLinting.md)
+- [YAML linting](Workflows/Productivity/YamlLinting.md)
 
 ## Azure hosting
 

Docs/Workflows/Productivity/MarkdownLinting.md

@@ -0,0 +1,16 @@
+# Markdown Linting
+
+This workflow uses [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) through its wrapper action for linting markdown files according to an optional configuration file. Such a configuration file includes a set of rules that are checked against when linting the files and can be found in `../../../.github/actions/markdown-lint/lombiq.markdownlint.json` and is used by default.
+
+You would typically consume the corresponding GHA workflow for markdown linting like this:
+
+```yaml
+...
+
+jobs:
+    markdown-linting:
+        name: Markdown Linting
+        uses: Lombiq/GitHub-Actions/.github/workflows/markdown-lint.yml@dev
+```
+
+The list of input parameters specific to the behavior of `markdownlint` are the the same as its wrapper action and [described in its readme](https://github.com/DavidAnson/markdownlint-cli2-action?tab=readme-ov-file#inputs). The values are passed on directly, but the defaults are changed to use Lombiq's configuration file.

Docs/Workflows/Productivity/YamlLinting.md

@@ -1,6 +1,6 @@
 # YAML Linting
 
-This solution uses [`yamllint`](https://github.com/adrienverge/yamllint) for linting YAML files according to a configuration file. Such a configuration file includes a set of rules that are checked against when linting the files and can be found in `/.trunk/configs/.yamllint.yaml`.
+This workflow uses [`yamllint`](https://github.com/adrienverge/yamllint) for linting YAML files according to a configuration file. Such a configuration file includes a set of rules that are checked against when linting the files and can be found in `/.trunk/configs/.yamllint.yaml`.
 
 You would typically consume the corresponding GHA workflow for YAML linting like this: