diff --git a/.github/workflows/markdownlint-problem-matcher.json b/.github/workflows/markdownlint-problem-matcher.json
new file mode 100644
index 00000000..f0741f6b
--- /dev/null
+++ b/.github/workflows/markdownlint-problem-matcher.json
@@ -0,0 +1,17 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "markdownlint",
+            "pattern": [
+                {
+                    "regexp": "^([^:]*):(\\d+):?(\\d+)?\\s([\\w-\\/]*)\\s(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "column": 3,
+                    "code": 4,
+                    "message": 5
+                }
+            ]
+        }
+    ]
+}
diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml
new file mode 100644
index 00000000..9cb00dc5
--- /dev/null
+++ b/.github/workflows/markdownlint.yml
@@ -0,0 +1,26 @@
+name: Markdownlint
+
+permissions:
+  contents: read
+
+# run even on changes without markdown changes, so that we can
+# make it in GitHub a required check for PR's
+on:
+  pull_request:
+
+jobs:
+  lint:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 16.x
+    - name: Run Markdownlint
+      run: |
+        echo "::add-matcher::.github/workflows/markdownlint-problem-matcher.json"
+        npm i -g markdownlint-cli
+        markdownlint --ignore '.dotnet/' '**/*.md'
diff --git a/.markdownlint.json b/.markdownlint.json
new file mode 100644
index 00000000..8fa75c42
--- /dev/null
+++ b/.markdownlint.json
@@ -0,0 +1,20 @@
+{
+    "default": true,
+    "ul-indent":                       false,
+    "ul-style":                        false,
+    "no-trailing-spaces":              false,
+    "line-length":                     false,
+    "blanks-around-headings":          false,
+    "no-duplicate-heading":            { "siblings_only": true },
+    "no-trailing-punctuation":         false,
+    "blanks-around-fences":            false,
+    "blanks-around-lists":             false,
+    "no-inline-html":                  { "allowed_elements": [ "summary", "details", "kbd", "br" ]},
+    "no-bare-urls":                    false,
+    "single-trailing-newline":         false,
+    "emphasis-style":                  false,
+
+    // rule settings and options are documented in https://github.com/DavidAnson/markdownlint
+    // feel free to disable more low value rules in here; get rule name from the error message.
+    // the purpose of the linter is to catch significant issues like broken links.
+}
diff --git a/.markdownlintignore b/.markdownlintignore
new file mode 100644
index 00000000..6efa1da3
--- /dev/null
+++ b/.markdownlintignore
@@ -0,0 +1,2 @@
+# This is for editors; keep .github/workflows/markdownlint.yml in sync
+.dotnet/
diff --git a/README.md b/README.md
index 54d287f9..f9743aba 100644
--- a/README.md
+++ b/README.md
@@ -30,16 +30,16 @@ dotnet restore eShop.Web.slnf
 > Remember to ensure that Docker is started
 
 * (Windows only) Run the application from Visual Studio:
-	* Open the `eShop.Web.slnf` file in Visual Studio
-	* Ensure that `eShop.AppHost.csproj` is your startup project
-	* Hit Ctrl-F5 to launch Aspire
+ - Open the `eShop.Web.slnf` file in Visual Studio
+ - Ensure that `eShop.AppHost.csproj` is your startup project
+ - Hit Ctrl-F5 to launch Aspire
 
 * Or run the application from your terminal:
 ```powershell
 dotnet run --project src/eShop.AppHost/eShop.AppHost.csproj
 ```
 then look for lines like this in the console output in order to find the URL to open the Aspire dashboard:
-```
+```sh
 Now listening on: http://localhost:18848
 ```
 
diff --git a/src/Basket.API/README.md b/src/Basket.API/README.md
deleted file mode 100644
index 98e4a1a5..00000000
--- a/src/Basket.API/README.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Containerized eShop - Basket Service
-Sample reference containerized application, cross-platform and microservices architecture.
-Powered by Microsoft
-
-
-
-
diff --git a/src/Identity.API/README.md b/src/Identity.API/README.md
deleted file mode 100644
index ffaaed53..00000000
--- a/src/Identity.API/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Containerized eShop - Identity Service
-Sample reference containerized application, cross-platform and microservices architecture.
-Powered by Microsoft
-
-## Overview
-This sample runs a microservices oriented application and a .net core Mvc application that consumes this services. You can find more information about how to set up docker in your machine in the global directory solution.
-
-## Setup
-This service is a identity provider or STS (Security Token Service) currently implemented with IdentityServer 4 wrapping ASP.NET Identity underneath.
-
-Check procedures on how to get the sample app started at the Wiki:
-https://github.com/dotnet/eShopOnContainers/wiki
-
-
diff --git a/src/Ordering.API/README.md b/src/Ordering.API/README.md
deleted file mode 100644
index f1671aa8..00000000
--- a/src/Ordering.API/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Containerized eShop - Orders Service
-Sample reference containerized application, cross-platform and microservices architecture.
-Powered by Microsoft
-
-Check procedures on how to get it started at the Wiki:
-https://github.com/dotnet/eShopOnContainers/wiki
-
-
-
-
-