You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by gi...@apache.org on 2026/09/18 20:31:36 UTC

(datafusion-comet) branch gh-readonly-queue/main/pr-6021-bae7f162be542e9eb3eb41e22422b1c0ac611156 created (now 5705a58ac2)

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a change to branch gh-readonly-queue/main/pr-6021-bae7f162be542e9eb3eb41e22422b1c0ac611156
in repository https://gitbox.apache.org/repos/asf/datafusion-comet.git


      at 5705a58ac2 docs: pre-render mermaid diagrams to SVG at build time (#6021)

This branch includes the following new commits:

     new 5705a58ac2 docs: pre-render mermaid diagrams to SVG at build time (#6021)

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org


(datafusion-comet) 01/01: docs: pre-render mermaid diagrams to SVG at build time (#6021)

Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-6021-bae7f162be542e9eb3eb41e22422b1c0ac611156
in repository https://gitbox.apache.org/repos/asf/datafusion-comet.git

commit 5705a58ac2ef7e6b2674c87f3b495f789ebfcc8d
Author: Andy Grove <ag...@apache.org>
AuthorDate: Fri Sep 18 19:54:29 2026 +0000

    docs: pre-render mermaid diagrams to SVG at build time (#6021)
    
    * docs: pre-render mermaid diagrams to SVG at build time
    
    The ASF serves *.apache.org with a Content-Security-Policy whose script-src
    allows only 'self' plus a few apache.org hosts. sphinxcontrib-mermaid defaults
    to drawing diagrams in the reader's browser, which emits a module import from
    cdn.jsdelivr.net, so the browser blocks it and every diagram on the published
    site is left as raw text.
    
    Draw the diagrams with mermaid-cli at build time instead. The resulting SVG is
    served from 'self' and needs no script, so the policy does not apply.
    apache/arrow sets the same option for the same reason.
    
    Diagrams stay authored as ```mermaid fences, so they keep rendering on
    github.com, and are drawn on a transparent background so one image suits both
    the light and dark site themes.
    
    * docs: apply prettier formatting to the docs README
    
    The Preflight job runs `prettier --check "**/*.md"`, which rejected the
    quadruple-backtick inline code span added in the previous commit. Prettier
    normalises it to a single-backtick span, which renders identically.
---
 .github/workflows/docs.yaml | 11 +++++++++++
 docs/README.md              |  4 ++++
 docs/requirements.txt       |  6 +++++-
 docs/source/conf.py         | 20 +++++++++++++++++---
 4 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 645b73b374..645f75e58d 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -49,6 +49,17 @@ jobs:
           java-version: '17'
           cache: 'maven'
 
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+
+      - name: Install mermaid-cli
+        # Draws the ```mermaid fences into SVG at build time. Without mmdc on PATH the build
+        # still succeeds but silently drops every diagram, so it is installed unconditionally.
+        # See mermaid_output_format in docs/source/conf.py for why the browser cannot draw them.
+        run: npm install -g @mermaid-js/mermaid-cli@11.17.0
+
       - name: Install dependencies
         run: |
           set -x
diff --git a/docs/README.md b/docs/README.md
index 031037b308..cc5e5ae1f2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -29,6 +29,10 @@ inside a Python virtualenv.
 
 - Python
 - `pip install -r requirements.txt`
+- Node, and `npm install -g @mermaid-js/mermaid-cli` for the `mmdc` command
+
+`mmdc` draws the ` ```mermaid ` fences into SVG when the docs are built. Without it on
+`PATH` the build still succeeds, but logs a warning and leaves those diagrams out of the pages.
 
 ## Build & Preview
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 10eb4f693d..ac9ccc4cbf 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -20,6 +20,10 @@ sphinx>=7.0,<8.0
 sphinx-reredirects
 pydata-sphinx-theme>=0.16.1,<0.17.0
 myst-parser>=2.0,<4.0
-sphinxcontrib-mermaid>=1.0,<3.0
+# 2.1 is the first release that skips the client-side mermaid.js machinery when
+# mermaid_output_format is not 'raw'. On older versions the diagrams still render as
+# build-time SVG, but every page carrying one also gets a dead cdn.jsdelivr.net script
+# tag that the ASF Content-Security-Policy blocks. See docs/source/conf.py.
+sphinxcontrib-mermaid>=2.1,<3.0
 maturin
 jinja2
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ba325734e0..c1c85ea011 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -53,9 +53,8 @@ extensions = [
     'sphinx.ext.napoleon',
     'myst_parser',
     'sphinx_reredirects',
-    # Renders the ```mermaid fences in the contributor guide. The diagrams are drawn in
-    # the browser by mermaid.js, which sphinxcontrib-mermaid loads from cdn.jsdelivr.net
-    # at the version pinned by its `mermaid_version` default.
+    # Renders the ```mermaid fences in the contributor guide. See mermaid_output_format
+    # below: the diagrams are drawn at build time, not in the reader's browser.
     'sphinxcontrib.mermaid',
 ]
 
@@ -69,6 +68,21 @@ source_suffix = {
 # understands that fence natively.
 myst_fence_as_directive = ['mermaid']
 
+# Draw the diagrams at build time with mermaid-cli (mmdc) instead of shipping mermaid.js to
+# the browser. The default 'raw' format emits `import mermaid from "https://cdn.jsdelivr.net/..."`,
+# and the ASF serves *.apache.org with a Content-Security-Policy whose script-src allows only
+# 'self' plus a few apache.org hosts, so that import is blocked and no diagram ever renders on
+# the published site. Pre-rendered SVG is served from 'self' and needs no script at all.
+# apache/arrow sets this for the same reason.
+#
+# This makes mmdc a build dependency: `npm install -g @mermaid-js/mermaid-cli`. Without it the
+# build still succeeds but logs a warning and drops the diagrams. See docs/README.md.
+mermaid_output_format = 'svg'
+
+# Render on a transparent background so one SVG suits both the light and dark site themes;
+# mmdc otherwise bakes in a white background.
+mermaid_params = ['-b', 'transparent']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org