From 43810028b3b83af3446e7c2740b38c8a8bcd8308 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Jul 2026 01:41:11 +0000 Subject: [PATCH 1/4] Initial plan From a14b0f702e51c611c0fb9172acaa258137a51343 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Jul 2026 01:48:57 +0000 Subject: [PATCH 2/4] fix: gracefully handle missing Playwright system deps during website build When Playwright browser system dependencies are not installed, the `rehype-mermaid` plugin would throw an error and fail the entire build. This change detects Playwright availability at build time by attempting to launch a browser. If that succeeds, the existing `inline-svg` strategy is used (server-side SVG rendering). If it fails for any reason (Playwright not installed, or system browser deps missing), we fall back to the `pre-mermaid` strategy which renders Mermaid diagrams client-side and does not require Playwright. Also updates CONTRIBUTING.md to clarify the effect of not having Playwright installed (mermaid diagrams fall back to client-side rendering instead of failing the build). Fixes microsoft/typespec#5272 Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com> --- CONTRIBUTING.md | 6 ++++-- website/astro.config.mjs | 28 +++++++++++++++++++++++++++- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3e55323483..b1fb5d330d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,12 +24,14 @@ pnpm install-conflict # This will reset the lockfile to the upstream version and pnpm build ``` -- (Optional) Install [Playwright](https://playwright.dev/) browsers for UI testing +- (Optional) Install [Playwright](https://playwright.dev/) browsers for UI testing and server-side Mermaid diagram rendering in the website ```bash -npx playwright install +npx playwright install --with-deps chromium ``` +> **Note:** Without Playwright, `pnpm build` still succeeds. Mermaid diagrams in the website will fall back to client-side rendering instead of being pre-rendered as SVGs. + - Start the build in watch mode to automatically rebuild on save ```bash diff --git a/website/astro.config.mjs b/website/astro.config.mjs index b867e435c2e..a0b57343baf 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -46,6 +46,32 @@ const base = process.env.TYPESPEC_WEBSITE_BASE_PATH ?? "/"; const initJsIntegrity = computeSriHash("1ds-init.js"); +/** + * Detect whether a Playwright browser can be launched. + * Returns 'inline-svg' if Playwright is available (server-side SVG rendering), + * or 'pre-mermaid' as a fallback (client-side rendering, no Playwright needed). + * @returns {Promise<'inline-svg' | 'pre-mermaid'>} + */ +async function getMermaidStrategy() { + try { + const { chromium } = await import("playwright"); + const browser = await chromium.launch(); + await browser.close(); + return "inline-svg"; + } catch { + // eslint-disable-next-line no-console + console.warn( + "[rehype-mermaid] Playwright is not available or browser system dependencies are missing.\n" + + " Mermaid diagrams will use client-side rendering (pre-mermaid strategy).\n" + + " To enable server-side SVG rendering, install Playwright:\n" + + " npx playwright install --with-deps chromium", + ); + return "pre-mermaid"; + } +} + +const mermaidStrategy = await getMermaidStrategy(); + // https://astro.build/config export default defineConfig({ base, @@ -135,7 +161,7 @@ export default defineConfig({ // @ts-expect-error wrong type remarkPlugins: [remarkHeadingID], rehypePlugins: [ - rehypeMermaid, + [rehypeMermaid, { strategy: mermaidStrategy }], [rehypeAstroRelativeMarkdownLinks, { base, collectionBase: false, trailingSlash: "always" }], ], shikiConfig: { From 4224030946a7fcb1dfecec50339f102f3e1af52e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Jul 2026 13:33:27 +0000 Subject: [PATCH 3/4] fix: always use pre-mermaid strategy in CI environments Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com> --- website/astro.config.mjs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/astro.config.mjs b/website/astro.config.mjs index a0b57343baf..ee3135877b1 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -50,9 +50,13 @@ const initJsIntegrity = computeSriHash("1ds-init.js"); * Detect whether a Playwright browser can be launched. * Returns 'inline-svg' if Playwright is available (server-side SVG rendering), * or 'pre-mermaid' as a fallback (client-side rendering, no Playwright needed). + * Always returns 'pre-mermaid' in CI environments. * @returns {Promise<'inline-svg' | 'pre-mermaid'>} */ async function getMermaidStrategy() { + if (process.env.CI) { + return "pre-mermaid"; + } try { const { chromium } = await import("playwright"); const browser = await chromium.launch(); From 6f3bd381ad18a73887cd0eb8622f392d2ae75569 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Jul 2026 13:37:08 +0000 Subject: [PATCH 4/4] fix: always use inline-svg in CI, pre-mermaid fallback only for local dev Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com> --- website/astro.config.mjs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/astro.config.mjs b/website/astro.config.mjs index ee3135877b1..aeeeaaa4bff 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -48,14 +48,14 @@ const initJsIntegrity = computeSriHash("1ds-init.js"); /** * Detect whether a Playwright browser can be launched. - * Returns 'inline-svg' if Playwright is available (server-side SVG rendering), - * or 'pre-mermaid' as a fallback (client-side rendering, no Playwright needed). - * Always returns 'pre-mermaid' in CI environments. + * In CI environments, always returns 'inline-svg' for server-side SVG pre-rendering. + * Locally, returns 'inline-svg' if Playwright is available, or 'pre-mermaid' as a + * fallback for client-side rendering when Playwright is not installed. * @returns {Promise<'inline-svg' | 'pre-mermaid'>} */ async function getMermaidStrategy() { if (process.env.CI) { - return "pre-mermaid"; + return "inline-svg"; } try { const { chromium } = await import("playwright");