update

app/src/components/Hero.astro

@@ -89,7 +89,7 @@ const pdfFilename = `${slugify(pdfBase)}.pdf`;
 <style>
   /* Hero (full-width) */
   .hero { width: 100%; padding: 48px 16px 16px; text-align: center; }
-  .hero-title { font-size: clamp(28px, 4vw, 48px); font-weight: 800; line-height: 1.1; margin: 0 0 8px; max-width: 60%; margin: auto; }
+  .hero-title { font-size: clamp(28px, 4vw, 48px); font-weight: 800; line-height: 1.1; margin: 0 0 8px; max-width: 100%; margin: auto; }
   .hero-banner { max-width: 980px; margin: 0 auto; }
   .hero-desc { color: var(--muted-color); font-style: italic; margin: 0 0 16px 0; }
 

app/src/content/chapters/available-blocks.mdx

@@ -109,12 +109,12 @@ Here are a few variations using the same bibliography:
 
 **Responsive images** automatically generate an optimized `srcset` and `sizes` so the browser downloads the most appropriate file for the current viewport and DPR. You can also request multiple output formats (e.g., **AVIF**, **WebP**, fallback **PNG/JPEG**) and control **lazy loading/decoding** for better **performance**.
 
-| Prop                   | Required | Description                                                                                                         | Option/Note                                                                                                 |
-|------------------------|----------|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
-| `data-zoomable`        | No       | Adds a zoomable lightbox (Medium-like).                                                                             | Only images with this attribute will open full-screen on click.                                             |
-| `data-downloadable`    | No       | Adds a small download button to fetch the image file.                                                               | By default uses the original filename. Can be customized with `data-download-name` and `data-download-src`. |
-| `loading="lazy"`       | No       | Lazy loads the image.                                                                                               | Defers image loading until it is visible on screen.                                                         |
-| `caption`              | No       | Adds a caption and credit.                                                                                          | Pass HTML as the `caption` prop, or use `<slot name="caption">`. Keep `<span className="image-credit">` for credits. |
+| Prop                   | Required | Description                                                                                                         
+|------------------------|----------|-------------------------------------------------------
+| `data-zoomable`        | No       | Adds a zoomable lightbox (Medium-like).                                                                             
+| `data-downloadable`    | No       | Adds a small download button to fetch the image file.                                                               
+| `loading="lazy"`       | No       | Lazy loads the image.                                                                                               
+| `caption`              | No       | Adds a caption and credit.                                                                                          
 
 
 <ResponsiveImage
@@ -278,7 +278,6 @@ greet("Astro");
 </Accordion>
 ````
 
-
 ### Note
 
 Small contextual callout for tips, caveats, or emphasis.
@@ -348,7 +347,7 @@ They exist in the `app/src/content/embeds` folder.
 For researchers who want to stay in **Python** while targeting **D3**, the [d3blocks](https://github.com/d3blocks/d3blocks) library lets you create interactive D3 charts with only a few lines of code. In **2025**, **D3** often provides more flexibility and a more web‑native rendering than **Plotly** for custom visualizations.
 
 | Prop        | Required | Description                                                                                      
-|-------------|----------|--------------------------------------------------------------------------------------------------
+|-------------|----------|----------------------------------------------------------------------------------
 | `src`       | Yes      | Path to the embed file in the `embeds` folder.                                                   
 | `title`     | No       | Short title displayed above the card.                                                            
 | `desc`      | No       | Short description displayed below the card. Supports inline HTML (e.g., links).                  

app/src/content/chapters/best-pratices.mdx

@@ -1,7 +1,7 @@
 
-import { Image } from 'astro:assets';
 import visualPoster from '../assets/images/visual-vocabulary-poster.png';
 import Note from '../../components/Note.astro';
+import ResponsiveImage from '../../components/ResponsiveImage.astro';
 
 
 ## Best Practices
@@ -55,12 +55,11 @@ A palette encodes **meaning** (categories, magnitudes, oppositions), preserves *
 
 Picking the right visualization depends on your goal (compare values, show distribution, part-to-whole, trends, relationships, etc.). The Visual Vocabulary poster below provides a concise mapping from **analytical task** to **chart types**.
 
-<figure>
-  <a href={"https://raw.githubusercontent.com/Financial-Times/chart-doctor/refs/heads/main/visual-vocabulary/poster.png"} target="_blank" rel="noopener noreferrer">
-    <Image src={visualPoster} alt="Visual Vocabulary: choosing the right chart by task" />
-  </a>
-  <figcaption>
-    A handy reference to select chart types by purpose — click to enlarge.
-  </figcaption> 
-</figure>
 
+  <a href={"https://raw.githubusercontent.com/Financial-Times/chart-doctor/refs/heads/main/visual-vocabulary/poster.png"} target="_blank" rel="noopener noreferrer">
+<ResponsiveImage
+  src={visualPoster}
+  alt="Visual Vocabulary: choosing the right chart by task"
+  caption={'A handy reference to select chart types by purpose — click to enlarge.'}
+/>
+</a>

app/src/content/chapters/writing-your-content.mdx

@@ -16,7 +16,7 @@ Your **article** lives in **one place**
 Everything is **self-contained** under `app/src/content/`:
 - **MDX**: `article.mdx` and [**optional chapters**](#chapters) in `chapters/`
 - **Assets**: `assets/` (**images**, **audios**, **datas**, etc.) tracked via **Git LFS**)
-- **Embeds**: `embed/` (**HTMLEmbed** for **Plotly/D3**, etc.) — see [**HtmlEmbed**](#htmlembed)
+- **Embeds**: `embed/` ([**HtmlEmbed**](#htmlembed) for **Plotly/D3**, etc.)
 
 The `article.mdx` file is the **main entry point** of your article.
 

app/src/styles/_base.css

@@ -97,8 +97,23 @@ html { font-size: 14px; line-height: 1.6; }
 }
 
 
-.content-grid main table { border-collapse: collapse; width: 100%; margin: 0 0 var(--spacing-4); }
-.content-grid main th, .content-grid main td { border-bottom: 1px solid var(--border-color); padding: 6px 8px; text-align: left; font-size: 15px; }
+.content-grid main table {
+  border-collapse: collapse;
+  /* Make markdown tables scroll horizontally when they overflow on small screens */
+  display: block;
+  width: 100%;
+  max-width: none;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  margin: 0 0 var(--spacing-4);
+}
+.content-grid main th, .content-grid main td {
+  border-bottom: 1px solid var(--border-color);
+  padding: 6px 8px;
+  text-align: left;
+  font-size: 15px;
+  white-space: nowrap; /* prevent squashing; allow horizontal scroll instead */
+}
 .content-grid main thead th { border-bottom: 1px solid var(--border-color); }
 
 .content-grid main hr { border: none; border-bottom: 1px solid var(--border-color); margin: var(--spacing-5) 0; }