diff --git a/docs/containers-policy.json.5.md b/docs/containers-policy.json.5.md
index 909d04afd0..50341b4106 100644
--- a/docs/containers-policy.json.5.md
+++ b/docs/containers-policy.json.5.md
@@ -58,7 +58,8 @@ This is expressed in JSON using the top-level syntax
 The global `default` set of policy requirements is mandatory; all of the other fields
 (`transports` itself, any specific transport, the transport-specific default, etc.) are optional.
 
-<!-- NOTE: Keep this in sync with transports/transports.go! -->
+[comment]: # (NOTE: Keep this in sync with transports/transports.go!)
+
 ## Supported transports and their scopes
 
 See containers-transports(5) for general documentation about the transports and their reference syntax.
@@ -235,7 +236,8 @@ This requirement requires an image to be signed using “simple signing” with
     "signedIdentity": identity_requirement
 }
 ```
-<!-- Later: other keyType values -->
+
+[comment]: # (Later: other keyType values)
 
 Exactly one of `keyPath`, `keyPaths` and `keyData` must be present, containing a GPG keyring of one or more public keys.  Only signatures made by these keys are accepted.
 
@@ -309,7 +311,7 @@ If the `signedIdentity` field is missing, it is treated as `matchRepoDigestOrExa
 provided by the transport.  In particular, the `dir:` and `oci:` transports can be only
 used with `exactReference` or `exactRepository`.
 
-<!-- ### `signedBaseLayer` -->
+[comment]: # (### `signedBaseLayer`)
 
 
 ### `sigstoreSigned`
diff --git a/docs/containers-registries.d.5.md b/docs/containers-registries.d.5.md
index 04434de4b6..18c0c6cdda 100644
--- a/docs/containers-registries.d.5.md
+++ b/docs/containers-registries.d.5.md
@@ -73,7 +73,7 @@ If no `docker` section can be found for the container image, and no `default-doc
 A single configuration section is selected for a container image using the process
 described above.  The configuration section is a YAML mapping, with the following keys:
 
-<!-- `sigstore` and `sigstore-staging` are deprecated and intentionally not documented here. -->
+[comment]: # (`sigstore` and `sigstore-staging` are deprecated and intentionally not documented here.)
 
 - `lookaside-staging` defines an URL of of the signature storage, used for editing it (adding or deleting signatures).
 
diff --git a/docs/containers-transports.5.md b/docs/containers-transports.5.md
index 8ec42fe87a..76b2946f61 100644
--- a/docs/containers-transports.5.md
+++ b/docs/containers-transports.5.md
@@ -16,7 +16,7 @@ they are evaluated. For example: if evaluated on a remote server, image names
 might refer to paths on that server; relative paths are relative to the current
 directory of the image consumer.
 
-<!-- atomic: is deprecated and not documented here. -->
+[comment]: # (atomic: is deprecated and not documented here.)
 
 ### **containers-storage**:[**[**storage-specifier**]**]{image-id|docker-reference[@image-id]}
 
@@ -91,7 +91,7 @@ An image using the Singularity image format at _path_.
 
 Only reading images is supported, and not all scripts can be represented in the OCI format.
 
-<!-- tarball: can only usefully be used from Go callers who call tarballReference.ConfigUpdate, and is not documented here. -->
+[comment]: # (tarball: can only usefully be used from Go callers who call tarballReference.ConfigUpdate, and is not documented here.)
 
 ## Examples