From 059a9c741df080312e87067f2b68b60d9826f4ac Mon Sep 17 00:00:00 2001
From: Greg Annandale <greg@raspberrypi.org>
Date: Tue, 7 Apr 2026 10:19:06 +0100
Subject: [PATCH] chore(docs): replace CompareBlock component with admonition
 syntax

---
 .../guides/app-integration/attribution.mdx    | 29 +++------
 .../contribute/samples/block_libraries.mdx    | 62 ++++++++-----------
 packages/docs/src/components/CompareBlock.js  |  5 --
 packages/docs/src/css/custom.css              | 34 ----------
 4 files changed, 35 insertions(+), 95 deletions(-)
 delete mode 100644 packages/docs/src/components/CompareBlock.js
diff --git a/packages/docs/docs/guides/app-integration/attribution.mdx b/packages/docs/docs/guides/app-integration/attribution.mdx
index 4f7df2e81..53d321a84 100644
--- a/packages/docs/docs/guides/app-integration/attribution.mdx
+++ b/packages/docs/docs/guides/app-integration/attribution.mdx
@@ -6,13 +6,6 @@ image: images/blockly_banner.png
 
 import Image from '@site/src/components/Image';
 
-<head>
-  <link
-    href="https://fonts.googleapis.com/icon?family=Material+Icons"
-    rel="stylesheet"
-  />
-</head>
-
 # Attribute Blockly
 
 Blockly's code is open source and free to use without attribution.
@@ -46,18 +39,16 @@ press interviews, the app, and on your website.
 
 ### Reference do's and don'ts
 
-<p>
-  <span className="compare-better">Do</span> — Call Blockly "beginner friendly"
-  instead of "kid friendly." Blockly is used for a variety of applications, not
-  all of which are kid focused.
-</p>
+:::tip[Do]
+Call Blockly "beginner friendly" instead of "kid friendly." Blockly is used for
+a variety of applications, not all of which are kid focused.
+:::
 
-<p>
-  <span className="compare-worse">Don't</span> — Refer to Blockly as a language
-  (for example, as a "block-based programming language"). Blockly is not a
-  language, it's a library that developers use to make a block-based visual
-  programming interface.
-</p>
+:::danger[Don't]
+Refer to Blockly as a language (for example, as a "block-based programming
+language"). Blockly is not a language, it's a library that developers use to
+make a block-based visual programming interface.
+:::
 
 ## How to visually represent Blockly
 
@@ -324,7 +315,7 @@ element on your page.
       Never crowd or overlap the logo with other elements.
     </p>
     <h3>Common errors</h3>
-    <span className="compare-worse">Do not...</span>
+    <b>Do not...</b>
     <ul>
       <li>Alter or distort the logo in any way</li>
       <li>Use the white knockout in any color but white</li>
diff --git a/packages/docs/docs/guides/contribute/samples/block_libraries.mdx b/packages/docs/docs/guides/contribute/samples/block_libraries.mdx
index 2c414147a..134c24450 100644
--- a/packages/docs/docs/guides/contribute/samples/block_libraries.mdx
+++ b/packages/docs/docs/guides/contribute/samples/block_libraries.mdx
@@ -4,17 +4,6 @@ title: Publish block libraries
 image: images/blockly_banner.png
 ---
 
-import Head from '@docusaurus/Head';
-import CompareBlock from '@site/src/components/CompareBlock';
-
-<Head>
-  <link
-    href="https://fonts.googleapis.com/icon?family=Material+Icons"
-    rel="stylesheet"
-  />
-</Head>
-
-
 # Publish block libraries
 
 Plugins that provide libraries of block definitions are a great way to share
@@ -42,35 +31,34 @@ versatile and useful as possible, we've developed these guidelines.
         pieces they need without worrying that pieces they don't will be
         installed.
 -   Use the JSON field registry instead of instantiating new fields directly.
- 
-    - <CompareBlock variant="worse">
-        Not Recommended - Instantiating a new field directly:
+    :::danger[Not Recommended]
+    Instantiating a new field directly:
 
-          ```js
-          const myCustomBlock = {
-            init: function() {
-              this.appendDummyInput()
-                  .appendField(new Blockly.FieldNumber(123), 'NAME');
-            }
-          }
-          ```
-      </CompareBlock>  
+    ```js
+    const myCustomBlock = {
+      init: function() {
+        this.appendDummyInput()
+            .appendField(new Blockly.FieldNumber(123), 'NAME');
+      }
+    }
+    ```
+    :::
 
-    - <CompareBlock variant="better">   
-        Recommended - JSON field registry:
+    :::tip[Recommended]
+    Use the JSON field registry:
 
-          ```js
-          export const myCustomBlock = {
-            init: function() {
-              this.appendDummyInput()
-                  .appendField(Blockly.fieldRegistry.fromJson({
-                      name: 'field_number',
-                      value: 123,
-                    }), 'NAME');
-            }
-          }
-          ```
-      </CompareBlock> 
+    ```js
+    export const myCustomBlock = {
+      init: function() {
+        this.appendDummyInput()
+            .appendField(Blockly.fieldRegistry.fromJson({
+                name: 'field_number',
+                value: 123,
+              }), 'NAME');
+      }
+    }
+    ```
+    :::
 
     -   Using the field registry makes it easier for a user to replace the
         implementation of the field used in your block without having to change
diff --git a/packages/docs/src/components/CompareBlock.js b/packages/docs/src/components/CompareBlock.js
deleted file mode 100644
index 8bb0df421..000000000
--- a/packages/docs/src/components/CompareBlock.js
+++ /dev/null
@@ -1,5 +0,0 @@
-import React from 'react';
-
-export default function CompareBlock({ variant, children }) {
-  return <p className={`compare-${variant}`}>{children}</p>;
-}
diff --git a/packages/docs/src/css/custom.css b/packages/docs/src/css/custom.css
index 42aef9b91..b5d5814d1 100644
--- a/packages/docs/src/css/custom.css
+++ b/packages/docs/src/css/custom.css
@@ -270,40 +270,6 @@ table th p {
   transform: scale(1.05);
 }
 
-.compare-better:before {
-  content: 'thumb_up';
-  color: #1e8e3e;
-  font-family: 'Material Icons' !important;
-  font-weight: normal;
-  font-style: normal;
-  font-size: 24px;
-  margin-inline: 0 4px;
-  vertical-align: middle;
-  width: 24px;
-}
-
-.compare-worse:before {
-  content: 'thumb_down';
-  color: #d50000;
-  font-family: 'Material Icons' !important;
-  font-weight: normal;
-  font-style: normal;
-  font-size: 24px;
-  margin-inline: 0 4px;
-  vertical-align: middle;
-  width: 24px;
-}
-
-.compare-better,
-.compare-worse {
-  font-weight: 700;
-}
-
-.compare-better p,
-.compare-worse p {
-  margin-top: 0;
-}
-
 .appendInputImg {
   width: 145px !important;
 }
