Always fail on Mintlify parsing errors

For some reason Mintlify CLI returns 0 even when parsing errors exist - this is likely the case when these errors appear in files that are not (yet) referenced by docs.json.

Author: fweikert

mintlify/Dockerfile

@@ -1,10 +1,44 @@
+# This Dockerfile is way more complex than it should be thanks to a bug in the
+# Mintlify CLI: It does not fail when it discovers parsing errors in .mdx
+# files that are not (yet) referenced by docs.json.
+# We work around this issue by running mint via script(1) - unlike tee(1) it
+# is able to redirect output to a file while preserving colored output in the
+# terminal. Then we check the file contents for actual parsing errors.
+# Unfortunately the newest readily available version of script is too old,
+# so we need to build our own binary (called script2) in the build stage.
+
+# Build stage
+FROM gcr.io/bazel-public/ubuntu2404 AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    wget \
+    build-essential \
+    tar \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /build
+
+# Download, extract, and build util-linux
+RUN wget -c "https://www.kernel.org/pub/linux/utils/util-linux/v2.42/util-linux-2.42.1.tar.gz" -O util-linux.tar.gz \
+    && tar -xzvf util-linux.tar.gz \
+    && cd util-linux-2.42.1 \
+    && ./configure --disable-all-programs --enable-scriptutils \
+    && make
+
 # Use the Bazel public image as the base
 FROM gcr.io/bazel-public/ubuntu2404
 
 # Install dependencies: jq and deps of nodejs
 RUN apt-get update && apt-get install -y \
     jq ca-certificates curl gnupg
 
+# Copy the compiled binary from the builder stage
+COPY --from=builder /build/util-linux-2.42.1/script /usr/bin/script2
+
+# Ensure it's executable
+RUN chmod +x /usr/bin/script2
+
 # Install nodejs as per https://github.com/nodesource/distributions/wiki/Repository-Manual-Installation#debian-systems
 RUN mkdir -p /etc/apt/keyrings && \
     curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \

mintlify/check_docs.sh

@@ -34,9 +34,14 @@ fi
 
 echo "+++ :male-detective::books: Checking documentation with Mintlify"
 
+LOG_FILE="log.txt"
 # https://www.mintlify.com/docs/installation#validate-documentation-build
 # If validation fails, we annotate the build and exit.
-if ! mint validate; then
+# "mint validate" sometimes returns 0 even though parsing errors exist
+# (this usually happens if the file is not yet referenced by docs.json).
+# That's why we use `script` to print to stdout and a file while preserving
+# colored output, then check the file for parsing errors.
+if ! script2 -eq "$LOG_FILE" -- "mint validate" || grep -q "parsing error" "$LOG_FILE"; then
   cat /usr/local/annotation.html | buildkite-agent annotate --style "error" --context "mdx_parser"
   exit 1
 fi