From 58ec202ccc3b62c66e070e86524f1456e9c82926 Mon Sep 17 00:00:00 2001
From: Alexander Wang <alex@terrastruct.com>
Date: Sat, 29 Apr 2023 20:44:09 -0700
Subject: [PATCH 1/2] add warning

---
 d2compiler/compile_test.go                       | 12 ++++++++++++
 d2parser/parse.go                                |  6 +++++-
 .../TestCompile/md_block_string_err.exp.json     | 16 ++++++++++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 testdata/d2compiler/TestCompile/md_block_string_err.exp.json

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 |"
+      }
+    ]
+  }
+}

From 2f5b0a875dc42c038d1a367629dfc9625ed2b7ee Mon Sep 17 00:00:00 2001
From: Alexander Wang <alex@terrastruct.com>
Date: Sat, 29 Apr 2023 20:55:35 -0700
Subject: [PATCH 2/2] add logseq plugin

---
 README.md                     | 1 +
 ci/release/changelogs/next.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/README.md b/README.md
index b98230348..b0f80ae2e 100644
--- a/README.md
+++ b/README.md
@@ -227,6 +227,7 @@ let us know and we'll be happy to include it here!
 - **D2 Snippets (for text editors)**: [https://github.com/Paracelsus-Rose/D2-Language-Code-Snippets](https://github.com/Paracelsus-Rose/D2-Language-Code-Snippets)
 - **Mongo to D2**: [https://github.com/novuhq/mongo-to-D2](https://github.com/novuhq/mongo-to-D2)
 - **Pandoc filter**: [https://github.com/ram02z/d2-filter](https://github.com/ram02z/d2-filter)
+- **Logseq-D2**: [https://github.com/b-yp/logseq-d2](https://github.com/b-yp/logseq-d2)
 
 ### Misc
 
diff --git a/ci/release/changelogs/next.md b/ci/release/changelogs/next.md
index efa62a77e..3320fc87a 100644
--- a/ci/release/changelogs/next.md
+++ b/ci/release/changelogs/next.md
@@ -9,6 +9,7 @@
 - ELK preserves order of objects in cycles [#1235](https://github.com/terrastruct/d2/pull/1235)
 - Improper usages of `class` and `style` get error messages [#1254](https://github.com/terrastruct/d2/pull/1254)
 - Improves scaling of object widths/heights in grid diagrams [#1263](https://github.com/terrastruct/d2/pull/1263)
+- Enhance Markdown parsing error message by appending link to docs [#1269](https://github.com/terrastruct/d2/pull/1269)
 
 #### Bugfixes ⛑️