diff --git a/docs/test_doc_forms.py b/docs/test_doc_forms.py
index 36203f12..9025163c 100644
--- a/docs/test_doc_forms.py
+++ b/docs/test_doc_forms.py
@@ -17,6 +17,8 @@
 def test_forms():
     # language=rst
     """
+    .. _forms:
+
     Forms
     =====
 
diff --git a/docs/test_doc_pages.py b/docs/test_doc_pages.py
index 47270b0b..5947e8f1 100644
--- a/docs/test_doc_pages.py
+++ b/docs/test_doc_pages.py
@@ -16,13 +16,17 @@
 def test_pages():
     # language=rst
     """
+    .. _pages:
+
     Pages
     =====
 
-    iommi pages are used to compose parts of a page into a full page.
+    iommi pages are used to compose parts of a page into a full page. A "part" can be any iommi component (like :ref:`Table <tables>`, :ref:`Form <forms>`, :doc:`Fragment`), or a plain Python string, or a Django `Template <https://docs.djangoproject.com/en/5.1/topics/templates/>`_.
+
+    The `html`_ builder function is used to create simple :doc:`Fragment`s for div, h1, span, etc.
 
     """
-    
+
 
 def test_example():
     # language=rst
@@ -103,6 +107,9 @@ class MyPage(Page):
 
 # language=rst
 """
+
+.. _html:
+
 html
 ----
 
diff --git a/docs/test_doc_tables.py b/docs/test_doc_tables.py
index dac72b83..34c0f518 100644
--- a/docs/test_doc_tables.py
+++ b/docs/test_doc_tables.py
@@ -19,6 +19,9 @@ def fill_dummy_data(): pass
 def test_tables(really_big_discography):
     # language=rst
     """
+
+    .. _tables:
+
     Tables
     ======