diff --git a/d2compiler/compile_test.go b/d2compiler/compile_test.go
index 9bf6300e1..b82b256a1 100644
--- a/d2compiler/compile_test.go
+++ b/d2compiler/compile_test.go
@@ -598,6 +598,18 @@ x: {
 				}
 			},
 		},
+		{
+			name: "md_block_string_err",
+
+			text: `test: |md
+  # What about pipes
+
+  Will escaping \| work?
+|
+`,
+			expErr: `d2/testdata/d2compiler/TestCompile/md_block_string_err.d2:4:19: unexpected text after md block string. See https://d2lang.com/tour/text#advanced-block-strings.
+d2/testdata/d2compiler/TestCompile/md_block_string_err.d2:5:1: block string must be terminated with |`,
+		},
 		{
 			name: "underscore_edge_existing",
 
diff --git a/d2parser/parse.go b/d2parser/parse.go
index 683a0a545..1a205e959 100644
--- a/d2parser/parse.go
+++ b/d2parser/parse.go
@@ -413,7 +413,11 @@ func (p *parser) parseMap(isFileMap bool) *d2ast.Map {
 		if after != p.pos {
 			if n.Unbox() != nil {
 				if n.MapKey != nil && n.MapKey.Value.Unbox() != nil {
-					p.errorf(after, p.pos, "unexpected text after %v", n.MapKey.Value.Unbox().Type())
+					ps := ""
+					if _, ok := n.MapKey.Value.Unbox().(*d2ast.BlockString); ok {
+						ps = ". See https://d2lang.com/tour/text#advanced-block-strings."
+					}
+					p.errorf(after, p.pos, "unexpected text after %v%s", n.MapKey.Value.Unbox().Type(), ps)
 				} else {
 					p.errorf(after, p.pos, "unexpected text after %v", n.Unbox().Type())
 				}
diff --git a/testdata/d2compiler/TestCompile/md_block_string_err.exp.json b/testdata/d2compiler/TestCompile/md_block_string_err.exp.json
new file mode 100644
index 000000000..d5f3db2b7
--- /dev/null
+++ b/testdata/d2compiler/TestCompile/md_block_string_err.exp.json
@@ -0,0 +1,16 @@
+{
+  "graph": null,
+  "err": {
+    "ioerr": null,
+    "errs": [
+      {
+        "range": "d2/testdata/d2compiler/TestCompile/md_block_string_err.d2,3:18:50-3:24:56",
+        "errmsg": "d2/testdata/d2compiler/TestCompile/md_block_string_err.d2:4:19: unexpected text after md block string. See https://d2lang.com/tour/text#advanced-block-strings."
+      },
+      {
+        "range": "d2/testdata/d2compiler/TestCompile/md_block_string_err.d2,4:0:57-5:0:59",
+        "errmsg": "d2/testdata/d2compiler/TestCompile/md_block_string_err.d2:5:1: block string must be terminated with |"
+      }
+    ]
+  }
+}