diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 35489112f..91fac8abe 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -270,6 +270,14 @@ jobs:
           ${{env.transcripts}}
           # Fail if any transcripts cause git diffs.
           git diff --ignore-cr-at-eol --exit-code unison-src/transcripts
+      - name: docs.to-html
+        if: steps.cache-transcript-test-results.outputs.cache-hit != 'true'
+        run: |
+          ${{env.ucm}} transcript unison-src/transcripts-manual/docs.to-html.md
+          # Fail if the output or generated docs differ.
+          git diff --ignore-cr-at-eol --exit-code \
+            unison-src/transcripts-manual/docs.to-html.output.md \
+            unison-src/transcripts-manual/docs.to-html
       - name: mark transcripts as passing
         if: steps.cache-transcript-test-results.outputs.cache-hit != 'true'
         run: |
@@ -417,7 +425,7 @@ jobs:
   build-jit-binary:
     name: build jit binary
     needs: generate-jit-source
-    uses: ./.github/workflows/ci-build-jit-binary.yaml    
+    uses: ./.github/workflows/ci-build-jit-binary.yaml
 
   test-jit:
     name: test jit
diff --git a/.github/workflows/update-transcripts.yaml b/.github/workflows/update-transcripts.yaml
index 3c35e9f04..68b7ec1e9 100644
--- a/.github/workflows/update-transcripts.yaml
+++ b/.github/workflows/update-transcripts.yaml
@@ -36,6 +36,9 @@ jobs:
           stack exec unison transcript unison-src/transcripts-manual/rewrites.md
       - name: transcripts
         run: stack exec transcripts
+      - name: docs.to-html
+        run: |
+          stack exec unison transcript unison-src/transcripts-manual/docs.to-html.md
       - name: save transcript changes
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
diff --git a/scripts/check.sh b/scripts/check.sh
index 03bb6609f..1784f69c6 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -6,4 +6,5 @@ true \
   && stack exec transcripts \
   && stack exec unison transcript unison-src/transcripts-round-trip/main.md \
   && stack exec unison transcript unison-src/transcripts-manual/rewrites.md \
+  && stack exec unison transcript unison-src/transcripts-manual/docs.to-html.md \
   && stack exec cli-integration-tests
diff --git a/unison-src/transcripts/fix4402.md b/unison-src/transcripts-manual/docs.to-html.md
similarity index 56%
rename from unison-src/transcripts/fix4402.md
rename to unison-src/transcripts-manual/docs.to-html.md
index e79d243e5..528d038e4 100644
--- a/unison-src/transcripts/fix4402.md
+++ b/unison-src/transcripts-manual/docs.to-html.md
@@ -1,6 +1,6 @@
 ```ucm
-.> project.create test-4402
-test-4402/main> builtins.merge
+.> project.create test-html-docs
+test-html-docs/main> builtins.merge
 ```
 
 ```unison
@@ -15,6 +15,6 @@ some.outside = 3
 ```
 
 ```ucm
-test-4402/main> add
-test-4402/main> docs.to-html some.ns /tmp/test-4402
+test-html-docs/main> add
+test-html-docs/main> docs.to-html some.ns unison-src/transcripts-manual/docs.to-html
 ```
diff --git a/unison-src/transcripts/fix4402.output.md b/unison-src/transcripts-manual/docs.to-html.output.md
similarity index 88%
rename from unison-src/transcripts/fix4402.output.md
rename to unison-src/transcripts-manual/docs.to-html.output.md
index 858f6474c..bdfc5fa4a 100644
--- a/unison-src/transcripts/fix4402.output.md
+++ b/unison-src/transcripts-manual/docs.to-html.output.md
@@ -1,7 +1,7 @@
 ```ucm
-.> project.create test-4402
+.> project.create test-html-docs
 
-  🎉 I've created the project test-4402.
+  🎉 I've created the project test-html-docs.
 
   I'll now fetch the latest version of the base Unison
   library...
@@ -20,7 +20,7 @@
   
   🎉 🥳 Happy coding!
 
-test-4402/main> builtins.merge
+test-html-docs/main> builtins.merge
 
   Done.
 
@@ -57,7 +57,7 @@ some.outside = 3
 
 ```
 ```ucm
-test-4402/main> add
+test-html-docs/main> add
 
   ⍟ I've added these definitions:
   
@@ -70,6 +70,6 @@ test-4402/main> add
       (also named lib.base.data.Map.internal.delta)
     some.outside.doc                 : Doc
 
-test-4402/main> docs.to-html some.ns /tmp/test-4402
+test-html-docs/main> docs.to-html some.ns unison-src/transcripts-manual/docs.to-html
 
 ```
diff --git a/unison-src/transcripts-manual/docs.to-html/direct/doc.html b/unison-src/transcripts-manual/docs.to-html/direct/doc.html
new file mode 100644
index 000000000..0e9f37a54
--- /dev/null
+++ b/unison-src/transcripts-manual/docs.to-html/direct/doc.html
@@ -0,0 +1 @@
+<article class="unison-doc"><span class="span"><span class="word">A doc directly in the namespace.</span></span><div class="tooltips" style="display: none;"></div></article>
\ No newline at end of file
diff --git a/unison-src/transcripts-manual/docs.to-html/pretty/deeply/nested/doc.html b/unison-src/transcripts-manual/docs.to-html/pretty/deeply/nested/doc.html
new file mode 100644
index 000000000..1e5a75f50
--- /dev/null
+++ b/unison-src/transcripts-manual/docs.to-html/pretty/deeply/nested/doc.html
@@ -0,0 +1 @@
+<article class="unison-doc"><span class="span"><span class="word">A doc pretty deeply nested in the namespace.</span></span><div class="tooltips" style="display: none;"></div></article>
\ No newline at end of file