diff --git a/docs/css/custom.css b/docs/css/custom.css
index 5ab062952..4f24ebc44 100644
--- a/docs/css/custom.css
+++ b/docs/css/custom.css
@@ -199,8 +199,39 @@ body {
   width: 100%;
 }
 
+/* Add comprehensive image control */
+.markdown img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  margin: 1rem auto;
+  max-height: 500px;
+  object-fit: contain;
+}
+
+/* Default size for most images */
+.markdown img:not(.resized-image) {
+  max-width: 500px;
+  width: auto;
+}
+
 .resized-image {
-  width: 400px;
+  width: 250px;
+  max-height: 400px;
+}
+
+/* Responsive images on mobile devices */
+@media (max-width: 768px) {
+  .markdown img:not(.resized-image) {
+    max-width: 100%;
+    max-height: 400px;
+  }
+  
+  .resized-image {
+    width: 100%;
+    max-width: 250px;
+    max-height: 300px;
+  }
 }
 
 /* Reduce width on mobile for Mendable Search */