UI: Improve doc_md rendering in Dag Documentation

airflow-core/docs/core-concepts/dags.rst

@@ -674,6 +674,7 @@ doc_rst     reStructuredText
 ==========  ================
 
 Please note that for Dags and TaskGroups, ``doc_md`` is the only attribute interpreted. It can contain a string or the reference to a markdown file. Markdown files are recognized by str ending in ``.md``.
+Dag documentation is rendered as Markdown, so fenced code blocks, tables, and other common Markdown constructs are supported. Mermaid diagrams are rendered from fenced code blocks whose language is ``mermaid``, and display math blocks delimited with ``$$`` are rendered with KaTeX.
 If a relative path is supplied it will be loaded from the path relative to which the Airflow Scheduler or Dag parser was started. If the markdown file does not exist, the passed filename will be used as text, no exception will be displayed. Note that the markdown file is loaded during Dag parsing, changes to the markdown content take one Dag parsing cycle to have changes be displayed.
 
 This is especially useful if your tasks are built dynamically from configuration files, as it allows you to expose the configuration that led to the related tasks in Airflow:

airflow-core/docs/tutorial/fundamentals.rst

@@ -153,9 +153,14 @@ For more information on the variables and macros that can be referenced in templ
 
 Adding Dag and Tasks documentation
 ----------------------------------
-You can add documentation to your Dag or individual tasks. While Dag documentation currently supports markdown, task
-documentation can be in plain text, markdown reStructuredText, JSON, or YAML. It's a good practice to include
-documentation at the start of your Dag file.
+You can add documentation to your Dag or individual tasks. Dag documentation is rendered as Markdown in the UI.
+Task documentation can be in plain text, markdown, reStructuredText, JSON, or YAML. When you use ``doc_md`` for
+task documentation, Airflow renders common Markdown features such as inline code, fenced code blocks, Mermaid diagrams
+in ``mermaid`` fences, and display math blocks delimited with ``$$`` that render with KaTeX.
+
+In the tutorial Dag, the ``print_date`` task uses ``doc_md`` to explain the bash command it runs, describe the
+downstream ``sleep`` and ``templated`` tasks, and show the Markdown features available in the Task Instance Details
+page. It's a good practice to keep this documentation close to the task it describes.
 
 .. exampleinclude:: /../src/airflow/example_dags/tutorial.py
     :language: python
@@ -165,11 +170,7 @@ documentation at the start of your Dag file.
 
 |
 
-.. image:: ../img/ui-light/task_doc.png
-
-|
-
-.. image:: ../img/ui-light/dag_doc.png
+.. image:: ../img/ui-light/task_doc_md.png
 
 Setting up Dependencies
 -----------------------

airflow-core/src/airflow/example_dags/example_markdown_doc.py

@@ -0,0 +1,78 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""
+# Markdown Rendering Demo
+
+Dag documentation is rendered from `doc_md` in the Airflow UI.
+
+## Features
+
+- Inline code such as `task_id="extract"`
+- Fenced code blocks with syntax highlighting
+- Display math blocks delimited by `$$`
+- Mermaid diagrams
+- Markdown tables
+
+### Code
+
+```python
+extract >> transform >> load
+```
+
+### Math
+
+$$
+y = \\beta_0 + \\beta_1 x_1 + \\beta_2 x_2 + \\epsilon
+$$
+
+### Mermaid
+
+```mermaid
+flowchart LR
+    A[extract] --> B[transform]
+    B --> C[load]
+```
+
+### Table
+
+| Task | Purpose |
+| --- | --- |
+| `extract` | Read the source data |
+| `transform` | Normalize the records |
+| `load` | Publish the result |
+"""
+
+from __future__ import annotations
+
+import pendulum
+
+from airflow.providers.standard.operators.empty import EmptyOperator
+from airflow.sdk import DAG
+
+with DAG(
+    dag_id="example_markdown_doc",
+    schedule="@once",
+    start_date=pendulum.datetime(2021, 1, 1, tz="UTC"),
+    catchup=False,
+    tags=["example"],
+    doc_md=__doc__,
+) as dag:
+    extract = EmptyOperator(task_id="extract")
+    transform = EmptyOperator(task_id="transform")
+    load = EmptyOperator(task_id="load")
+
+    extract >> transform >> load

airflow-core/src/airflow/example_dags/tutorial.py

@@ -87,16 +87,35 @@
     # [START documentation]
     t1.doc_md = textwrap.dedent(
         """\
-    #### Task Documentation
-    You can document your task using the attributes `doc_md` (markdown),
-    `doc` (plain text), `doc_rst`, `doc_json`, `doc_yaml` which gets
-    rendered in the UI's Task Instance Details page.
-    ![img](https://imgs.xkcd.com/comics/fixing_problems.png)
-    **Image Credit:** Randall Munroe, [XKCD](https://xkcd.com/license.html)
+    #### Print the current date
+
+    This task runs `date` by using the `bash_command` argument on `BashOperator`.
+    In the Task Instance Details page, Airflow renders this documentation from
+    the task's `doc_md` field. After this task succeeds, Airflow can run both
+    downstream tasks: `sleep` and `templated`.
+
+    ```bash
+    date
+    ```
+
+    Display math is rendered with KaTeX. This tutorial starts one task and then
+    branches into two downstream tasks:
+
+    $$
+    1\\ \\text{upstream task} + 2\\ \\text{downstream tasks} = 3\\ \\text{tasks}
+    $$
+
+    The same dependency is shown as a Mermaid diagram:
+
+    ```mermaid
+    graph LR
+        print_date[print_date] --> sleep[sleep]
+        print_date --> templated[templated]
+    ```
     """
     )
 
-    dag.doc_md = __doc__  # providing that you have a docstring at the beginning of the DAG; OR
+    dag.doc_md = __doc__  # providing that you have a docstring at the beginning of the Dag; OR
     dag.doc_md = """
     This is a documentation placed anywhere
     """  # otherwise, type it like this

airflow-core/src/airflow/ui/package.json

@@ -50,6 +50,8 @@
     "i18next": "^25.8.16",
     "i18next-browser-languagedetector": "^8.2.1",
     "i18next-http-backend": "^3.0.5",
+    "katex": "^0.16.45",
+    "mermaid": "^11.14.0",
     "monaco-editor": "^0.52.2",
     "next-themes": "^0.4.6",
     "react": "^19.2.6",
@@ -64,7 +66,9 @@
     "react-resizable-panels": "^3.0.6",
     "react-router-dom": "^7.13.1",
     "react-syntax-highlighter": "^15.6.1",
+    "rehype-katex": "^7.0.1",
     "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
     "use-debounce": "^10.1.0",
     "usehooks-ts": "^3.1.1",
     "yaml": "^2.8.2",