Merge pull request #7 from cycle/feat/markdown-linter

feat: markdown linter Makefile command and gh-action

.github/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at [email protected]. All
+reported by contacting the project team at <[email protected]>. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.
@@ -68,9 +68,9 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>

.github/CONTRIBUTING.md

@@ -12,19 +12,18 @@ Before you begin, you will need to set up your local development environment. He
 
 - **Operating System**: macOS Monterey+, Linux, or Windows with WSL2.
 - **Docker**: Version 26.0.0 or newer. Installation guides:
-    - [Docker on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04)
-    - [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/)
+  - [Docker on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04)
+  - [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/)
 - **Homebrew** (macOS only): Install via [brew.sh](https://brew.sh/).
 
 ### → Optional Tools
 
 - [Pre-commit](https://pre-commit.com) — Automates the running of git pre-commit hooks.
-    - Installation: `brew install pre-commit` and `make hooks`
+  - Installation: `brew install pre-commit` and `make hooks`
 - [Cz-git](https://cz-git.qbb.sh) — Commitizen adapter, that assists in formatting git commits.
-    - Installation: `brew install czg`
+  - Installation: `brew install czg`
 - [Act](https://github.com/nektos/act) — To run and test GitHub actions locally.
-    - Installation: `brew install act`
-
+  - Installation: `brew install act`
 
 <br>
 
@@ -35,7 +34,7 @@ This project uses a Makefile to streamline common development tasks. The Makefil
 Refer to the output of `make help` for a comprehensive list of available commands.
 
 ```bash
-$ make help
+make help
 ```
 
 ![Screenshot](../assets/screenshot.png)
@@ -67,15 +66,15 @@ Our project employs [GitHub Actions](https://github.com/features/actions) for co
 
 <br>
 
-## ✉️ Commit Message Guidelines
+## 📩 Commit Message Guidelines
 
 We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. Please structure your commit messages as follows, using the appropriate prefix:
 
 **Examples:**
 
 ```bash
-$ git commit -am 'feat: some feature was introduced'
-$ git commit -am 'fix: something has been fixed'
+git commit -am 'feat: some feature was introduced'
+git commit -am 'fix: something has been fixed'
 ```
 
 **Allowed Prefixes:**
@@ -109,7 +108,7 @@ We use [`yamllint`](https://github.com/adrienverge/yamllint) to enforce coding s
 To lint yaml files run:
 
 ```bash
-$ make lint-yaml
+make lint-yaml
 ```
 
 by default, [`cytopia/yamllint`](https://github.com/cytopia/docker-yamllint) Docker image will be used to run linter.
@@ -121,7 +120,7 @@ We use [`actionlint`](https://github.com/rhysd/actionlint) to enforce coding sta
 To lint GitHub Actions run:
 
 ```bash
-$ make lint-actions
+make lint-actions
 ```
 
 by default, [`rhysd/actionlint`](https://hub.docker.com/r/rhysd/actionlint/tags) Docker image will be used to run linter.
@@ -146,7 +145,7 @@ Our pre-commit configuration includes several hooks:
 To utilize these hooks, you first need to install them using the command provided by the Makefile:
 
 ```bash
-$ make hooks
+make hooks
 ```
 
 <br>

.github/workflows/integrate.yml

@@ -21,7 +21,6 @@ jobs:
       - name: 📦 Check out the codebase
         uses: actions/[email protected]
 
-      # See: https://github.com/wagoid/commitlint-github-action
       - name: 🧐 Lint commits using "commitlint"
         uses: wagoid/[email protected]
         with:
@@ -47,4 +46,21 @@ jobs:
           file_or_dir: '.'
           strict: true
 
+  markdown-linting:
+    timeout-minutes: 4
+    runs-on: ubuntu-latest
+    concurrency:
+      cancel-in-progress: true
+      group: markdown-linting-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+    steps:
+      - name: 📦 Check out the codebase
+        uses: actions/[email protected]
+
+      - name: 🧐 Lint Markdown files
+        uses: DavidAnson/[email protected]
+        with:
+          globs: |
+            **/*.md
+            !CHANGELOG.md
+
 ...

.markdownlint.json

@@ -0,0 +1,6 @@
+{
+    "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.34.0/schema/markdownlint-config-schema.json",
+    "line-length": false,
+    "no-inline-html": false,
+    "first-line-h1": false
+}

.pre-commit-config.yaml

@@ -2,15 +2,15 @@
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-added-large-files
       - id: fix-encoding-pragma
 
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: v3.20.0
+    rev: v3.24.0
     hooks:
       - id: commitizen
         stages:
@@ -23,4 +23,13 @@ repos:
         stages:
           - commit-msg
 
+  - repo: local
+    hooks:
+      - id: markdownlint
+        name: markdownlint-cli2
+        description: Run markdownlint-cli2 on your Markdown files using the docker image
+        language: docker_image
+        types: [markdown]
+        entry: davidanson/markdownlint-cli2-rules:latest
+
 ...

Makefile

@@ -12,6 +12,11 @@ ACTION_LINT_RUNNER ?= $(DOCKER) run --rm $$(tty -s && echo "-it" || echo) \
 	 rhysd/actionlint:latest \
 	 -color
 
+MARKDOWN_LINT_RUNNER ?= $(DOCKER) run --rm $$(tty -s && echo "-it" || echo) \
+	-v $(shell pwd):/app \
+	--workdir /app \
+	davidanson/markdownlint-cli2-rules:latest
+
 #
 # Self documenting Makefile code
 # ------------------------------------------------------------------------------------
@@ -73,7 +78,7 @@ hooks: ## Install git hooks from pre-commit-config
 	pre-commit autoupdate
 .PHONY: hooks
 
-lint: lint-yaml lint-actions ## Lint all files
+lint: lint-yaml lint-actions lint-md ## Lint all files
 .PHONY: lint
 
 lint-yaml: ## Lint all yaml files
@@ -84,6 +89,14 @@ lint-actions: ## Lint all github actions
 	@$(ACTION_LINT_RUNNER)
 .PHONY: lint-actions
 
+lint-md: ## Lint all markdown files using markdownlint-cli2
+	@$(MARKDOWN_LINT_RUNNER) --fix "**/*.md" "#CHANGELOG.md" | tee -a $(MAKE_LOGFILE)
+.PHONY: lint-md
+
+lint-md-dry: ## Lint all markdown files using markdownlint-cli2 in dry-run mode
+	@$(MARKDOWN_LINT_RUNNER) "**/*.md" "#CHANGELOG.md" | tee -a $(MAKE_LOGFILE)
+.PHONY: lint-md-dry
+
 #
 # Release
 # ------------------------------------------------------------------------------------

README.md

@@ -41,7 +41,6 @@ These tools encapsulate common and repetitive tasks, allowing for easy integrati
 - [Security Policy](#-security-policy)
 - [Contributing](#-want-to-contribute)
 - [Social Links](#-social-links)
-- [Author Information](#-author-information)
 - [Useful Resources](#-useful-resources)
 - [Contributors](#-contributors)
 
@@ -53,7 +52,7 @@ To use these workflows and actions, reference them directly from your project's
 
 <br>
 
-## ⚙️ Composite Actions
+## 💻 Composite Actions
 
 Composite Actions are a powerful feature of GitHub Actions that allow you to create reusable actions using a combination of other actions, shell commands, or both.
 
@@ -72,7 +71,7 @@ Check each action's README file for detailed instructions on how to use it.
 
 <br>
 
-## ⚙️ Workflows
+## 💻 Workflows
 
 Read more about [reusing workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
 
@@ -84,7 +83,7 @@ Automatically applies labels to pull requests based on modified paths.
 
 This workflow triages pull requests and applies labels based on the paths that are modified in the pull request. This can help to categorize your pull requests and make it easier to identify the type of changes included.
 
-To use this workflow, set up a `.github/labeler.yml` file with your configuration in your project. For more information on how to configure the labeler, see: https://github.com/actions/labeler/blob/master/README.md
+To use this workflow, set up a `.github/labeler.yml` file with your configuration in your project. For more information on how to configure the labeler, see: <https://github.com/actions/labeler/blob/master/README.md>
 
 Here is an example of how to use this workflow:
 
@@ -133,6 +132,7 @@ jobs:
 
 ...
 ```
+
 </details>
 
 Real-world examples can be found in the [`wayofdev/laravel-package-tpl`](https://github.com/wayofdev/laravel-package-tpl/blob/master/.github/workflows/apply-labels.yml) repository.
@@ -174,6 +174,7 @@ jobs:
 
 ...
 ```
+
 </details>
 
 Real-world examples can be found in the [`wayofdev/laravel-package-tpl`](https://github.com/wayofdev/laravel-package-tpl/blob/master/.github/workflows/auto-merge-release.yml) repository.
@@ -221,6 +222,7 @@ jobs:
 
 ...
 ```
+
 </details>
 
 Real-world examples can be found in the [`wayofdev/laravel-package-tpl`](https://github.com/wayofdev/laravel-package-tpl/blob/master/.github/workflows/create-arch-diagram.yml) repository.
@@ -260,6 +262,7 @@ jobs:
 
 ...
 ```
+
 </details>
 
 Real-world examples can be found in the [`wayofdev/laravel-package-tpl`](https://github.com/wayofdev/laravel-package-tpl/blob/master/.github/workflows/shellcheck.yml) repository.
@@ -300,13 +303,13 @@ You are more than welcome. Before contributing, kindly check our [contribution g
 
 ## 🧱 Useful Resources
 
-* [Composite Actions vs Reusable Workflows: what is the difference?](https://dev.to/n3wt0n/composite-actions-vs-reusable-workflows-what-is-the-difference-github-actions-11kd)
+- [Composite Actions vs Reusable Workflows: what is the difference?](https://dev.to/n3wt0n/composite-actions-vs-reusable-workflows-what-is-the-difference-github-actions-11kd)
 
-* [wayofdev/gh-actions](https://github.com/wayofdev/gh-actions) — Upstream repository for the shared GitHub Actions.
+- [wayofdev/gh-actions](https://github.com/wayofdev/gh-actions) — Upstream repository for the shared GitHub Actions.
 
-* [ergebnis/.github](https://github.com/ergebnis/.github) — Shareable actions of the [@ergebnis](https://github.com/ergebnis) organization.
+- [ergebnis/.github](https://github.com/ergebnis/.github) — Shareable actions of the [@ergebnis](https://github.com/ergebnis) organization.
 
-* [skills/reusable-workflows](https://github.com/skills/reusable-workflows) — Reusable workflow examples
+- [skills/reusable-workflows](https://github.com/skills/reusable-workflows) — Reusable workflow examples
 
 <br>
 

actions/composer/install/README.md

@@ -97,18 +97,19 @@ none
 - When `dependencies` is set to `"lowest"`, dependencies are installed in the directory specified by `working-directory` with
 
   ```bash
-  $ composer update --ansi --no-interaction --no-progress --prefer-lowest
+  composer update --ansi --no-interaction --no-progress --prefer-lowest
   ````
+
 - When `dependencies` is set to `"locked"`, dependencies are installed in the directory specified by `working-directory` with
 
   ```bash
-  $ composer install --ansi --no-interaction --no-progress
+  composer install --ansi --no-interaction --no-progress
   ```
 
 - When `dependencies` is set to `"highest"`, dependencies are installed in the directory specified by `working-directory` with
 
   ```bash
-  $ composer update --ansi --no-interaction --no-progress
+  composer update --ansi --no-interaction --no-progress
   ````
 
 <br>

actions/phive/install/README.md

@@ -85,17 +85,17 @@ none
 - When `dependencies` is set to `"lowest"`, dependencies are installed in the directory specified by `working-directory` with
 
   ```bash
-  $ composer update --ansi --no-interaction --no-progress --prefer-lowest
+  composer update --ansi --no-interaction --no-progress --prefer-lowest
   ````
 
 - ```bash
-  $ composer install --ansi --no-interaction --no-progress
+  composer install --ansi --no-interaction --no-progress
   ```
 
 - When `dependencies` is set to `"highest"`, dependencies are installed in the directory specified by `working-directory` with
 
   ```bash
-  $ composer update --ansi --no-interaction --no-progress
+  composer update --ansi --no-interaction --no-progress
   ````
 
 <br>