diff --git a/.github/actions/markdown-lint/action.yml b/.github/actions/markdown-lint/action.yml new file mode 100644 index 000000000..070b3628c --- /dev/null +++ b/.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 diff --git a/.github/actions/markdown-lint/lombiq.markdownlint.json b/.github/actions/markdown-lint/lombiq.markdownlint.json new file mode 100644 index 000000000..0fa4eeb9f --- /dev/null +++ b/.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" } +} diff --git a/.github/actions/spelling/dictionaries/Lombiq.common.txt b/.github/actions/spelling/dictionaries/Lombiq.common.txt index c1049bde0..6af2e7967 100644 --- a/.github/actions/spelling/dictionaries/Lombiq.common.txt +++ b/.github/actions/spelling/dictionaries/Lombiq.common.txt @@ -71,6 +71,7 @@ linting loglevel lombiq lucene +markdownlint mediafield mediatheme mentoring diff --git a/.github/actions/yaml-lint/action.yml b/.github/actions/yaml-lint/action.yml index 3fbf5d0e1..b2a9bef23 100644 --- a/.github/actions/yaml-lint/action.yml +++ b/.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 }}" diff --git a/.github/workflows/markdown-lint-this-repo.yml b/.github/workflows/markdown-lint-this-repo.yml new file mode 100644 index 000000000..0da9c27ee --- /dev/null +++ b/.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 diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 000000000..8834ddca4 --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/spelling-this-repo.yml b/.github/workflows/spelling-this-repo.yml index cc1d2dd9b..0a0cd4826 100644 --- a/.github/workflows/spelling-this-repo.yml +++ b/.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/" + } diff --git a/.github/workflows/spelling.yml b/.github/workflows/spelling.yml index 0348e9230..8808148f0 100644 --- a/.github/workflows/spelling.yml +++ b/.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' diff --git a/.github/workflows/yaml-lint.yml b/.github/workflows/yaml-lint.yml index 820076307..749776747 100644 --- a/.github/workflows/yaml-lint.yml +++ b/.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 diff --git a/Docs/Actions.md b/Docs/Actions.md index f6d487396..f90ee050a 100644 --- a/Docs/Actions.md +++ b/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 diff --git a/Docs/Workflows.md b/Docs/Workflows.md index 38dd02d45..ee1f7ea8d 100644 --- a/Docs/Workflows.md +++ b/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 diff --git a/Docs/Workflows/Productivity/MarkdownLinting.md b/Docs/Workflows/Productivity/MarkdownLinting.md new file mode 100644 index 000000000..da32ab956 --- /dev/null +++ b/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. diff --git a/Docs/Workflows/Productivity/YamlLinting.md b/Docs/Workflows/Productivity/YamlLinting.md index 82d14587d..d43ff8290 100644 --- a/Docs/Workflows/Productivity/YamlLinting.md +++ b/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: