diff --git a/docs/_klipper3d/README b/docs/_klipper3d/README
new file mode 100644
index 00000000..3f291c88
--- /dev/null
+++ b/docs/_klipper3d/README
@@ -0,0 +1,6 @@
+This directory defines the https://www.klipper3d.org/ website. The
+site is hosted using "github pages". The
+.github/workflows/klipper3d-deploy.yaml tool uses mkdocs (
+https://www.mkdocs.org/ ) to automatically convert the markdown files
+in the docs/ directory to html. In addition to the files in this
+directory, the docs/CNAME file also controls the website generation.
diff --git a/docs/_klipper3d/css/extra.css b/docs/_klipper3d/css/extra.css
index a1dc2133..ea57721b 100644
--- a/docs/_klipper3d/css/extra.css
+++ b/docs/_klipper3d/css/extra.css
@@ -1,3 +1,4 @@
+/* Customization of mkdocs generated site */
 [data-md-color-scheme="slate"] {
     --md-primary-fg-color: hsla(var(--md-hue),15%,12%,1);
     --md-default-bg-color: hsla(var(--md-hue),17%,17%,1);
diff --git a/docs/_klipper3d/mkdocs-requirements.txt b/docs/_klipper3d/mkdocs-requirements.txt
index 6afd2723..7bd40f79 100644
--- a/docs/_klipper3d/mkdocs-requirements.txt
+++ b/docs/_klipper3d/mkdocs-requirements.txt
@@ -1,3 +1,4 @@
+# Python virtualenv module requirements for mkdocs
 mkdocs==1.2.2
 mkdocs-material==7.2.0
 mkdocs-section-index==0.3.1
diff --git a/docs/_klipper3d/mkdocs_hooks.py b/docs/_klipper3d/mkdocs_hooks.py
index 8815c776..f8e88839 100644
--- a/docs/_klipper3d/mkdocs_hooks.py
+++ b/docs/_klipper3d/mkdocs_hooks.py
@@ -1,3 +1,4 @@
+# Tool to customize conversion of markdown files during mkdocs site generation
 import re
 import logging