UI: Improve doc_md rendering in Dag Documentation

[minyeamer]

This PR improves how doc_md content renders in the Dag Documentation dialog in the new UI.

It adds proper rendering for inline code, fenced code blocks, KaTeX math, and Mermaid diagrams.

What changed

• render inline code separately so it stays in normal sentence flow
• render fenced code blocks in a dedicated full-width container with broader syntax highlighting, line numbers, and a copy action
• add KaTeX support for math expressions and load the bundled stylesheet needed to display them
• add Mermaid support for diagram blocks with strict security settings
• add regression tests for inline code, fenced code blocks, math, and Mermaid rendering

Test plan

• install dependencies with the committed lockfile to confirm the markdown-related packages and KaTeX assets install correctly:
  cd airflow-core/src/airflow/ui && corepack pnpm install --frozen-lockfile
• run the focused React markdown tests to verify inline code, fenced code blocks, math, and Mermaid rendering:
  cd airflow-core/src/airflow/ui && corepack pnpm vitest run src/components/ReactMarkdown.test.tsx
• run eslint on the touched UI files to catch typing, import, and lint regressions in the markdown rendering changes:
  cd airflow-core/src/airflow/ui && corepack pnpm exec eslint src/components/ReactMarkdown.tsx src/components/ReactMarkdownBlocks.tsx src/utils/renderMermaid.ts src/utils/syntaxHighlighter.ts src/components/ReactMarkdown.test.tsx src/main.tsx
• build the UI bundle to confirm the new markdown packages and KaTeX styles work in a production build:
  cd airflow-core/src/airflow/ui && corepack pnpm build

Screenshots

Mode	Before	After
Light
Dark

---

Was generative AI tooling used to co-author this PR?

• Yes

Generated-by: GitHub Copilot (GPT-5.4) following the guidelines

---

• Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
• For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
• When adding dependency, check compliance with the ASF 3rd Party License Policy.
• For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

[Copilot]

Pull request overview

This PR enhances the new UI’s DAG Documentation markdown rendering so doc_md displays richer content (inline code, fenced code blocks with improved UX, KaTeX math, and Mermaid diagrams), and adds regression tests for the new behavior.

Changes:

• Refactors markdown rendering to separate inline code from fenced code blocks and introduce dedicated block renderers (code + Mermaid).
• Adds KaTeX + math plugin support and globally loads KaTeX styles.
• Switches syntax highlighting setup and adds targeted Vitest coverage for markdown rendering cases.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
airflow-core/src/airflow/ui/src/utils/syntaxHighlighter.ts	Switches exported highlighter + theme source (now hljs-based) and updates types.
airflow-core/src/airflow/ui/src/utils/renderMermaid.ts	Adds Mermaid rendering helper with strict security configuration.
airflow-core/src/airflow/ui/src/main.tsx	Imports KaTeX stylesheet globally.
airflow-core/src/airflow/ui/src/components/ReactMarkdownBlocks.tsx	Adds block-level renderers for fenced code blocks and Mermaid diagrams (copy UX, loading state, SVG injection).
airflow-core/src/airflow/ui/src/components/ReactMarkdown.tsx	Integrates remark-math/rehype-katex, new pre/code handling, Mermaid routing, and KaTeX display styling.
airflow-core/src/airflow/ui/src/components/ReactMarkdown.test.tsx	Adds regression tests for inline code, fenced blocks, math, and Mermaid rendering.
airflow-core/src/airflow/ui/package.json	Adds dependencies for KaTeX, Mermaid, and markdown math plugins.
airflow-core/src/airflow/ui/pnpm-lock.yaml	Updates lockfile for new dependencies.

Files not reviewed (1)

• airflow-core/src/airflow/ui/pnpm-lock.yaml: Language not supported

[Srabasti]

Static checks are failing. Please run prek locally in your branch to fix the errors and then commit to repo. Remember to rebase to ensure all latest commits from community are incorporated.

[choo121600]

@minyeamer A few things need addressing before review — see our Pull Request quality criteria.

• ❌ Pre-commit / static checks — Failing: CI image checks / Static checks. See docs.
• ❌ Provider tests — Failing: provider distributions tests / Compat 3.0.6:P3.10:. See docs.

No rush.

---

Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this two-stage triage process so that our maintainers' limited time is spent where it matters most: the conversation with you.

[minyeamer]

@Srabasti @choo121600

Thanks for pointing those out! I’ve resolved the failures locally and pushed the fixes:

Static Checks: Fixed the pre-commit and CI image check failures.
Provider Distributions: All failed provider tests (Compat 3.0.6) are now passing.

[choo121600]

nice feature :)
one question

[parkhojeong]

Thanks for working on this. This looks very useful, and I left a few comments.

[potiuk]

@minyeamer — This PR has new commits since the last review requesting changes from bbovenzi. Could you address the outstanding review comments and either push a fix or reply in each thread explaining why the feedback doesn't apply? When you believe the threads are resolved, please mark them as resolved and ping the reviewer (bbovenzi) — they'll either re-review or hand the PR back to the queue. Thanks!

---

Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this two-stage triage process so that our maintainers' limited time is spent where it matters most: the conversation with you.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[minyeamer]

@bbovenzi I went through your requested changes and pushed follow-up commits to address them.

The biggest change is that Mermaid now lives in a MermaidProvider under src/context, instead of being initialized from a standalone utility. That keeps theme initialization inside the React lifecycle while still lazy-loading Mermaid only when needed.

Along the way, I also incorporated related feedback from the other threads:

• reverted the syntax highlighter back to PrismLight
• reduced the tests to minimal smoke coverage
• limited math support to display math ($$...$$) and lazy-loaded KaTeX styles
• added the required license notice updates

I'm sorry for the late mention. After updating this branch from main, a few PROD image tests started failing, and I wanted to sort that out before asking for another look.

Also, thanks to @potiuk for pointing out that I should mention the reviewer once the requested changes were addressed.

I’ve resolved the threads I addressed. When you have a moment, could you please take another look and let me know if anything still needs adjustment?

[minyeamer]

@bbovenzi Thanks for the review. Addressed all three:

• useCallback: Understood that babel-plugin-react-compiler already handles memoization at build time via reactCompilerPreset(), so removed useCallback from initializeMermaid and renderDiagram, and dropped the useMemo wrapping the context value. (f328e09)
• State management: Understood that mermaid.initialize() is cheap enough to call on every renderDiagram invocation, so removed the useState / useRef / useEffect tracking chain and the separate initializeMermaid function entirely. (f328e09)
• extractTextContent: Understood that both helpers were only used in one place, so inlined the logic as an Array.isArray check with String() conversion and removed both functions. (b7cfacd)
  • Had to adjust String(codeText) from the suggested change — it triggered @typescript-eslint/no-base-to-string since ReactNode can include non-string types, so added typeof guards to ensure codeText is always a string and dropped the String() wrapper. (d436b76)

---

Drafted-by: Claude Code (claude-sonnet-4-6); reviewed by @minyeamer before posting

[pierrejeambrun]

Really nice result — the before/after screenshots look great, and lazy-importing mermaid is exactly right given its size.

One thing on structure: I think the context/mermaid/ module and the app-wide in main.tsx are more than this needs. Details inline — collapsing it to a small util would cut a good chunk of code without changing behavior.

[minyeamer]

@pierrejeambrun Addressed in ea53d86.

Mermaid initialization is now cached per theme in the provider, so mermaid.initialize() is not called on every renderDiagram and only runs again when the theme changes.

The ReactMarkdown spread order change was not intentional, so I restored the previous override behavior by placing components={components} before {...props}.

[choo121600]

From my side, most things look good now.

[bbovenzi]

This is looking much better! Thanks for dealing with all of our feedback!

I think we have just two changes left:

Echo-ing @pierrejeambrun, I will say its safe to not need the 3rd party licenses.

I also agree with Pierre about making this a util instead of a context provider. My apologies for giving bad direction previously.

[minyeamer]

@bbovenzi Thanks for the follow-up review. I addressed both of the remaining points and pushed follow-up commits:

• Removed the 3rd-party license additions in 44c6acf
• Changed Mermaid from the context provider back to a small utility in 39dc0f1

[jscheffl]

That improved markdown also including mermaid is really cool! But after merge nobody will know (except when reading the code). So can you please (1) ass a small hint to docs what is supported (proposal: (a) airflow-core/docs/core-concepts/dags.rst and (b) airflow-core/docs/tutorial/fundamentals.rst) and add an extended example also to one of the example dags (e.g. airflow-core/src/airflow/example_dags/tutorial.py)

[minyeamer]

@jscheffl Thanks, updated this in the docs and examples in 0f5935d.

I added a short note to airflow-core/docs/core-concepts/dags.rst describing the Markdown features now rendered in Dag documentation, including fenced code blocks, Mermaid fences, and KaTeX display math.

For airflow-core/docs/tutorial/fundamentals.rst, I updated the existing section that already references airflow-core/src/airflow/example_dags/tutorial.py. Instead of adding a separate tutorial example, I extended the existing print_date task's doc_md so the rendered Task documentation now demonstrates inline code, a fenced code block, KaTeX, and Mermaid while still describing the tutorial task and its downstream sleep / templated tasks.

I also added new screenshots as task_doc_md.png and dag_doc_md.png for both light and dark themes. I kept the existing task_doc.png and dag_doc.png files untouched, since they may still be referenced elsewhere.

For the Dag-level doc_md, I added example_markdown_doc.py as a small example Dag whose doc_md demonstrates the same richer Markdown rendering features at the Dag documentation level; this file can be included in the example docs as well if needed.