fix: adds a grey background to the dark themed images

README.md

@@ -72,6 +72,29 @@ npm start
 
 This starts a local dev server at `http://localhost:3000` and opens the browser automatically. Most changes are reflected live without restarting the server.
 
+### Dark Mode: Images with light background (`:::image-light`)
+
+Some diagrams or screenshots have a transparent or white background and become hard to read in dark mode. Wrap them with the `:::image-light` directive to automatically add a subtle light background behind the image in dark mode.
+
+**Usage in MDX/Markdown:**
+
+```mdx
+:::image-light
+![Architecture overview](/img/contribution/Picture.png)
+:::
+```
+
+**What it does:**
+
+- Adds a `rgba(255, 255, 255, 0.9)` background behind the image
+- Adds `8px` padding and rounded corners (`border-radius: 8px`)
+- Works in both light and dark mode
+- Does **not** affect logos, icons, or the Axolotl mascot (these are excluded by default from the global dark-mode image rule)
+
+**When to use it:**
+
+Use `:::image-light` for screenshots, architecture diagrams, or any image that has a transparent or near-white background and looks broken/invisible in dark mode.
+
 ### Build
 
 ```bash

docs/contribution/0-understand-providers.mdx

@@ -8,22 +8,25 @@ import Link from '@docusaurus/Link'
 # 👋 Provider Intro
 ## Situation Today
 
+:::image-light
 ![today](/img/contribution/Picture.png)
+:::
 
 Most often, you use an API to create infrastructure in the cloud. More advanced teams have leveraged the benefits of Infrastructure as Code with tools like Terraform. While this already offers massive benefits like reproducibility and version control, there is one thing missing: **what happens if your landscape changes after you apply it?** It is no longer consistent with the state specified in the configuration file.
 
 ## Introducing Crossplane
 
+:::image-light
 ![crossplane](/img/contribution/Picture0.png)
-
+:::
 Having faced these challenges, especially in larger organizations, one can quickly see that using Infrastructure as Code alone is not enough. We want clarity about the state of our landscape. When we define Infrastructure as Code, it should truly reflect that definition no matter what.
 This is what Crossplane does for us. It uses a declarative approach to manage APIs and leverages the Kubernetes reconciliation loop to repeatedly check and ensure that the state defined in our files matches the actual state at the API.
 This is what we call Infrastructure as Data. We are not using a high-level markup language or dependency trees of related resources. Only Cloud native and Kubernetes like resources, this is the way to the future!
 
 ## How it works
-
+:::image-light
 ![architecture](/img/contribution/Picture1.png)
-
+:::
 Crossplane uses the concept of Kubernetes Operators to extend Kubernetes with custom behavior. This enables us to introduce Crossplane Providers and custom Managed Resources to a Control Plane.
 
 #### Control Plane

docusaurus.config.js

@@ -1,4 +1,10 @@
 // @ts-check
+// remark-directive is ESM-only; require() returns the module namespace object
+const remarkDirective = (() => {
+  const m = require('remark-directive');
+  return m.default ?? m;
+})();
+const remarkImageLight = require('./src/plugins/remark-image-light');
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -29,6 +35,7 @@ const config = {
           path: 'docs',
           routeBasePath: 'docs',
           sidebarPath: require.resolve('./sidebars.js'),
+          remarkPlugins: [remarkDirective, remarkImageLight],
           exclude: [
             // exclude everything in the btp submodule except the docs/ subfolder
             'crossplane-provider-btp/!(docs)/**',

src/css/custom.css

@@ -813,3 +813,29 @@ html[data-theme="light"] #__docusaurus :where(.markdown, .theme-doc-markdown, .c
     font-size: 2em;
   }
 }
+
+/* ===== :::image-light directive: always show light background around images ===== */
+/*
+ * Usage in MDX:
+ *   :::image-light
+ *   ![alt text](./img/my-diagram.png)
+ *   :::
+ *
+ * Usage in JSX:
+ *   <div className="doc-image-light">...</div>
+ *
+ * Applies a white background with padding/radius in BOTH light and dark mode.
+ * Useful for diagrams with transparent backgrounds.
+ */
+.doc-image-light img {
+  background-color: rgba(255, 255, 255, 0.9);
+  padding: 8px;
+  border-radius: 8px;
+}
+
+html[data-theme="dark"] .doc-image-light img {
+  background-color: rgba(255, 255, 255, 0.9) !important;
+  padding: 8px;
+  border-radius: 8px;
+}
+

src/pages/index.js

@@ -157,7 +157,7 @@ export default function Home() {
           </Link>
           <span>
             or explore{" "}
-            <Link to="/crossplane-provider-docs/docs/crossplane-provider-btp/docs/user/external-name">
+            <Link to="/crossplane-provider-docs/docs/crossplane-provider-btp/docs/user-stories/btp">
               our crossplane provider for SAP BTP
             </Link>
           </span>
@@ -169,11 +169,13 @@ export default function Home() {
               <div className="open-source-wrapper">
                 <div className="typing-open-source">100% open-source</div>
               </div>
-              <img
-                src={require("/img/landingpage-crossplane.png").default}
-                alt="Crossplane based on CNCF"
-                style={{ maxWidth: "100%", marginBottom: "24px" }}
-              />
+              <div className="doc-image-light">
+                <img
+                  src={require("/img/landingpage-crossplane.png").default}
+                  alt="Crossplane based on CNCF"
+                  style={{ maxWidth: "100%", marginBottom: "24px" }}
+                />
+              </div>
               <p>
                 Through technical <b>providers</b>, we request, update and delete the cloud resources we want to
                 orchestrate. They <b>allow us to describe environments in code</b>. Most SAP cloud services do not

src/plugins/remark-image-light.js

@@ -0,0 +1,37 @@
+// @ts-nocheck
+/**
+ * Remark plugin that transforms :::image-light container directives into
+ * a <div class="doc-image-light"> wrapper.
+ *
+ * Usage in MDX:
+ *
+ *   :::image-light
+ *   ![alt text](./img/my-diagram.png)
+ *   :::
+ *
+ * The wrapper applies a light background to images in dark mode AND light mode,
+ * which is useful for diagrams with transparent backgrounds.
+ *
+ * Requires `remark-directive` to be registered before this plugin.
+ */
+
+const { visit } = require('unist-util-visit');
+
+/** @type {import('unified').Plugin} */
+function remarkImageLight() {
+  return (tree) => {
+    visit(tree, (node) => {
+      if (node.type === 'containerDirective' && node.name === 'image-light') {
+        const data = node.data || (node.data = {});
+        // Render as a <div> with the CSS class
+        data.hName = 'div';
+        data.hProperties = {
+          className: ['doc-image-light'],
+          ...(node.attributes || {}),
+        };
+      }
+    });
+  };
+}
+
+module.exports = remarkImageLight;