diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
new file mode 100644
index 0000000..de85860
--- /dev/null
+++ b/.github/workflows/markdown.yml
@@ -0,0 +1,29 @@
+---
+name: Markdown Quality Checks
+
+on:
+  pull_request:
+
+jobs:
+  run-quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - uses: tj-actions/changed-files@v44
+      id: changed-markdown-files
+      with:
+        files: '**/*.md'
+        separator: ","
+
+    - name: Lint Markdown files
+      uses: DavidAnson/markdownlint-cli2-action@v16
+      if: steps.changed-markdown-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-markdown-files.outputs.all_changed_files }}
+        config: '.markdownlint.json'
+        fix: true
+        separator: ","
+      continue-on-error: false
diff --git a/.markdownlint.json b/.markdownlint.json
new file mode 100644
index 0000000..60e52b2
--- /dev/null
+++ b/.markdownlint.json
@@ -0,0 +1,45 @@
+{
+  "code-block-style": {
+    "style": "fenced"
+  },
+  "code-fence-style": {
+    "style": "backtick"
+  },
+  "heading-style": {
+    "style": "atx"
+  },
+  "hr-style": {
+    "style": "---"
+  },
+  "line-length": {
+    "strict": false,
+    "code_blocks": false
+  },
+  "proper-names": {
+    "code_blocks": false,
+    "names": [
+      "Markdown",
+      "markdown-it",
+      "markdownlint",
+      "markdownlint-cli2"
+    ]
+  },
+  "strong-style": {
+    "style": "asterisk"
+  },
+  "table-pipe-style": {
+    "style": "leading_and_trailing"
+  },
+  "ul-style": {
+    "style": "dash"
+  },
+  "no-duplicate-header" : {
+    "allow_different_nesting": true
+  },
+  "MD033" : false,
+  "MD041": false,
+  "MD045": false,
+  "MD025": {
+    "front_matter_title": ""
+  }
+}
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 9b7c40e..f0ab58b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -4,19 +4,14 @@ repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v2.3.0
   hooks:
-  - id: check-yaml
-  - id: end-of-file-fixer
-  - id: trailing-whitespace
-#- repo: https://github.com/markdownlint/markdownlint.git
-#  rev: v0.13.0
-#  hooks:
-  #- id: markdownlint_docker
-  #name: Markdownlint Docker
-  #description: Run markdown lint on your Markdown files using the project docker image
-  #language: docker_image
-  #files: \.(md|mdown|markdown)$
-  #entry: markdownlint/markdownlint
+    - id: check-yaml
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+- repo: https://github.com/DavidAnson/markdownlint-cli2
+  rev: v0.9.2
+  hooks:
+    - id: markdownlint-cli2-rules-docker
 - repo: https://github.com/shellcheck-py/shellcheck-py
   rev: v0.10.0.1
   hooks:
-  -   id: shellcheck
+    - id: shellcheck
diff --git a/README.md b/README.md
index 2f3f0b4..2ed68dc 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ cluster to be used for development or integration tests. It is also used in
 - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
 - [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries)
 - [Git](https://git-scm.com/)
+- OPTIONAL: [pre-commit](https://pre-commit.com/)
 
 Please install the same version of `kubectl` and `kind` as Github-hosted runner.
 
@@ -37,7 +38,8 @@ Will setup container runtime on your host instance.
 
 ## Startup
 
-**note**: in 2024 July, we decoupled cluster config with kind cluster setup, so that we allow this repo to set up a existing cluster.
+> **_Note_**: in 2024 July, we decoupled cluster config with kind cluster setup,
+so that we allow this repo to set up a existing cluster.
 
 1. Modify kind [config](./kind/manifests/kind.yml) to make sure `extraMounts:` cover
    the linux header and BCC.
@@ -135,3 +137,11 @@ To run pre-commit manually
 ```bash
 pre-commit run --all-files
 ```
+
+To skip pre-commit checks, use the `--no-verify` flag when committing changes
+
+```bash
+git commit -m "test" --no-verify
+[precommit-shellcheck-mardown 89ed1adc] test
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+```