diff --git a/Makefile b/Makefile
index b05a62e9ea..ee82b8292f 100644
--- a/Makefile
+++ b/Makefile
@@ -86,7 +86,7 @@ push-all: image.amd64 image.arm64
 clean:
 	rm -rf _output
 
-verify: verify-gofmt verify-vendor lint lint-chart verify-spelling
+verify: verify-gofmt verify-vendor lint lint-chart verify-spelling verify-toc
 
 verify-spelling:
 	./hack/verify-spelling.sh
@@ -97,6 +97,9 @@ verify-gofmt:
 verify-vendor:
 	./hack/verify-vendor.sh
 
+verify-toc:
+	./hack/verify-toc.sh
+
 test-unit:
 	./test/run-unit-tests.sh
 
@@ -107,6 +110,7 @@ gen:
 	./hack/update-generated-conversions.sh
 	./hack/update-generated-deep-copies.sh
 	./hack/update-generated-defaulters.sh
+	./hack/update-toc.sh
 
 lint:
 ifndef HAS_GOLANGCI
diff --git a/README.md b/README.md
index ecd07a3039..7b89310abb 100644
--- a/README.md
+++ b/README.md
@@ -22,35 +22,35 @@ Descheduler, based on its policy, finds pods that can be moved and evicts them.
 note, in current implementation, descheduler does not schedule replacement of evicted pods
 but relies on the default scheduler for that.
 
-Table of Contents
-=================
-
-  * [Quick Start](#quick-start)
-     * [Run As A Job](#run-as-a-job)
-     * [Run As A CronJob](#run-as-a-cronjob)
-     * [Install Using Helm](#install-using-helm)
-     * [Install Using Kustomize](#install-using-kustomize)
-  * [User Guide](#user-guide)
-  * [Policy and Strategies](#policy-and-strategies)
-     * [RemoveDuplicates](#removeduplicates)
-     * [LowNodeUtilization](#lownodeutilization)
-     * [RemovePodsViolatingInterPodAntiAffinity](#removepodsviolatinginterpodantiaffinity)
-     * [RemovePodsViolatingNodeAffinity](#removepodsviolatingnodeaffinity)
-     * [RemovePodsViolatingNodeTaints](#removepodsviolatingnodetaints)
-     * [RemovePodsViolatingTopologySpreadConstraint](#removepodsviolatingtopologyspreadconstraint)
-     * [RemovePodsHavingTooManyRestarts](#removepodshavingtoomanyrestarts)
-     * [PodLifeTime](#podlifetime)
-  * [Filter Pods](#filter-pods)
-     * [Namespace filtering](#namespace-filtering)
-     * [Priority filtering](#priority-filtering)
-     * [Label filtering](#label-filtering)
-  * [Pod Evictions](#pod-evictions)
-     * [Pod Disruption Budget (PDB)](#pod-disruption-budget-pdb)
-  * [Compatibility Matrix](#compatibility-matrix)
-  * [Getting Involved and Contributing](#getting-involved-and-contributing)
-     * [Communicating With Contributors](#communicating-with-contributors)
-  * [Roadmap](#roadmap)
-     * [Code of conduct](#code-of-conduct)
+<!--ts-->
+   * [Descheduler for Kubernetes](#descheduler-for-kubernetes)
+      * [Quick Start](#quick-start)
+         * [Run As A Job](#run-as-a-job)
+         * [Run As A CronJob](#run-as-a-cronjob)
+         * [Install Using Helm](#install-using-helm)
+         * [Install Using Kustomize](#install-using-kustomize)
+      * [User Guide](#user-guide)
+      * [Policy and Strategies](#policy-and-strategies)
+         * [RemoveDuplicates](#removeduplicates)
+         * [LowNodeUtilization](#lownodeutilization)
+         * [RemovePodsViolatingInterPodAntiAffinity](#removepodsviolatinginterpodantiaffinity)
+         * [RemovePodsViolatingNodeAffinity](#removepodsviolatingnodeaffinity)
+         * [RemovePodsViolatingNodeTaints](#removepodsviolatingnodetaints)
+         * [RemovePodsViolatingTopologySpreadConstraint](#removepodsviolatingtopologyspreadconstraint)
+         * [RemovePodsHavingTooManyRestarts](#removepodshavingtoomanyrestarts)
+         * [PodLifeTime](#podlifetime)
+      * [Filter Pods](#filter-pods)
+         * [Namespace filtering](#namespace-filtering)
+         * [Priority filtering](#priority-filtering)
+         * [Label filtering](#label-filtering)
+      * [Pod Evictions](#pod-evictions)
+         * [Pod Disruption Budget (PDB)](#pod-disruption-budget-pdb)
+      * [Compatibility Matrix](#compatibility-matrix)
+      * [Getting Involved and Contributing](#getting-involved-and-contributing)
+         * [Communicating With Contributors](#communicating-with-contributors)
+      * [Roadmap](#roadmap)
+         * [Code of conduct](#code-of-conduct)
+<!--te-->
 
 ## Quick Start
 
diff --git a/hack/update-toc.sh b/hack/update-toc.sh
new file mode 100755
index 0000000000..596d7acd6c
--- /dev/null
+++ b/hack/update-toc.sh
@@ -0,0 +1,8 @@
+#!/bin/bash
+source "$(dirname "${BASH_SOURCE}")/lib/init.sh"
+
+# forked from github.com/ekalinin/github-markdown-toc/gh-md-toc
+wget -O ${OS_OUTPUT_BINPATH}/gh-md-toc https://raw.githubusercontent.com/damemi/github-markdown-toc/hide-footer/gh-md-toc
+chmod a+x ${OS_OUTPUT_BINPATH}/gh-md-toc
+
+${OS_OUTPUT_BINPATH}/gh-md-toc --insert --no-backup --hide-footer README.md
diff --git a/hack/verify-toc.sh b/hack/verify-toc.sh
new file mode 100755
index 0000000000..c014af746a
--- /dev/null
+++ b/hack/verify-toc.sh
@@ -0,0 +1,59 @@
+#!/bin/bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+source "$(dirname "${BASH_SOURCE}")/lib/init.sh"
+
+DESCHEDULER_ROOT=$(dirname "${BASH_SOURCE}")/..
+
+mkdir -p "${DESCHEDULER_ROOT}/_tmp"
+_tmpdir="$(mktemp -d "${DESCHEDULER_ROOT}/_tmp/kube-vendor.XXXXXX")"
+
+if [[ -z ${KEEP_TMP:-} ]]; then
+    KEEP_TMP=false
+fi
+
+function cleanup {
+  # make go module dirs writeable
+  chmod -R +w "${_tmpdir}"
+  if [ "${KEEP_TMP}" == "true" ]; then
+    echo "Leaving ${_tmpdir} for you to examine or copy. Please delete it manually when finished. (rm -rf ${_tmpdir})"
+  else
+    echo "Removing ${_tmpdir}"
+    rm -rf "${_tmpdir}"
+  fi
+}
+trap "cleanup" EXIT
+
+_deschedulertmp="${_tmpdir}"
+mkdir -p "${_deschedulertmp}"
+
+git archive --format=tar --prefix=descheduler/ "$(git write-tree)" | (cd "${_deschedulertmp}" && tar xf -)
+_deschedulertmp="${_deschedulertmp}/descheduler"
+
+cp -r _output "${_deschedulertmp}"
+
+pushd "${_deschedulertmp}" > /dev/null 2>&1
+hack/update-toc.sh
+popd > /dev/null 2>&1
+
+ret=0
+
+pushd "${DESCHEDULER_ROOT}" > /dev/null 2>&1
+if ! _out="$(diff README.md "${_deschedulertmp}/README.md")"; then
+    echo "Generated table of contents differs:" >&2
+    echo "${_out}" >&2
+    echo "TOC verify failed." >&2
+    echo "${_out}" > vendordiff.patch
+    echo "If you're seeing this locally, run the below command to fix your table of contents:" >&2
+    echo "hack/update-toc.sh" >&2
+fi
+popd > /dev/null 2>&1
+
+if [[ ${ret} -gt 0 ]]; then
+  exit ${ret}
+fi
+
+echo "Table of contents verified."