diff --git a/dbuild/docs.py b/dbuild/docs.py
index 2c02180..d6016c4 100644
--- a/dbuild/docs.py
+++ b/dbuild/docs.py
@@ -315,6 +315,11 @@ def _site_placeholders(text: str, env_file: bool = False) -> str:
     text = re.sub(r"(?m)(\bPGID=)1000\b", r"\g<1>@PGID@", text)
     if env_file:
         text = re.sub(r"(?m)^#?\s*TZ=\S*$", "TZ=@TZ@", text)
+    else:
+        # A YAML value can't start with @: the highlighter splits it, and the
+        # site's settings panel never finds the placeholder. Quoted, it's one
+        # string (the README template quotes its volume lines for this).
+        text = re.sub(r"""(?m)^(\s*(?:-\s+|[\w.-]+:\s+))(@[A-Z_]+@[^\s#"']*)(?=[ \t]*(?:#.*)?$)""", r'\1"\2"', text)
     return text
 
 
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 811806e..761352c 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -468,7 +468,7 @@ def test_repo_compose_and_env_get_site_placeholders(self):
         compose = "      - PUID=1000\n      - PGID=1000\n    volumes:\n      - /containers/app/config:/config\n"
         assert _site_placeholders(compose) == (
             "      - PUID=@PUID@\n      - PGID=@PGID@\n    volumes:\n"
-            "      - @CONTAINER_CONFIG_ROOT@/app/config:/config\n")
+            '      - "@CONTAINER_CONFIG_ROOT@/app/config:/config"\n')
         env = "CONFIG_LOCATION=/containers/app\n# TZ=UTC\n"
         assert _site_placeholders(env, env_file=True) == (
             "CONFIG_LOCATION=@CONTAINER_CONFIG_ROOT@/app\nTZ=@TZ@\n")
@@ -479,7 +479,12 @@ def test_the_whole_fleet_root_becomes_the_placeholder(self):
         # swapped, so the page showed /path/to@CONTAINER_CONFIG_ROOT@/<app>.
         from dbuild.docs import _site_placeholders
         compose = "      - /path/to/containers/uptime-kuma:/config\n"
-        assert _site_placeholders(compose) == "      - @CONTAINER_CONFIG_ROOT@/uptime-kuma:/config\n"
+        # quoted: a YAML value starting with @ is split by the highlighter
+        assert _site_placeholders(compose) == '      - "@CONTAINER_CONFIG_ROOT@/uptime-kuma:/config"\n'
+        long_form = "        source: /path/to/containers/app/db\n"
+        assert _site_placeholders(long_form) == '        source: "@CONTAINER_CONFIG_ROOT@/app/db"\n'
+        commented = "      - /path/to/containers/x:/data  # required\n"
+        assert _site_placeholders(commented) == '      - "@CONTAINER_CONFIG_ROOT@/x:/data"  # required\n'
         env = "DB_LOCATION=/path/to/containers/app/db\n"
         assert _site_placeholders(env, env_file=True) == "DB_LOCATION=@CONTAINER_CONFIG_ROOT@/app/db\n"
         assert _site_placeholders("      - /srv/containers/x:/x\n") == "      - /srv/containers/x:/x\n", "only at a path's start"