Print Buildkite annotation when .mdx parsing fails (#2525)

The annotation contains links to resources that are helpful when
debugging .mdx parsing errors.

Demo: https://buildkite.com/bazel-testing/fwe-test/builds/60

mintlify/Dockerfile

diff --git a/mintlify/Dockerfile b/mintlify/Dockerfile
index 0454afc..15e4f78 100644
--- a/mintlify/Dockerfile
+++ b/mintlify/Dockerfile
@@ -10,6 +10,8 @@
 ENV DOCS_DIR="docs"
 ENV DOCS_JSON_URL="https://raw.githubusercontent.com/bazel-contrib/bazel-docs/refs/heads/main/docs.json"
 
+COPY --chown=root:root annotation.html /usr/local/annotation.html
+
 COPY --chown=root:root check_docs.sh /usr/local/bin/check_docs.sh
 
 RUN chmod 0755 /usr/local/bin/check_docs.sh

mintlify/annotation.html

diff --git a/mintlify/annotation.html b/mintlify/annotation.html
new file mode 100644
index 0000000..97b6adb
--- /dev/null
+++ b/mintlify/annotation.html
@@ -0,0 +1,6 @@
+<b>Bazel Docs:</b> <code>.mdx</code> parsing has failed. Please see the following resources for help:
+
+<ul>
+    <li><a href='http://go/bazel-mdx#help'>go/bazel-mdx#help</a></li>
+    <li><a href='https://mdxjs.com/docs/troubleshooting-mdx/#problems-writing-mdx'>mdxjs.com troubleshooting guide</a></li>
+</ul>

mintlify/check_docs.sh

diff --git a/mintlify/check_docs.sh b/mintlify/check_docs.sh
index da10653..90b1c4e 100644
--- a/mintlify/check_docs.sh
+++ b/mintlify/check_docs.sh
@@ -7,6 +7,10 @@
 curl -sS "$DOCS_JSON_URL" -o docs.json
 
 # https://www.mintlify.com/docs/installation#validate-documentation-build
-mint validate
+# If validation fails, we annotate the build and exit.
+if ! mint validate; then
+  cat /usr/local/annotation.html | buildkite-agent annotate --style "error" --context "mdx_parser"
+  exit 1
+fi
 
 # TODO: call `mint broken-links``