From 62a91258cd64c5b553c1a577556cac0cb695c028 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Thu, 1 Jan 2026 12:46:07 +0000
Subject: [PATCH 01/15] fix(mdx-loader): propagate class names to admonitions

closes #11641
---
 .../admonitions/__tests__/__fixtures__/attributes.md      | 5 +++++
 .../__tests__/__snapshots__/index.test.ts.snap            | 5 +++++
 .../src/remark/admonitions/__tests__/index.test.ts        | 5 +++++
 .../docusaurus-mdx-loader/src/remark/admonitions/index.ts | 1 +
 website/_dogfooding/_docs tests/tests/admonitions.mdx     | 8 ++++++++
 website/_dogfooding/dogfooding.css                        | 4 ++++
 6 files changed, 28 insertions(+)
 create mode 100644 packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md

diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
new file mode 100644
index 000000000000..05c2fa64c273
--- /dev/null
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
@@ -0,0 +1,5 @@
+Admonitions with attributes
+
+:::info[Info Title]{.bold}
+An info admonition with a className attribute.
+:::
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
index c19b192babb0..4c50e27149fd 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
@@ -11,6 +11,11 @@ exports[`admonitions remark plugin add custom keyword 1`] = `
 <p>++++</p>"
 `;
 
+exports[`admonitions remark plugin attributes 1`] = `
+"<p>Admonitions with attributes</p>
+<admonition title="Info Title" class="bold" type="info"><p>An info admonition with a className attribute.</p></admonition>"
+`;
+
 exports[`admonitions remark plugin base 1`] = `
 "<p>The blog feature enables you to deploy in no time a full-featured blog.</p>
 <admonition title="Sample Title" type="info"><p>Check the <a href="./api/plugins/plugin-content-blog.md">Blog Plugin API Reference documentation</a> for an exhaustive list of options.</p></admonition>
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/index.test.ts b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/index.test.ts
index 7784850e44e1..7629d8679401 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/index.test.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/index.test.ts
@@ -97,4 +97,9 @@ describe('admonitions remark plugin', () => {
     const result = await processFixture('nesting');
     expect(result).toMatchSnapshot();
   });
+
+  it('attributes', async () => {
+    const result = await processFixture('attributes');
+    await expect(result).toMatchSnapshot();
+  });
 });
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts b/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
index d87df3bb54a5..10cfa20b210b 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
@@ -107,6 +107,7 @@ const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
           hName: 'admonition',
           hProperties: {
             ...(textOnlyTitle && {title: textOnlyTitle}),
+            ...(node.attributes?.class && {className: node.attributes.class}),
             type: node.name,
           },
         };
diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index e9f7d858aae2..dd1c9b48948f 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -54,6 +54,14 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 </Admonition>
 ```
 
+## Adminitions with Classnames
+
+:::info{.shadow}
+
+The class `shadow` was added by writing `:::info{.shadow}`.
+
+:::
+
 ## Indented admonitions
 
 See admonition title v2 compat syntax bug: https://github.com/facebook/docusaurus/issues/9507
diff --git a/website/_dogfooding/dogfooding.css b/website/_dogfooding/dogfooding.css
index 54376d3d546c..bbf8c128591d 100644
--- a/website/_dogfooding/dogfooding.css
+++ b/website/_dogfooding/dogfooding.css
@@ -25,6 +25,10 @@ html {
         border-bottom: solid thin cyan;
       }
 
+      .shadow {
+        box-shadow: 10px 10px 10px red;
+      }
+
       .dogfood_sidebar_class_name_test {
         &.theme-doc-sidebar-item-link > a {
           color: cyan;

From 68844e082e0927c4a9fed4963bdd9278037aae8d Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Thu, 1 Jan 2026 13:04:47 +0000
Subject: [PATCH 02/15] fix typo

---
 website/_dogfooding/_docs tests/tests/admonitions.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index dd1c9b48948f..9bcf8e754a46 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -54,7 +54,7 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 </Admonition>
 ```
 
-## Adminitions with Classnames
+## Admonitions with classes
 
 :::info{.shadow}
 

From 8c74e0f73211ed4c4ca694529e1501794240656f Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Fri, 2 Jan 2026 19:03:29 +0000
Subject: [PATCH 03/15] pass all directive attributes to the admonition

---
 .../__tests__/__fixtures__/attributes.md         | 16 ++++++++++++++++
 .../__tests__/__snapshots__/index.test.ts.snap   |  6 +++++-
 .../src/remark/admonitions/index.ts              | 11 ++++++++++-
 3 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
index 05c2fa64c273..ccf3c3d93422 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
@@ -3,3 +3,19 @@ Admonitions with attributes
 :::info[Info Title]{.bold}
 An info admonition with a className attribute.
 :::
+
+:::info{.bold .italic}
+An info admonition with multiple className attributes.
+:::
+
+:::info{#custom-id}
+An info admonition with a custom id attribute.
+:::
+
+:::info{#custom-id .bold}
+An info admonition with both id and className attributes.
+:::
+
+:::info{.c1 #id1 .c2 #id2 hello=world}
+An info admonition with multiple attributes.
+:::
\ No newline at end of file
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
index 4c50e27149fd..f4a8a4b280f3 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
@@ -13,7 +13,11 @@ exports[`admonitions remark plugin add custom keyword 1`] = `
 
 exports[`admonitions remark plugin attributes 1`] = `
 "<p>Admonitions with attributes</p>
-<admonition title="Info Title" class="bold" type="info"><p>An info admonition with a className attribute.</p></admonition>"
+<admonition title="Info Title" class="bold" type="info"><p>An info admonition with a className attribute.</p></admonition>
+<admonition class="bold italic" type="info"><p>An info admonition with multiple className attributes.</p></admonition>
+<admonition id="custom-id" type="info"><p>An info admonition with a custom id attribute.</p></admonition>
+<admonition id="custom-id" class="bold" type="info"><p>An info admonition with both id and className attributes.</p></admonition>
+<admonition class="c1 c2" id="id2" hello="world" type="info"><p>An info admonition with multiple attributes.</p></admonition>"
 `;
 
 exports[`admonitions remark plugin base 1`] = `
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts b/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
index 10cfa20b210b..85b910618454 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
@@ -99,6 +99,15 @@ const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
           node.attributes?.title ??
           (directiveLabel ? getTextOnlyTitle(directiveLabel) : undefined);
 
+        // Convert 'class' attribute to 'className' for React compatibility
+        const attributes = node.attributes
+          ? Object.fromEntries(
+              Object.entries(node.attributes).map(([key, value]) => [
+                key === 'class' ? 'className' : key,
+                value,
+              ]),
+            )
+          : {};
         // Transform the mdast directive node to a hast admonition node
         // See https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes
         // TODO in MDX v2 we should transform the whole directive to
@@ -107,7 +116,7 @@ const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
           hName: 'admonition',
           hProperties: {
             ...(textOnlyTitle && {title: textOnlyTitle}),
-            ...(node.attributes?.class && {className: node.attributes.class}),
+            ...attributes,
             type: node.name,
           },
         };

From 066a0094ee25cc1f256cc8a1dd4b52218c728a9d Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Fri, 2 Jan 2026 19:09:58 +0000
Subject: [PATCH 04/15] add more dogfood

---
 .../_docs tests/tests/admonitions.mdx         | 61 ++++++++++++++++++-
 website/_dogfooding/dogfooding.css            | 15 ++++-
 2 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index 9bcf8e754a46..97291cb50369 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -54,7 +54,34 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 </Admonition>
 ```
 
-## Admonitions with classes
+## Admonitions with attributes
+
+<details>
+<summary>Relevant CSS for this section</summary>
+
+```css title="dogfooding.css"
+/* ... */
+.shadow {
+  --shadow-color: red;
+  box-shadow: 10px 10px 10px var(--shadow-color);
+
+  &.blue {
+    --shadow-color: blue;
+  }
+}
+
+#info-1 {
+  border: solid 2px blue;
+}
+
+#info-2 {
+  border: solid 2px green;
+}
+```
+
+</details>
+
+### Classes
 
 :::info{.shadow}
 
@@ -62,6 +89,34 @@ The class `shadow` was added by writing `:::info{.shadow}`.
 
 :::
 
+:::info{.shadow .blue}
+
+The class `shadow` and `blue` were added by writing `:::info{.shadow .blue}`.
+
+:::
+
+### Ids
+
+:::info{#info-1}
+
+The id `info-1` was added by writing `:::{#info-1}`
+
+:::
+
+:::info{#info-3 #info-1 #info-2}
+
+The last provided id `info-2` wins when writing `:::{#info-3 #info-1 #info-2}`
+
+:::
+
+### Combination
+
+:::info{.shadow #info-4 .blue #info-2 hello=world}
+
+Multiple Classes, Ids and attributes: `:::info{.shadow #id1 .blue #id2 hello=world}`. `hello` is passed to the admonition component, but not further used, so ignored in the output.
+
+:::
+
 ## Indented admonitions
 
 See admonition title v2 compat syntax bug: https://github.com/facebook/docusaurus/issues/9507
@@ -155,3 +210,7 @@ success
 caution
 
 :::
+
+```
+
+```
diff --git a/website/_dogfooding/dogfooding.css b/website/_dogfooding/dogfooding.css
index bbf8c128591d..386c1548bbd0 100644
--- a/website/_dogfooding/dogfooding.css
+++ b/website/_dogfooding/dogfooding.css
@@ -26,7 +26,20 @@ html {
       }
 
       .shadow {
-        box-shadow: 10px 10px 10px red;
+        --shadow-color: red;
+        box-shadow: 10px 10px 10px var(--shadow-color);
+
+        &.blue {
+          --shadow-color: blue;
+        }
+      }
+
+      #info-1 {
+        border: solid 2px blue;
+      }
+
+      #info-2 {
+        border: solid 2px green;
       }
 
       .dogfood_sidebar_class_name_test {

From 41c11d04de8ec79100f878024490615118d2f274 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Fri, 2 Jan 2026 19:46:49 +0000
Subject: [PATCH 05/15] support passing ids and additional attributes

---
 .../docusaurus-theme-classic/src/theme-classic.d.ts    |  2 ++
 .../src/theme/Admonition/Layout/index.tsx              | 10 ++++++----
 website/_dogfooding/_docs tests/tests/admonitions.mdx  |  8 ++++----
 website/_dogfooding/dogfooding.css                     |  3 ++-
 4 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme-classic.d.ts b/packages/docusaurus-theme-classic/src/theme-classic.d.ts
index c38431f8b7f4..961d68fcc044 100644
--- a/packages/docusaurus-theme-classic/src/theme-classic.d.ts
+++ b/packages/docusaurus-theme-classic/src/theme-classic.d.ts
@@ -48,6 +48,7 @@ declare module '@theme/Admonition' {
     readonly icon?: ReactNode;
     readonly title?: ReactNode;
     readonly className?: string;
+    readonly id?: string;
   }
 
   export default function Admonition(props: Props): ReactNode;
@@ -123,6 +124,7 @@ declare module '@theme/Admonition/Layout' {
     readonly icon?: ReactNode;
     readonly title?: ReactNode;
     readonly className?: string;
+    readonly id?: string;
   }
   export default function AdmonitionLayout(props: Props): ReactNode;
 }
diff --git a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
index b90b6cb1dbbc..c87be7ff2221 100644
--- a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
@@ -17,7 +17,8 @@ function AdmonitionContainer({
   type,
   className,
   children,
-}: Pick<Props, 'type' | 'className'> & {children: ReactNode}) {
+  ...optional
+}: Pick<Props, 'type' | 'className' | 'id'> & {children: ReactNode}) {
   return (
     <div
       className={clsx(
@@ -25,7 +26,8 @@ function AdmonitionContainer({
         ThemeClassNames.common.admonitionType(type),
         styles.admonition,
         className,
-      )}>
+      )}
+      {...optional}>
       {children}
     </div>
   );
@@ -47,9 +49,9 @@ function AdmonitionContent({children}: Pick<Props, 'children'>) {
 }
 
 export default function AdmonitionLayout(props: Props): ReactNode {
-  const {type, icon, title, children, className} = props;
+  const {type, icon, title, children, className, ...optional} = props;
   return (
-    <AdmonitionContainer type={type} className={className}>
+    <AdmonitionContainer type={type} className={className} {...optional}>
       {title || icon ? <AdmonitionHeading title={title} icon={icon} /> : null}
       <AdmonitionContent>{children}</AdmonitionContent>
     </AdmonitionContainer>
diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index 97291cb50369..b2ed682e219e 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -62,8 +62,8 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 ```css title="dogfooding.css"
 /* ... */
 .shadow {
-  --shadow-color: red;
-  box-shadow: 10px 10px 10px var(--shadow-color);
+  --shadow-size: 10px;
+  box-shadow: 10px 10px var(--shadow-size) var(--shadow-color);
 
   &.blue {
     --shadow-color: blue;
@@ -111,9 +111,9 @@ The last provided id `info-2` wins when writing `:::{#info-3 #info-1 #info-2}`
 
 ### Combination
 
-:::info{.shadow #info-4 .blue #info-2 hello=world}
+:::info{.shadow #info-4 .blue #info-2 style="--shadow-size:5px"}
 
-Multiple Classes, Ids and attributes: `:::info{.shadow #id1 .blue #id2 hello=world}`. `hello` is passed to the admonition component, but not further used, so ignored in the output.
+Multiple Classes, Ids and attributes: `:::info{.shadow #id1 .blue #id2 style="--shadow-size:5px"}`.
 
 :::
 
diff --git a/website/_dogfooding/dogfooding.css b/website/_dogfooding/dogfooding.css
index 386c1548bbd0..fe7498e7e370 100644
--- a/website/_dogfooding/dogfooding.css
+++ b/website/_dogfooding/dogfooding.css
@@ -27,7 +27,8 @@ html {
 
       .shadow {
         --shadow-color: red;
-        box-shadow: 10px 10px 10px var(--shadow-color);
+        --shadow-size: 10px;
+        box-shadow: 10px 10px var(--shadow-size) var(--shadow-color);
 
         &.blue {
           --shadow-color: blue;

From fbf5019349c1117b46256e837259539b651cc17d Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Fri, 2 Jan 2026 19:50:54 +0000
Subject: [PATCH 06/15] add missing css rule

---
 website/_dogfooding/_docs tests/tests/admonitions.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index b2ed682e219e..ff33166ebacf 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -62,6 +62,7 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 ```css title="dogfooding.css"
 /* ... */
 .shadow {
+  --shadow-color: red;
   --shadow-size: 10px;
   box-shadow: 10px 10px var(--shadow-size) var(--shadow-color);
 

From d15fdf48f055006fb43aaedfa7e03901c13538a0 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Fri, 2 Jan 2026 20:15:46 +0000
Subject: [PATCH 07/15] add docs

---
 .../markdown-features-admonitions.mdx         | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
index 39353f587396..e41a16b84713 100644
--- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
@@ -129,6 +129,66 @@ Some **content** with some _Markdown_ `syntax`.
 </BrowserWindow>
 ```
 
+## Specifying attributes {#specifying-attributes}
+
+You may also provide optional attributes such as classes, IDs, or even inline styles. This feature is enabled by attribute parsing from remark-directives , where only text values are supported—no React syntax or evaluated expressions are allowed.
+
+```md
+:::note[With css classes]{.shadow--tl .text--italic}
+
+Note the box shadow and the italicized text.
+
+:::
+
+:::note{#admonition-id}
+
+You can link to [this admonition](#admonition-id).
+
+:::
+
+:::note[Style Attribute]{style="--ifm-alert-border-color:gold"}
+
+Only html attributes are supported - react syntax won't work.
+
+:::
+
+:::note{.shadow--tl #admonition-id-2 style="--ifm-alert-border-color:teal"}
+
+Combine multiple attributes together.
+
+:::
+```
+
+```mdx-code-block
+<BrowserWindow>
+
+:::note[With css classes]{.shadow--tl .text--italic}
+
+Note the box shadow and the italicized text.
+
+:::
+
+:::note{#admonition-id}
+
+You can link to [this admonition](#admonition-id).
+
+:::
+
+:::note[Style Attribute]{style="--ifm-alert-border-color:gold"}
+
+Only html attributes are supported - react syntax won't work.
+
+:::
+
+:::note{.shadow--tl #admonition-id-2 style="--ifm-alert-border-color:teal"}
+
+Combine multiple attributes together.
+
+:::
+
+</BrowserWindow>
+```
+
 ## Nested admonitions {#nested-admonitions}
 
 Admonitions can be nested. Use more colons `:` for each parent admonition level.

From 1babe74aa8718d4c048a91e3244554b6af7139ff Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Fri, 2 Jan 2026 20:34:54 +0000
Subject: [PATCH 08/15] use h5 heading when an id is provided

---
 .../src/theme/Admonition/Layout/index.tsx     | 28 +++++++++++++++----
 .../theme/Admonition/Layout/styles.module.css |  6 ++++
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
index c87be7ff2221..d08357ef61f2 100644
--- a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
@@ -10,6 +10,7 @@ import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
 import type {Props} from '@theme/Admonition/Layout';
+import Heading from '@theme/Heading';
 
 import styles from './styles.module.css';
 
@@ -33,11 +34,21 @@ function AdmonitionContainer({
   );
 }
 
-function AdmonitionHeading({icon, title}: Pick<Props, 'icon' | 'title'>) {
+function AdmonitionHeading({
+  icon,
+  title,
+  id,
+}: Pick<Props, 'icon' | 'title' | 'id'>) {
   return (
     <div className={styles.admonitionHeading}>
       <span className={styles.admonitionIcon}>{icon}</span>
-      {title}
+      {id ? (
+        <Heading as="h5" id={id} className={styles.admonitionHeadingLink}>
+          {title}
+        </Heading>
+      ) : (
+        title
+      )}
     </div>
   );
 }
@@ -49,10 +60,17 @@ function AdmonitionContent({children}: Pick<Props, 'children'>) {
 }
 
 export default function AdmonitionLayout(props: Props): ReactNode {
-  const {type, icon, title, children, className, ...optional} = props;
+  const {type, icon, title, children, className, id, ...optional} = props;
+  const hasHeading = !!(title || icon);
   return (
-    <AdmonitionContainer type={type} className={className} {...optional}>
-      {title || icon ? <AdmonitionHeading title={title} icon={icon} /> : null}
+    <AdmonitionContainer
+      type={type}
+      className={className}
+      id={hasHeading ? undefined : id}
+      {...optional}>
+      {hasHeading ? (
+        <AdmonitionHeading title={title} icon={icon} id={id} />
+      ) : null}
       <AdmonitionContent>{children}</AdmonitionContent>
     </AdmonitionContainer>
   );
diff --git a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css
index cc5f8655f1e3..3da723878b1d 100644
--- a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css
+++ b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css
@@ -13,6 +13,12 @@
   font: var(--ifm-heading-font-weight) var(--ifm-h5-font-size) /
     var(--ifm-heading-line-height) var(--ifm-heading-font-family);
   text-transform: uppercase;
+
+  .admonitionHeadingLink {
+    display: inline-block;
+    --ifm-heading-margin-top: 0;
+    --ifm-heading-margin-bottom: 0;
+  }
 }
 
 /* Heading alone without content (does not handle fragment content) */

From 1f55af2dd9bb9f8f9fe3df6e04baa1819d0325ed Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 12:08:07 +0100
Subject: [PATCH 09/15] Revert "use h5 heading when an id is provided"

This reverts commit 1babe74aa8718d4c048a91e3244554b6af7139ff.
---
 .../src/theme/Admonition/Layout/index.tsx     | 28 ++++---------------
 .../theme/Admonition/Layout/styles.module.css |  6 ----
 2 files changed, 5 insertions(+), 29 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
index d08357ef61f2..c87be7ff2221 100644
--- a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
@@ -10,7 +10,6 @@ import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
 import type {Props} from '@theme/Admonition/Layout';
-import Heading from '@theme/Heading';
 
 import styles from './styles.module.css';
 
@@ -34,21 +33,11 @@ function AdmonitionContainer({
   );
 }
 
-function AdmonitionHeading({
-  icon,
-  title,
-  id,
-}: Pick<Props, 'icon' | 'title' | 'id'>) {
+function AdmonitionHeading({icon, title}: Pick<Props, 'icon' | 'title'>) {
   return (
     <div className={styles.admonitionHeading}>
       <span className={styles.admonitionIcon}>{icon}</span>
-      {id ? (
-        <Heading as="h5" id={id} className={styles.admonitionHeadingLink}>
-          {title}
-        </Heading>
-      ) : (
-        title
-      )}
+      {title}
     </div>
   );
 }
@@ -60,17 +49,10 @@ function AdmonitionContent({children}: Pick<Props, 'children'>) {
 }
 
 export default function AdmonitionLayout(props: Props): ReactNode {
-  const {type, icon, title, children, className, id, ...optional} = props;
-  const hasHeading = !!(title || icon);
+  const {type, icon, title, children, className, ...optional} = props;
   return (
-    <AdmonitionContainer
-      type={type}
-      className={className}
-      id={hasHeading ? undefined : id}
-      {...optional}>
-      {hasHeading ? (
-        <AdmonitionHeading title={title} icon={icon} id={id} />
-      ) : null}
+    <AdmonitionContainer type={type} className={className} {...optional}>
+      {title || icon ? <AdmonitionHeading title={title} icon={icon} /> : null}
       <AdmonitionContent>{children}</AdmonitionContent>
     </AdmonitionContainer>
   );
diff --git a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css
index 3da723878b1d..cc5f8655f1e3 100644
--- a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css
+++ b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/styles.module.css
@@ -13,12 +13,6 @@
   font: var(--ifm-heading-font-weight) var(--ifm-h5-font-size) /
     var(--ifm-heading-line-height) var(--ifm-heading-font-family);
   text-transform: uppercase;
-
-  .admonitionHeadingLink {
-    display: inline-block;
-    --ifm-heading-margin-top: 0;
-    --ifm-heading-margin-bottom: 0;
-  }
 }
 
 /* Heading alone without content (does not handle fragment content) */

From 21649f35d7b60aab4df8396386c0c8bdfda02508 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 12:12:02 +0100
Subject: [PATCH 10/15] rm codeblock

---
 website/_dogfooding/_docs tests/tests/admonitions.mdx | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index ff33166ebacf..1703e4a0afe0 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -63,8 +63,7 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 /* ... */
 .shadow {
   --shadow-color: red;
-  --shadow-size: 10px;
-  box-shadow: 10px 10px var(--shadow-size) var(--shadow-color);
+  box-shadow: 10px 10px 10px var(--shadow-color);
 
   &.blue {
     --shadow-color: blue;
@@ -112,9 +111,9 @@ The last provided id `info-2` wins when writing `:::{#info-3 #info-1 #info-2}`
 
 ### Combination
 
-:::info{.shadow #info-4 .blue #info-2 style="--shadow-size:5px"}
+:::info{.shadow #info-4 .blue #info-2}
 
-Multiple Classes, Ids and attributes: `:::info{.shadow #id1 .blue #id2 style="--shadow-size:5px"}`.
+Multiple classes and ids: `{.shadow #info-4 .blue #info-2}`.
 
 :::
 
@@ -211,7 +210,3 @@ success
 caution
 
 :::
-
-```
-
-```

From 05dd1fd3de98d92bebc330184d877a024f7b7f28 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 11:30:54 +0000
Subject: [PATCH 11/15] ignore arbitrary attributes from admonitions

---
 .../admonitions/__tests__/__fixtures__/attributes.md |  2 +-
 .../__tests__/__snapshots__/index.test.ts.snap       |  4 ++--
 .../src/remark/admonitions/index.ts                  | 12 ++----------
 3 files changed, 5 insertions(+), 13 deletions(-)

diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
index ccf3c3d93422..eb91dea38bbf 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__fixtures__/attributes.md
@@ -17,5 +17,5 @@ An info admonition with both id and className attributes.
 :::
 
 :::info{.c1 #id1 .c2 #id2 hello=world}
-An info admonition with multiple attributes.
+Arbitrary attributes are ignored.
 :::
\ No newline at end of file
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
index f4a8a4b280f3..23b93a2b663f 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap
@@ -16,8 +16,8 @@ exports[`admonitions remark plugin attributes 1`] = `
 <admonition title="Info Title" class="bold" type="info"><p>An info admonition with a className attribute.</p></admonition>
 <admonition class="bold italic" type="info"><p>An info admonition with multiple className attributes.</p></admonition>
 <admonition id="custom-id" type="info"><p>An info admonition with a custom id attribute.</p></admonition>
-<admonition id="custom-id" class="bold" type="info"><p>An info admonition with both id and className attributes.</p></admonition>
-<admonition class="c1 c2" id="id2" hello="world" type="info"><p>An info admonition with multiple attributes.</p></admonition>"
+<admonition class="bold" id="custom-id" type="info"><p>An info admonition with both id and className attributes.</p></admonition>
+<admonition class="c1 c2" id="id2" type="info"><p>Arbitrary attributes are ignored.</p></admonition>"
 `;
 
 exports[`admonitions remark plugin base 1`] = `
diff --git a/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts b/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
index 85b910618454..15bfb37e5326 100644
--- a/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts
@@ -99,15 +99,6 @@ const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
           node.attributes?.title ??
           (directiveLabel ? getTextOnlyTitle(directiveLabel) : undefined);
 
-        // Convert 'class' attribute to 'className' for React compatibility
-        const attributes = node.attributes
-          ? Object.fromEntries(
-              Object.entries(node.attributes).map(([key, value]) => [
-                key === 'class' ? 'className' : key,
-                value,
-              ]),
-            )
-          : {};
         // Transform the mdast directive node to a hast admonition node
         // See https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes
         // TODO in MDX v2 we should transform the whole directive to
@@ -116,7 +107,8 @@ const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
           hName: 'admonition',
           hProperties: {
             ...(textOnlyTitle && {title: textOnlyTitle}),
-            ...attributes,
+            ...(node.attributes?.class && {className: node.attributes.class}),
+            ...(node.attributes?.id && {id: node.attributes.id}),
             type: node.name,
           },
         };

From 2aba6e771d02454d5fa6688ca2f3a400a930263d Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 11:31:08 +0000
Subject: [PATCH 12/15] update docs

---
 .../_docs tests/tests/admonitions.mdx         |  8 +++--
 website/_dogfooding/dogfooding.css            |  7 +++--
 .../markdown-features-admonitions.mdx         | 30 ++++++-------------
 3 files changed, 20 insertions(+), 25 deletions(-)

diff --git a/website/_dogfooding/_docs tests/tests/admonitions.mdx b/website/_dogfooding/_docs tests/tests/admonitions.mdx
index 1703e4a0afe0..4a80c46b2734 100644
--- a/website/_dogfooding/_docs tests/tests/admonitions.mdx	
+++ b/website/_dogfooding/_docs tests/tests/admonitions.mdx	
@@ -77,6 +77,10 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 #info-2 {
   border: solid 2px green;
 }
+
+#info-3 {
+  border: solid 2px red;
+}
 ```
 
 </details>
@@ -111,9 +115,9 @@ The last provided id `info-2` wins when writing `:::{#info-3 #info-1 #info-2}`
 
 ### Combination
 
-:::info{.shadow #info-4 .blue #info-2}
+:::info{.shadow #info-4 .blue #info-3}
 
-Multiple classes and ids: `{.shadow #info-4 .blue #info-2}`.
+Multiple classes and ids: `{.shadow #info-4 .blue #info-3}`.
 
 :::
 
diff --git a/website/_dogfooding/dogfooding.css b/website/_dogfooding/dogfooding.css
index fe7498e7e370..3ae643d6f197 100644
--- a/website/_dogfooding/dogfooding.css
+++ b/website/_dogfooding/dogfooding.css
@@ -27,8 +27,7 @@ html {
 
       .shadow {
         --shadow-color: red;
-        --shadow-size: 10px;
-        box-shadow: 10px 10px var(--shadow-size) var(--shadow-color);
+        box-shadow: 10px 10px 10px var(--shadow-color);
 
         &.blue {
           --shadow-color: blue;
@@ -43,6 +42,10 @@ html {
         border: solid 2px green;
       }
 
+      #info-3 {
+        border: solid 2px red;
+      }
+
       .dogfood_sidebar_class_name_test {
         &.theme-doc-sidebar-item-link > a {
           color: cyan;
diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
index e41a16b84713..fc2b4035eeaa 100644
--- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
@@ -131,12 +131,12 @@ Some **content** with some _Markdown_ `syntax`.
 
 ## Specifying attributes {#specifying-attributes}
 
-You may also provide optional attributes such as classes, IDs, or even inline styles. This feature is enabled by attribute parsing from remark-directives , where only text values are supported—no React syntax or evaluated expressions are allowed.
+You may also provide classes or IDs to admonitions.
 
 ```md
-:::note[With css classes]{.shadow--tl .text--italic}
+:::note[With css classes]{.padding--lg .text--italic}
 
-Note the box shadow and the italicized text.
+Note the padding and the italicized text.
 
 :::
 
@@ -146,15 +146,9 @@ You can link to [this admonition](#admonition-id).
 
 :::
 
-:::note[Style Attribute]{style="--ifm-alert-border-color:gold"}
+:::note{.padding--lg #admonition-id-2}
 
-Only html attributes are supported - react syntax won't work.
-
-:::
-
-:::note{.shadow--tl #admonition-id-2 style="--ifm-alert-border-color:teal"}
-
-Combine multiple attributes together.
+Use id and classes together.
 
 :::
 ```
@@ -162,9 +156,9 @@ Combine multiple attributes together.
 ```mdx-code-block
 <BrowserWindow>
 
-:::note[With css classes]{.shadow--tl .text--italic}
+:::note[With css classes]{.padding--lg .text--italic}
 
-Note the box shadow and the italicized text.
+Note the padding and the italicized text.
 
 :::
 
@@ -174,15 +168,9 @@ You can link to [this admonition](#admonition-id).
 
 :::
 
-:::note[Style Attribute]{style="--ifm-alert-border-color:gold"}
-
-Only html attributes are supported - react syntax won't work.
-
-:::
-
-:::note{.shadow--tl #admonition-id-2 style="--ifm-alert-border-color:teal"}
+:::note{.padding--lg #admonition-id-2}
 
-Combine multiple attributes together.
+Use id and classes together.
 
 :::
 

From 188c8fd4ca420cc0a4c26f3d81bd253c15a14760 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 11:33:50 +0000
Subject: [PATCH 13/15] pass id explicit

---
 .../src/theme/Admonition/Layout/index.tsx                 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
index c87be7ff2221..521712de772c 100644
--- a/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx
@@ -17,7 +17,7 @@ function AdmonitionContainer({
   type,
   className,
   children,
-  ...optional
+  id,
 }: Pick<Props, 'type' | 'className' | 'id'> & {children: ReactNode}) {
   return (
     <div
@@ -27,7 +27,7 @@ function AdmonitionContainer({
         styles.admonition,
         className,
       )}
-      {...optional}>
+      id={id}>
       {children}
     </div>
   );
@@ -49,9 +49,9 @@ function AdmonitionContent({children}: Pick<Props, 'children'>) {
 }
 
 export default function AdmonitionLayout(props: Props): ReactNode {
-  const {type, icon, title, children, className, ...optional} = props;
+  const {type, icon, title, children, className, id} = props;
   return (
-    <AdmonitionContainer type={type} className={className} {...optional}>
+    <AdmonitionContainer type={type} className={className} id={id}>
       {title || icon ? <AdmonitionHeading title={title} icon={icon} /> : null}
       <AdmonitionContent>{children}</AdmonitionContent>
     </AdmonitionContainer>

From cff0013548b9ea4b002a45c74b7c094a6552cc62 Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 11:40:41 +0000
Subject: [PATCH 14/15] update docs example

---
 .../markdown-features/markdown-features-admonitions.mdx       | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
index fc2b4035eeaa..940a1f61438a 100644
--- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
@@ -148,7 +148,7 @@ You can link to [this admonition](#admonition-id).
 
 :::note{.padding--lg #admonition-id-2}
 
-Use id and classes together.
+Use [id](#admonition-id-2) and classes together.
 
 :::
 ```
@@ -170,7 +170,7 @@ You can link to [this admonition](#admonition-id).
 
 :::note{.padding--lg #admonition-id-2}
 
-Use id and classes together.
+Use [id](#admonition-id-2) and classes together.
 
 :::
 

From e9278f862dad38d0c4fcb2f593d0f9c361c6598e Mon Sep 17 00:00:00 2001
From: bh0fer <lebalz@outlook.com>
Date: Sat, 3 Jan 2026 11:44:46 +0000
Subject: [PATCH 15/15] fix broken links

---
 .../markdown-features/markdown-features-admonitions.mdx   | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
index 940a1f61438a..60f8605ad347 100644
--- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
@@ -142,13 +142,13 @@ Note the padding and the italicized text.
 
 :::note{#admonition-id}
 
-You can link to [this admonition](#admonition-id).
+The admonition container has now the id `admonition-id`.
 
 :::
 
 :::note{.padding--lg #admonition-id-2}
 
-Use [id](#admonition-id-2) and classes together.
+Use id and classes together.
 
 :::
 ```
@@ -164,13 +164,13 @@ Note the padding and the italicized text.
 
 :::note{#admonition-id}
 
-You can link to [this admonition](#admonition-id).
+The admonition container has now the id `admonition-id`.
 
 :::
 
 :::note{.padding--lg #admonition-id-2}
 
-Use [id](#admonition-id-2) and classes together.
+Use id and classes together.
 
 :::