diff --git a/doc/source/general-jobs.rst b/doc/source/general-jobs.rst
index 747b1ac70..7803f82b7 100644
--- a/doc/source/general-jobs.rst
+++ b/doc/source/general-jobs.rst
@@ -3,6 +3,7 @@ General Purpose Jobs
 
 .. zuul:autojob:: dco-license
 .. zuul:autojob:: unittests
+.. zuul:autojob:: markdownlint
 .. zuul:autojob:: multinode
 .. zuul:autojob:: run-test-command
 .. zuul:autojob:: upload-git-mirror
diff --git a/doc/source/general-roles.rst b/doc/source/general-roles.rst
index a4a5ceb0d..83a8d97df 100644
--- a/doc/source/general-roles.rst
+++ b/doc/source/general-roles.rst
@@ -15,8 +15,11 @@ General Purpose Roles
 .. zuul:autorole:: emit-job-header
 .. zuul:autorole:: enable-netconsole
 .. zuul:autorole:: ensure-dstat-graph
+.. zuul:autorole:: ensure-markdownlint
+.. zuul:autorole:: fetch-markdownlint
 .. zuul:autorole:: git-prepare-nodecache
 .. zuul:autorole:: log-inventory
+.. zuul:autorole:: markdownlint
 .. zuul:autorole:: mirror-workspace-git-repos
 .. zuul:autorole:: multi-node-bridge
 .. zuul:autorole:: multi-node-firewall
diff --git a/playbooks/markdownlint/post.yaml b/playbooks/markdownlint/post.yaml
new file mode 100644
index 000000000..90b0517cb
--- /dev/null
+++ b/playbooks/markdownlint/post.yaml
@@ -0,0 +1,4 @@
+- name: Get markdownlint report
+  hosts: all
+  roles:
+    - fetch-markdownlint
diff --git a/playbooks/markdownlint/pre.yaml b/playbooks/markdownlint/pre.yaml
new file mode 100644
index 000000000..c8180f945
--- /dev/null
+++ b/playbooks/markdownlint/pre.yaml
@@ -0,0 +1,5 @@
+- name: Ensure Markdownlint is installed via NPM
+  hosts: all
+  roles:
+    - install-nodejs
+    - ensure-markdownlint
diff --git a/playbooks/markdownlint/run.yaml b/playbooks/markdownlint/run.yaml
new file mode 100644
index 000000000..d0f51f2c4
--- /dev/null
+++ b/playbooks/markdownlint/run.yaml
@@ -0,0 +1,5 @@
+- name: Run markdownlint
+  hosts: all
+  roles:
+    - revoke-sudo
+    - markdownlint
diff --git a/roles/ensure-markdownlint/README.rst b/roles/ensure-markdownlint/README.rst
new file mode 100644
index 000000000..085b698bc
--- /dev/null
+++ b/roles/ensure-markdownlint/README.rst
@@ -0,0 +1 @@
+Ensure markdownlint-cli from NPM is installed.
diff --git a/roles/ensure-markdownlint/tasks/main.yaml b/roles/ensure-markdownlint/tasks/main.yaml
new file mode 100644
index 000000000..d45cb8e41
--- /dev/null
+++ b/roles/ensure-markdownlint/tasks/main.yaml
@@ -0,0 +1,4 @@
+- name: Install markdownlint-cli
+  npm:
+    name: markdownlint-cli
+    path: ~/.markdownlint
diff --git a/roles/fetch-markdownlint/README.rst b/roles/fetch-markdownlint/README.rst
new file mode 100644
index 000000000..2f3a253f6
--- /dev/null
+++ b/roles/fetch-markdownlint/README.rst
@@ -0,0 +1,9 @@
+Collect output from a markdownlint run. Assumes you will only run one repo, and
+one node.
+
+**Role Variables**
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   The location of the main working directory of the job.
diff --git a/roles/fetch-markdownlint/defaults/main.yaml b/roles/fetch-markdownlint/defaults/main.yaml
new file mode 100644
index 000000000..9739eb171
--- /dev/null
+++ b/roles/fetch-markdownlint/defaults/main.yaml
@@ -0,0 +1 @@
+zuul_work_dir: "{{ zuul.project.src_dir }}"
diff --git a/roles/fetch-markdownlint/tasks/main.yaml b/roles/fetch-markdownlint/tasks/main.yaml
new file mode 100644
index 000000000..5ad52b1e9
--- /dev/null
+++ b/roles/fetch-markdownlint/tasks/main.yaml
@@ -0,0 +1,12 @@
+- name: Is there a markdownlint.txt
+  register: stat_mdl_txt
+  stat:
+    path: "{{ zuul_work_dir }}/markdownlint.txt"
+
+- name: Store on executor
+  when: stat_mdl_txt.stat.exists
+  synchronize:
+    mode: pull
+    src: "{{ zuul_work_dir }}/markdownlint.txt"
+    dest: "{{ zuul.executor.log_root }}/markdownlint.txt"
+    verify_host: true
diff --git a/roles/markdownlint/README.rst b/roles/markdownlint/README.rst
new file mode 100644
index 000000000..b8d86158a
--- /dev/null
+++ b/roles/markdownlint/README.rst
@@ -0,0 +1,8 @@
+Run markdownlint against all markdown files in the given project.
+
+**Role Variables**
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   Directory to search for markdown files in.
diff --git a/roles/markdownlint/defaults/main.yaml b/roles/markdownlint/defaults/main.yaml
new file mode 100644
index 000000000..9739eb171
--- /dev/null
+++ b/roles/markdownlint/defaults/main.yaml
@@ -0,0 +1 @@
+zuul_work_dir: "{{ zuul.project.src_dir }}"
diff --git a/roles/markdownlint/tasks/main.yaml b/roles/markdownlint/tasks/main.yaml
new file mode 100644
index 000000000..9f58e6bdb
--- /dev/null
+++ b/roles/markdownlint/tasks/main.yaml
@@ -0,0 +1,16 @@
+- name: find all .md files
+  find:
+    paths: "{{ zuul_work_dir }}"
+    pattern: "*.md"
+  register: markdown_find
+
+- name: Run markdownlint
+  shell: |
+    set -o pipefail
+    set -e
+    ~/.markdownlint/node_modules/.bin/markdownlint {{ item|relpath(zuul_work_dir) }} 2>&1 | tee -a markdownlint.txt
+  args:
+    chdir: "{{ zuul_work_dir }}"
+    executable: /bin/bash
+  with_items: "{{ markdown_find.files|map(attribute='path')|list }}"
+  changed_when: false
diff --git a/zuul.d/python-jobs.yaml b/zuul.d/python-jobs.yaml
index 1af163f36..6da6e8715 100644
--- a/zuul.d/python-jobs.yaml
+++ b/zuul.d/python-jobs.yaml
@@ -335,3 +335,14 @@
       - test-requirements.txt
       - tox.ini
 
+- job:
+    name: markdownlint
+    files: '^.*\.md$'
+    pre-run: playbooks/markdownlint/pre.yaml
+    run: playbooks/markdownlint/run.yaml
+    post-run: playbooks/markdownlint/post.yaml
+    description: |
+      Check any markdown for basic lint problems. Include a file named
+      `.markdownlint.json` that is configured according to
+      https://github.com/DavidAnson/markdownlint#optionsconfig
+      to control rule specifics.