[pull] main from facebook:main

packages/docusaurus-mdx-loader/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap

@@ -11,6 +11,15 @@ 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>
+<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 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`] = `
 "<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>

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();
+  });
 });

packages/docusaurus-mdx-loader/src/remark/admonitions/index.ts

@@ -107,6 +107,8 @@ const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
           hName: 'admonition',
           hProperties: {
             ...(textOnlyTitle && {title: textOnlyTitle}),
+            ...(node.attributes?.class && {className: node.attributes.class}),
+            ...(node.attributes?.id && {id: node.attributes.id}),
             type: node.name,
           },
         };

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;
 }

packages/docusaurus-theme-classic/src/theme/Admonition/Layout/index.tsx

@@ -17,15 +17,17 @@ function AdmonitionContainer({
   type,
   className,
   children,
-}: Pick<Props, 'type' | 'className'> & {children: ReactNode}) {
+  id,
+}: Pick<Props, 'type' | 'className' | 'id'> & {children: ReactNode}) {
   return (
     <div
       className={clsx(
         ThemeClassNames.common.admonition,
         ThemeClassNames.common.admonitionType(type),
         styles.admonition,
         className,
-      )}>
+      )}
+      id={id}>
       {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, id} = props;
   return (
-    <AdmonitionContainer type={type} className={className}>
+    <AdmonitionContainer type={type} className={className} id={id}>
       {title || icon ? <AdmonitionHeading title={title} icon={icon} /> : null}
       <AdmonitionContent>{children}</AdmonitionContent>
     </AdmonitionContainer>

website/_dogfooding/_docs tests/tests/admonitions.mdx

@@ -54,6 +54,73 @@ import InfoIcon from "@theme/Admonition/Icon/Info"
 </Admonition>
 ```
 
+## 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;
+}
+
+#info-3 {
+  border: solid 2px red;
+}
+```
+
+</details>
+
+### Classes
+
+:::info{.shadow}
+
+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-3}
+
+Multiple classes and ids: `{.shadow #info-4 .blue #info-3}`.
+
+:::
+
 ## Indented admonitions
 
 See admonition title v2 compat syntax bug: https://github.com/facebook/docusaurus/issues/9507

website/_dogfooding/dogfooding.css

@@ -25,6 +25,27 @@ html {
         border-bottom: solid thin cyan;
       }
 
+      .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;
+      }
+
+      #info-3 {
+        border: solid 2px red;
+      }
+
       .dogfood_sidebar_class_name_test {
         &.theme-doc-sidebar-item-link > a {
           color: cyan;

website/docs/guides/markdown-features/markdown-features-admonitions.mdx

@@ -129,6 +129,54 @@ Some **content** with some _Markdown_ `syntax`.
 </BrowserWindow>
 ```
 
+## Specifying attributes {#specifying-attributes}
+
+You may also provide classes or IDs to admonitions.
+
+```md
+:::note[With css classes]{.padding--lg .text--italic}
+
+Note the padding and the italicized text.
+
+:::
+
+:::note{#admonition-id}
+
+The admonition container has now the id `admonition-id`.
+
+:::
+
+:::note{.padding--lg #admonition-id-2}
+
+Use id and classes together.
+
+:::
+```
+
+```mdx-code-block
+<BrowserWindow>
+
+:::note[With css classes]{.padding--lg .text--italic}
+
+Note the padding and the italicized text.
+
+:::
+
+:::note{#admonition-id}
+
+The admonition container has now the id `admonition-id`.
+
+:::
+
+:::note{.padding--lg #admonition-id-2}
+
+Use id and classes together.
+
+:::
+
+</BrowserWindow>
+```
+
 ## Nested admonitions {#nested-admonitions}
 
 Admonitions can be nested. Use more colons `:` for each parent admonition level.