diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html
index 7f8e9742..7ae7aba7 100644
--- a/layouts/_default/_markup/render-heading.html
+++ b/layouts/_default/_markup/render-heading.html
@@ -1 +1,11 @@
+{{- /*
+
+    This is a heading render hook (https://gohugo.io/render-hooks/headings/)
+    using Docsy's heading self-links hook (https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links).
+
+    This is used when a heading is encountered in markdown content to generate
+    the HTML for that heading. A self-link anchor is added at the end of the
+    heading.
+
+*/ -}}
 {{ template "_default/_markup/td-render-heading.html" . }}
diff --git a/layouts/_default/_markup/td-heading-self-link.html b/layouts/_default/_markup/td-heading-self-link.html
index 20d95611..3d8d7df5 100644
--- a/layouts/_default/_markup/td-heading-self-link.html
+++ b/layouts/_default/_markup/td-heading-self-link.html
@@ -1,8 +1,8 @@
 {{- /*
 
-    A copy of the private "_default/_markup/_td-heading-self-link.html" template
-    in Docsy's "_default/_markup/_td-render-heading.html" partial to be able to
-    reuse it when the title has custom markup.
+    A simplified copy of the inlined "_default/_markup/_td-heading-self-link.html"
+    template in Docsy's "_default/_markup/td-render-heading.html" template to be
+    able to reuse it when the heading has custom markup.
 
     Takes a string which is the ID of the heading.