Move assets into content/assets; update imports; clean .gitattributes; fix LFS tracking

.gitattributes

@@ -1,5 +1,3 @@
-app/assets/images/*.png filter=lfs diff=lfs merge=lfs -text
-app/src/assets/images/*.png filter=lfs diff=lfs merge=lfs -text
 *.png filter=lfs diff=lfs merge=lfs -text
 *.jpg filter=lfs diff=lfs merge=lfs -text
 *.wav filter=lfs diff=lfs merge=lfs -text

app/.astro/astro/content.d.ts

@@ -0,0 +1,204 @@
+declare module 'astro:content' {
+	interface Render {
+		'.mdx': Promise<{
+			Content: import('astro').MarkdownInstance<{}>['Content'];
+			headings: import('astro').MarkdownHeading[];
+			remarkPluginFrontmatter: Record<string, any>;
+			components: import('astro').MDXInstance<{}>['components'];
+		}>;
+	}
+}
+
+declare module 'astro:content' {
+	interface RenderResult {
+		Content: import('astro/runtime/server/index.js').AstroComponentFactory;
+		headings: import('astro').MarkdownHeading[];
+		remarkPluginFrontmatter: Record<string, any>;
+	}
+	interface Render {
+		'.md': Promise<RenderResult>;
+	}
+
+	export interface RenderedContent {
+		html: string;
+		metadata?: {
+			imagePaths: Array<string>;
+			[key: string]: unknown;
+		};
+	}
+}
+
+declare module 'astro:content' {
+	type Flatten<T> = T extends { [K: string]: infer U } ? U : never;
+
+	export type CollectionKey = keyof AnyEntryMap;
+	export type CollectionEntry<C extends CollectionKey> = Flatten<AnyEntryMap[C]>;
+
+	export type ContentCollectionKey = keyof ContentEntryMap;
+	export type DataCollectionKey = keyof DataEntryMap;
+
+	type AllValuesOf<T> = T extends any ? T[keyof T] : never;
+	type ValidContentEntrySlug<C extends keyof ContentEntryMap> = AllValuesOf<
+		ContentEntryMap[C]
+	>['slug'];
+
+	/** @deprecated Use `getEntry` instead. */
+	export function getEntryBySlug<
+		C extends keyof ContentEntryMap,
+		E extends ValidContentEntrySlug<C> | (string & {}),
+	>(
+		collection: C,
+		// Note that this has to accept a regular string too, for SSR
+		entrySlug: E,
+	): E extends ValidContentEntrySlug<C>
+		? Promise<CollectionEntry<C>>
+		: Promise<CollectionEntry<C> | undefined>;
+
+	/** @deprecated Use `getEntry` instead. */
+	export function getDataEntryById<C extends keyof DataEntryMap, E extends keyof DataEntryMap[C]>(
+		collection: C,
+		entryId: E,
+	): Promise<CollectionEntry<C>>;
+
+	export function getCollection<C extends keyof AnyEntryMap, E extends CollectionEntry<C>>(
+		collection: C,
+		filter?: (entry: CollectionEntry<C>) => entry is E,
+	): Promise<E[]>;
+	export function getCollection<C extends keyof AnyEntryMap>(
+		collection: C,
+		filter?: (entry: CollectionEntry<C>) => unknown,
+	): Promise<CollectionEntry<C>[]>;
+
+	export function getEntry<
+		C extends keyof ContentEntryMap,
+		E extends ValidContentEntrySlug<C> | (string & {}),
+	>(entry: {
+		collection: C;
+		slug: E;
+	}): E extends ValidContentEntrySlug<C>
+		? Promise<CollectionEntry<C>>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof DataEntryMap,
+		E extends keyof DataEntryMap[C] | (string & {}),
+	>(entry: {
+		collection: C;
+		id: E;
+	}): E extends keyof DataEntryMap[C]
+		? Promise<DataEntryMap[C][E]>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof ContentEntryMap,
+		E extends ValidContentEntrySlug<C> | (string & {}),
+	>(
+		collection: C,
+		slug: E,
+	): E extends ValidContentEntrySlug<C>
+		? Promise<CollectionEntry<C>>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof DataEntryMap,
+		E extends keyof DataEntryMap[C] | (string & {}),
+	>(
+		collection: C,
+		id: E,
+	): E extends keyof DataEntryMap[C]
+		? Promise<DataEntryMap[C][E]>
+		: Promise<CollectionEntry<C> | undefined>;
+
+	/** Resolve an array of entry references from the same collection */
+	export function getEntries<C extends keyof ContentEntryMap>(
+		entries: {
+			collection: C;
+			slug: ValidContentEntrySlug<C>;
+		}[],
+	): Promise<CollectionEntry<C>[]>;
+	export function getEntries<C extends keyof DataEntryMap>(
+		entries: {
+			collection: C;
+			id: keyof DataEntryMap[C];
+		}[],
+	): Promise<CollectionEntry<C>[]>;
+
+	export function render<C extends keyof AnyEntryMap>(
+		entry: AnyEntryMap[C][string],
+	): Promise<RenderResult>;
+
+	export function reference<C extends keyof AnyEntryMap>(
+		collection: C,
+	): import('astro/zod').ZodEffects<
+		import('astro/zod').ZodString,
+		C extends keyof ContentEntryMap
+			? {
+					collection: C;
+					slug: ValidContentEntrySlug<C>;
+				}
+			: {
+					collection: C;
+					id: keyof DataEntryMap[C];
+				}
+	>;
+	// Allow generic `string` to avoid excessive type errors in the config
+	// if `dev` is not running to update as you edit.
+	// Invalid collection names will be caught at build time.
+	export function reference<C extends string>(
+		collection: C,
+	): import('astro/zod').ZodEffects<import('astro/zod').ZodString, never>;
+
+	type ReturnTypeOrOriginal<T> = T extends (...args: any[]) => infer R ? R : T;
+	type InferEntrySchema<C extends keyof AnyEntryMap> = import('astro/zod').infer<
+		ReturnTypeOrOriginal<Required<ContentConfig['collections'][C]>['schema']>
+	>;
+
+	type ContentEntryMap = {
+		"chapters": {
+"available-blocks.mdx": {
+	id: "available-blocks.mdx";
+  slug: "available-blocks";
+  body: string;
+  collection: "chapters";
+  data: any
+} & { render(): Render[".mdx"] };
+"best-pratices.mdx": {
+	id: "best-pratices.mdx";
+  slug: "best-pratices";
+  body: string;
+  collection: "chapters";
+  data: any
+} & { render(): Render[".mdx"] };
+"getting-started.mdx": {
+	id: "getting-started.mdx";
+  slug: "getting-started";
+  body: string;
+  collection: "chapters";
+  data: any
+} & { render(): Render[".mdx"] };
+"writing-your-content.mdx": {
+	id: "writing-your-content.mdx";
+  slug: "writing-your-content";
+  body: string;
+  collection: "chapters";
+  data: any
+} & { render(): Render[".mdx"] };
+};
+
+	};
+
+	type DataEntryMap = {
+		"assets": Record<string, {
+  id: string;
+  collection: "assets";
+  data: any;
+}>;
+"embeds": Record<string, {
+  id: string;
+  collection: "embeds";
+  data: any;
+}>;
+
+	};
+
+	type AnyEntryMap = ContentEntryMap & DataEntryMap;
+
+	export type ContentConfig = never;
+}

app/astro.config.mjs

@@ -34,7 +34,25 @@ function rehypeCodeCopyAndLabel() {
           fromClass(preClasses),
         ];
         let lang = candidates.find(Boolean) || '';
-        const displayLang = lang ? String(lang).toUpperCase() : '';
+        const lower = String(lang).toLowerCase();
+        const toExt = (s) => {
+          switch (String(s).toLowerCase()) {
+            case 'typescript': case 'ts': return 'ts';
+            case 'tsx': return 'tsx';
+            case 'javascript': case 'js': case 'node': return 'js';
+            case 'jsx': return 'jsx';
+            case 'python': case 'py': return 'py';
+            case 'bash': case 'shell': case 'sh': return 'sh';
+            case 'markdown': case 'md': return 'md';
+            case 'yaml': case 'yml': return 'yml';
+            case 'html': return 'html';
+            case 'css': return 'css';
+            case 'json': return 'json';
+            default: return lower || '';
+          }
+        };
+        const ext = toExt(lower);
+        const displayLang = ext ? String(ext).toUpperCase() : '';
         // Determine if single-line block: prefer Shiki lines, then text content
         const countLinesFromShiki = () => {
           const isLineEl = (el) => el && el.type === 'element' && el.tagName === 'span' && Array.isArray(el.properties?.className) && el.properties.className.includes('line');
@@ -81,14 +99,16 @@ function rehypeCodeCopyAndLabel() {
             node.__forceSingle = true;
           }
         }
-        // Ensure CSS-only label works: set data-language on the <code> element
+        // Ensure CSS-only label works: set data-language on <code> and <pre>, and wrapper
         code.properties = code.properties || {};
-        if (displayLang) code.properties['data-language'] = displayLang;
+        if (ext) code.properties['data-language'] = ext;
+        node.properties = node.properties || {};
+        if (ext) node.properties['data-language'] = ext;
         // Replace <pre> with wrapper div.code-card containing button + pre
         const wrapper = {
           type: 'element',
           tagName: 'div',
-          properties: { className: ['code-card'].concat((isSingleLine || node.__forceSingle) ? ['no-copy'] : []), 'data-language': displayLang },
+          properties: { className: ['code-card'].concat((isSingleLine || node.__forceSingle) ? ['no-copy'] : []), 'data-language': ext },
           children: (isSingleLine || node.__forceSingle) ? [ node ] : [
             {
               type: 'element',

app/src/components/{FullBleed.astro → FullWidth.astro}

@@ -1,6 +1,6 @@
 ---
 const { class: className, ...props } = Astro.props;
-const wrapperClass = ["full-bleed", className].filter(Boolean).join(" ");
+const wrapperClass = ["full-width", className].filter(Boolean).join(" ");
 ---
 <div class={wrapperClass} {...props}>
   <slot />

app/src/components/Hero.astro

@@ -87,7 +87,7 @@ const pdfFilename = `${slugify(pdfBase)}.pdf`;
 </script>
 
 <style>
-  /* Hero (full-bleed) */
+  /* 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-banner { max-width: 980px; margin: 0 auto; }

app/src/components/HtmlEmbed.astro

@@ -2,14 +2,14 @@
 interface Props { src: string; title?: string; desc?: string; frameless?: boolean }
 const { src, title, desc, frameless = false } = Astro.props as Props;
 
-// Load all .html fragments under src/content/fragments/** as strings (dev & build)
-const fragments = (import.meta as any).glob('../content/fragments/**/*.html', { query: '?raw', import: 'default', eager: true }) as Record<string, string>;
+// Load all .html embeds under src/content/embeds/** as strings (dev & build)
+const embeds = (import.meta as any).glob('../content/embeds/**/*.html', { query: '?raw', import: 'default', eager: true }) as Record<string, string>;
 
 function resolveFragment(requested: string): string | null {
-  // Allow both "banner.html" and "fragments/banner.html"
+  // Allow both "banner.html" and "embeds/banner.html"
   const needle = requested.replace(/^\/*/, '');
-  for (const [key, html] of Object.entries(fragments)) {
-    if (key.endsWith('/' + needle) || key.endsWith('/' + needle.replace(/^fragments\//, ''))) {
+  for (const [key, html] of Object.entries(embeds)) {
+    if (key.endsWith('/' + needle) || key.endsWith('/' + needle.replace(/^embeds\//, ''))) {
       return html;
     }
   }
@@ -58,7 +58,7 @@ const mountId = `frag-${Math.random().toString(36).slice(2)}`;
     });
   };
   // Ensure execution when ready: run now if Plotly or D3 is present, or when document is ready; otherwise wait for 'load'
-  // @ts-expect-error: Plotly/d3 are attached globally at runtime via fragments
+  // @ts-expect-error: Plotly/d3 are attached globally at runtime via embeds
   if (window.Plotly || window.d3 || document.readyState === 'complete') execute();
   else window.addEventListener('load', execute, { once: true });
   </script>

app/src/components/{Aside.astro → Sidenote.astro}

@@ -8,3 +8,5 @@
     <slot name="aside" />
   </aside>
 </div>
+
+

app/src/components/ThemeToggle.astro

@@ -1,6 +1,6 @@
 ---
-import sunIconUrl from "../assets/icones/sun.svg?url";
-import moonIconUrl from "../assets/icones/moon.svg?url";
+import sunIconUrl from "../content/assets/icones/sun.svg?url";
+import moonIconUrl from "../content/assets/icones/moon.svg?url";
 ---
 <button id="theme-toggle" aria-label="Toggle color theme">
   <img class="icon light" src={sunIconUrl} alt="light" width="20" height="20" />

app/src/content/article.mdx

@@ -17,35 +17,35 @@ ogImage: "/thumb.jpg"
 
 import HtmlEmbed from "../components/HtmlEmbed.astro";
 import Wide from "../components/Wide.astro";
-import FullBleed from "../components/FullBleed.astro";
+import FullWidth from "../components/FullWidth.astro";
 import { Image } from 'astro:assets';
-import placeholder from "../assets/images/placeholder.png";
-import audioDemo from "../assets/audio/audio-example.wav";
-import Aside from "../components/Aside.astro";
-import visualPoster from "../assets/images/visual-vocabulary-poster.png";
+import placeholder from "./assets/images/placeholder.png";
+import audioDemo from "./assets/audio/audio-example.wav";
+import Sidenote from "../components/Sidenote.astro";
+import visualPoster from "./assets/images/visual-vocabulary-poster.png";
 
 import BestPractices from "./chapters/best-pratices.mdx";
 import WritingYourContent from "./chapters/writing-your-content.mdx";
 import AvailableBlocks from "./chapters/available-blocks.mdx";  
 import GettingStarted from "./chapters/getting-started.mdx";
 
-<Aside>
-  Welcome to this single-page research article template built with **Markdown**.
+<Sidenote>
+  Welcome to this single-page research article template.
   It’s designed to help you write clear, modern, and **interactive** technical articles with **minimal setup**.
   Whether you cover machine learning, data science, physics, or software topics, this template keeps the authoring flow simple while offering robust features out of the box.
   <Fragment slot="aside">
     Reading time: 20–25 minutes.
   </Fragment>
   In this guide, you’ll learn how to install the template,
-  write content (math, citations, images, code, asides, interactive fragments),
+  write content (math, citations, images, code, sidenotes, interactive fragments),
   customize styles and behavior, and follow a few **best practices** for publishing.
   
-</Aside>
+</Sidenote>
 
 
 #### Features
 
-<Aside>
+<Sidenote>
 <div className="tag-list">
   <span className="tag">Markdown based</span>
   <span className="tag">KaTeX math</span>
@@ -69,7 +69,7 @@ import GettingStarted from "./chapters/getting-started.mdx";
 <Fragment slot="aside">
     If you have questions or remarks open a discussion on the <a href="https://huggingface.co/spaces/tfrere/research-blog-template/discussions?status=open&type=discussion">Community tab</a>!
   </Fragment>
-</Aside>
+</Sidenote>
 
 ## Introduction
 The web enables forms of explanation that static PDFs cannot: **reactive diagrams**, progressive notation, and **exploratory views** that reveal how ideas behave. Use **interactive fragments** to let readers hover, scrub, and inspect—building **intuition**, not just reading results.

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

@@ -1,10 +1,10 @@
 import { Image } from 'astro:assets';
-import placeholder from '../../assets/images/placeholder.png';
-import audioDemo from '../../assets/audio/audio-example.wav';
+import placeholder from '../assets/images/placeholder.png';
+import audioDemo from '../assets/audio/audio-example.wav';
 import HtmlEmbed from '../../components/HtmlEmbed.astro';
-import Aside from '../../components/Aside.astro';
+import Sidenote from '../../components/Sidenote.astro';
 import Wide from '../../components/Wide.astro';
-import FullBleed from '../../components/FullBleed.astro';
+import FullWidth from '../../components/FullWidth.astro';
 import Accordion from '../../components/Accordion.astro';
 
 ## Available blocks
@@ -58,11 +58,14 @@ $$
 
 Props (optional)
 - `data-zoomable`: adds a zoomable lightbox.
+- `data-downloadable`: adds a small download button to fetch the image file.
 - `loading="lazy"`: lazy loads the image.
 - `figcaption`: adds a caption and credit.
 
 **Optional:** Zoomable (Medium-like lightbox): add `data-zoomable` to opt-in. Only images with this attribute will open full-screen on click.
 
+**Optional:** Download button: add `data-downloadable` to render a small button in the bottom-right corner that downloads the image. By default it tries to use the original filename; you can override via `data-download-name="myfile.png"` and `data-download-src="/path/to/original.png"`.
+
 **Optional:** Lazy loading: add `loading="lazy"` to opt-in.
 
 **Optional:** Figcaption and credits: add a `figcaption` element with a `span` containing the credit.
@@ -73,6 +76,8 @@ Props (optional)
   <Image
     src={placeholder}
     data-zoomable
+    data-downloadable
+    layout="fixed"
     alt="Tensor parallelism in a transformer block"
   />
   <figcaption>
@@ -84,12 +89,12 @@ Props (optional)
 <small className="muted">Example</small>
 ```mdx
 import { Image } from 'astro:assets'
-import myImage from '../assets/images/placeholder.jpg'
+import myImage from './assets/images/placeholder.jpg'
 
 <Image src={myImage} alt="Responsive, optimized example image" />
 
 <figure>
-  <Image src={myImage} data-zoomable alt="Example with caption and credit" loading="lazy" />
+  <Image src={myImage} layout="fixed" data-zoomable data-downloadable alt="Example with caption and credit" loading="lazy" />
   <figcaption>
     Optimized image with a descriptive caption.
     <span className="image-credit">Credit: Photo by <a href="https://example.com">Author</a></span>
@@ -299,7 +304,7 @@ greet("Astro");
 <br/>
 <small className="muted">Example</small>
 ```mdx
-import audioDemo from '../assets/audio/audio-example.wav'
+import audioDemo from './assets/audio/audio-example.wav'
 
 <audio controls src={audioDemo}/>
 ```

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

@@ -1,6 +1,6 @@
 
 import { Image } from 'astro:assets';
-import visualPoster from '../../assets/images/visual-vocabulary-poster.png';
+import visualPoster from '../assets/images/visual-vocabulary-poster.png';
 import Note from '../../components/Note.astro';
 
 
@@ -39,7 +39,7 @@ Favor **concise captions** and callouts that clarify what to look at and why it
 {/* ### Use the right color
 A palette encodes **meaning** (categories, magnitudes, oppositions), preserves **readability** and **accessibility** (sufficient contrast, color‑vision safety), and ensures **perceptually smooth transitions**. The three families below illustrate when to use **categorical**, **sequential**, or **diverging** colors and how they evolve from the same **reference hue**.
 
-<Aside>
+<Sidenote>
 <div className="">
   <HtmlEmbed src="palettes.html" />
 </div>
@@ -49,7 +49,7 @@ A palette encodes **meaning** (categories, magnitudes, oppositions), preserves *
 <Fragment slot="aside">
   It will be applied to the <a href="/" target="_blank">whole page</a>.
 </Fragment>
-</Aside> */}
+</Sidenote> */}
 
 ### Use the right chart
 

app/src/content/chapters/getting-started.mdx

@@ -1,10 +1,10 @@
-import Aside from '../../components/Aside.astro';
+import Sidenote from '../../components/Sidenote.astro';
 
 ## Getting Started
 
 ### Installation
 
-<Aside>
+<Sidenote>
 ```bash
 git lfs install
 git lfs pull
@@ -14,7 +14,7 @@ npm install
 <Fragment slot="aside">
     You can also use yarn.
   </Fragment>
-</Aside>
+</Sidenote>
 
 
 ### Development

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

@@ -1,11 +1,11 @@
 {/* IMPORTS */}
 import { Image } from 'astro:assets';
-import placeholder from '../../assets/images/placeholder.png';
-import Aside from '../../components/Aside.astro';
+import placeholder from '../assets/images/placeholder.png';
+import Sidenote from '../../components/Sidenote.astro';
 import Wide from '../../components/Wide.astro';
-import FullBleed from '../../components/FullBleed.astro';
+import FullWidth from '../../components/FullWidth.astro';
 import HtmlEmbed from '../../components/HtmlEmbed.astro';
-import audioDemo from '../../assets/audio/audio-example.wav';
+import audioDemo from '../assets/audio/audio-example.wav';
 
 ## Writing Your Content
 
@@ -14,7 +14,7 @@ import audioDemo from '../../assets/audio/audio-example.wav';
 Your article lives in two places
 
 - `app/src/content/` — where you can find the `article.mdx`, `bibliography.bib` and html fragments.
-- `app/src/assets/` — images, audio, and other static assets. (handled by git lfs)
+- `app/src/content/assets/` — images, audio, and other static assets. (handled by git lfs)
 
 The `article.mdx` file is the main file that contains your article.
 
@@ -39,7 +39,7 @@ ogImage: "https://example.com/your-og-image.png"
 
 {/* IMPORTS */}
 import { Image } from 'astro:assets';
-import placeholder from '../assets/images/placeholder.jpg';
+import placeholder from './assets/images/placeholder.jpg';
 
 {/* CONTENT */}
 # Hello, world
@@ -57,14 +57,14 @@ MDX is a mix of Markdown and HTML/JSX: write regular Markdown, and embed interac
 ```mdx
 {/* IMPORTS */}
 import { Image } from 'astro:assets'
-import placeholder from '../assets/images/placeholder.png'
-import Aside from '../components/Aside.astro'
+import placeholder from './assets/images/placeholder.png'
+import Sidenote from '../components/Sidenote.astro'
 
 # Mixing Markdown and components
 
 This paragraph is written in Markdown. 
 
-<Aside>A short callout inserted via a component.</Aside>
+<Sidenote>A short callout inserted via a component.</Sidenote>
 
 Below is an image imported via Astro and optimized at build time:
 
@@ -105,14 +105,14 @@ Use the **color picker** below to see how the primary color affects the theme.
 
 #### Brand color
 
-<Aside>
+<Sidenote>
   <HtmlEmbed frameless src="color-picker.html" />
   <Fragment slot="aside">
     You can use the color picker to select the right color.
     
     Here is an example of an <a href="#">interactive element</a>.
   </Fragment>
-</Aside>
+</Sidenote>
 
 
 #### Color palettes
@@ -124,25 +124,25 @@ Here is a suggestion of **color palettes** for your **data visualizations** that
 
 ### Placement
 
-Use these helpers when you need to step outside the main content flow: **Asides** for contextual side notes, **Wide** to extend beyond the main column, and **Full-bleed** for full-width, immersive sections.
+Use these helpers when you need to step outside the main content flow: **Sidenotes** for contextual side notes, **Wide** to extend beyond the main column, and **Full-width** for full-width, immersive sections.
 
-#### Asides
+#### Sidenotes
 
-<Aside>
+<Sidenote>
   This paragraph presents a **key idea** concisely.
   <Fragment slot="aside">
     **Side note** for brief context or a definition.
   </Fragment>
-  </Aside>
+  </Sidenote>
 
 <small className="muted">Example</small>
 ```mdx
-import Aside from '../components/Aside.astro'
+import Sidenote from '../components/Sidenote.astro'
 
-<Aside>
+<Sidenote>
   Main paragraph with the core idea.
   <Fragment slot="aside">Short side note.</Fragment>
-</Aside>
+</Sidenote>
 ```
 
 Use these helpers to expand content beyond the main column when needed. They will always be centered and displayed above every other content.
@@ -162,17 +162,17 @@ import Wide from '../components/Wide.astro'
 </Wide>
 ```
 
-#### Full-bleed example
+#### Full-width example
 
-<FullBleed>
-  <div className="demo-full-bleed">demo full-bleed</div>
-</FullBleed>
+<FullWidth>
+  <div className="demo-full-width">demo full-width</div>
+</FullWidth>
 
 <small className="muted">Example</small>
 ```mdx
-import FullBleed from '../components/FullBleed.astro'
+import FullWidth from '../components/FullWidth.astro'
 
-<FullBleed>
+<FullWidth>
   Your content here...
-</FullBleed>
+</FullWidth>
 ```

app/src/pages/index.astro

@@ -5,7 +5,7 @@ import Footer from '../components/Footer.astro';
 import ThemeToggle from '../components/ThemeToggle.astro';
 import Seo from '../components/Seo.astro';
 // @ts-ignore Astro asset import typed via env.d.ts
-import ogDefaultUrl from '../assets/images/visual-vocabulary-poster.png?url';
+import ogDefaultUrl from '../content/assets/images/visual-vocabulary-poster.png?url';
 import 'katex/dist/katex.min.css';
 import '../styles/global.css';
 const articleFM = (ArticleMod as any).frontmatter ?? {};
@@ -178,6 +178,105 @@ const bibtex = `@misc{${bibKey},\n  title={${titleFlat}},\n  author={${authorsBi
     </script>
     
 
+    <script>
+      // Add a small download button to img[data-downloadable]
+      (() => {
+        const SELECTOR = 'section.content-grid main img[data-downloadable]';
+
+        /**
+         * @param {HTMLImageElement} img
+         */
+        const injectDownloadButton = (img) => {
+          if (!img || img.dataset.__dlInjected) return;
+          const parentFigure = img.closest('figure');
+          const parent = img.parentElement;
+          if (!parent) return;
+          img.dataset.__dlInjected = '1';
+
+          // Wrap the image in a positioned inline-block so the button is on the image
+          const wrapper = document.createElement('span');
+          wrapper.className = 'img-dl-wrap';
+          parent.insertBefore(wrapper, img);
+          wrapper.appendChild(img);
+          if (parentFigure && !parentFigure.classList.contains('has-dl-btn')) {
+            parentFigure.classList.add('has-dl-btn');
+          }
+
+          // Determine download href and filename
+          const pickHrefAndName = () => {
+            const current = img.currentSrc || img.src || '';
+            let href = img.getAttribute('data-download-src') || current;
+            // Derive filename from the original source when possible
+            const deriveName = () => {
+              try {
+                const u = new URL(current, location.href);
+                // Prefer original href param if provided by Astro image service
+                const rawHref = u.searchParams.get('href');
+                const candidate = rawHref ? decodeURIComponent(rawHref) : u.pathname;
+                const last = String(candidate).split('/').pop() || '';
+                // Strip query/hash and any appended transform suffixes after extension
+                const base = last.split('?')[0].split('#')[0];
+                const m = base.match(/^(.+?\.(?:png|jpe?g|webp|avif|gif|svg))(?:[._-].*)?$/i);
+                if (m && m[1]) return m[1];
+                // If extension missing, fallback to base as-is
+                return base || 'image';
+              } catch {
+                return 'image';
+              }
+            };
+            const name = img.getAttribute('data-download-name') || deriveName();
+            return { href, name };
+          };
+
+          const { href, name } = pickHrefAndName();
+          const a = document.createElement('a');
+          a.className = 'button button--ghost img-dl-btn';
+          a.href = href;
+          if (name) a.download = name;
+          a.setAttribute('aria-label', 'Download image');
+          a.setAttribute('title', name ? `Download ${name}` : 'Download image');
+          a.innerHTML = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M12 16c-.26 0-.52-.11-.71-.29l-5-5a1 1 0 0 1 1.42-1.42L11 12.59V4a1 1 0 1 1 2 0v8.59l3.29-3.3a1 1 0 1 1 1.42 1.42l-5 5c-.19.18-.45.29-.71.29zM5 20a1 1 0 1 1 0-2h14a1 1 0 1 1 0 2H5z"/></svg>';
+
+          // Ensure href/name match currentSrc right before navigation
+          a.addEventListener('click', async (ev) => {
+            try {
+              ev.preventDefault();
+              const picked = pickHrefAndName();
+              const res = await fetch(picked.href, { credentials: 'same-origin' });
+              const blob = await res.blob();
+              const objectUrl = URL.createObjectURL(blob);
+              const tmp = document.createElement('a');
+              tmp.href = objectUrl;
+              tmp.download = picked.name || 'image';
+              document.body.appendChild(tmp);
+              tmp.click();
+              setTimeout(() => { URL.revokeObjectURL(objectUrl); tmp.remove(); }, 1000);
+            } catch {
+              // Fallback to native behavior if fetch fails
+            }
+          });
+
+          // Append inside wrapper so positioning is relative to the image box
+          wrapper.appendChild(a);
+        };
+
+        const scan = () => {
+          document.querySelectorAll(SELECTOR).forEach((el) => injectDownloadButton(el));
+        };
+
+        const bootstrap = () => {
+          scan();
+          const main = document.querySelector('section.content-grid main');
+          if (!main) return;
+          const mo = new MutationObserver(() => scan());
+          mo.observe(main, { childList: true, subtree: true, attributes: true, attributeFilter: ['src'] });
+        };
+
+        if (document.readyState === 'complete') bootstrap();
+        else window.addEventListener('load', bootstrap, { once: true });
+      })();
+    </script>
+
     <script>
       // Open external links in a new tab; keep internal anchors in-page
       const setExternalTargets = () => {

app/src/styles/_base.css

@@ -81,7 +81,7 @@ html { font-size: 14px; line-height: 1.6; }
 
 /* Demo blocks for width helpers */
 .demo-wide,
-.demo-full-bleed {
+.demo-full-width {
   display: grid;
   place-items: center;
   min-height: 150px;
@@ -118,6 +118,8 @@ picture {
   max-width: 100%;
   height: auto;
   display: block;
+  position: relative;
+  z-index: var(--z-elevated);
 }
 
 /* Inline feature tags */
@@ -146,6 +148,17 @@ figcaption { text-align: left; font-size: 0.9rem; color: var(--muted-color); mar
 .image-credit { display: block; margin-top: 4px; font-size: 12px; color: var(--muted-color); }
 .image-credit a { color: inherit; text-decoration: underline; text-underline-offset: 2px; }
 
+/* Zoomable overlay container (if used by any lightbox implementation) */
+[data-zoom-overlay],
+.zoom-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-overlay);
+}
+
+/* Download link inside figures */
+figure .download-link { position: relative; z-index: var(--z-elevated); }
+
 /* ============================================================================ */
 /* Buttons (minimal, clean) */
 /* ============================================================================ */
@@ -248,7 +261,7 @@ button:disabled, .button:disabled {
   table,
   blockquote,
   .wide,
-  .full-bleed {
+  .full-width {
     break-inside: avoid;
     page-break-inside: avoid;
   }

app/src/styles/_layout.css

@@ -1,7 +1,11 @@
 /* ============================================================================ */
 /* Layout – 3-column grid (TOC / Article / Aside) */
 /* ============================================================================ */
-.content-grid { max-width: 1280px; margin: 0 auto; padding: 0 16px; margin-top: 40px; display: grid; grid-template-columns: 220px minmax(0, 680px) 260px; gap: 32px; align-items: start; }
+:root {
+  --content-padding-x: 16px;
+}
+
+.content-grid { max-width: 1280px; margin: 0 auto; padding: 0 var(--content-padding-x); margin-top: 40px; display: grid; grid-template-columns: 220px minmax(0, 680px) 260px; gap: 32px; align-items: start; }
 .content-grid > main { max-width: 100%; margin: 0; padding: 0; }
 
 /* TOC (left column) */
@@ -69,11 +73,11 @@ main > nav:first-of-type { display: none; }
 
 
 /* ============================================================================ */
-/* Width helpers – slightly wider than main column, and full-bleed to viewport */
+/* Width helpers – slightly wider than main column, and full-width to viewport */
 /* ---------------------------------------------------------------------------- */
 /* Usage in MDX: */
 /* <div className="wide"> ... </div> */
-/* <div className="full-bleed"> ... </div> */
+/* <div className="full-width"> ... </div> */
 /* These center the content relative to the viewport while keeping it responsive. */
 /* */
 /* Notes: */
@@ -81,7 +85,7 @@ main > nav:first-of-type { display: none; }
 /*   to be wider or fully span the viewport. On small screens, they fall back to 100%. */
 /* - Adjust the target width in .wide if desired. */
 .wide,
-.full-bleed { box-sizing: border-box; }
+.full-width { box-sizing: border-box; position: relative; z-index: var(--z-elevated); }
 
 .wide {
   /* Target up to ~1100px while staying within viewport minus page gutters */
@@ -90,18 +94,19 @@ main > nav:first-of-type { display: none; }
   transform: translateX(-50%);
 }
 
-.full-bleed {
-  /* Span the full viewport width */
+.full-width {
+  /* Span the full viewport width and center relative to viewport */
   width: 100vw;
-  margin-left: 50%;
-  transform: translateX(-50%);
+  margin-left: calc(50% - 50vw + var(--content-padding-x) * 2);
+  margin-right: calc(50% - 50vw);
 }
 
 @media (max-width: 1100px) {
   .wide,
-  .full-bleed {
+  .full-width {
     width: 100%;
     margin-left: 0;
+    margin-right: 0;
     transform: none;
   }
 }

app/src/styles/_variables.css

@@ -33,6 +33,14 @@
   --spacing-8: 56px;
   --spacing-9: 64px;
   --spacing-10: 72px;
+
+  /* Z-index scale */
+  --z-base: 0;           /* background/base */
+  --z-content: 1;        /* regular content */
+  --z-elevated: 10;      /* wide/full-width blocks, images */
+  --z-overlay: 1000;     /* overlays/lightboxes */
+  --z-modal: 1100;       /* modals/dialogs */
+  --z-tooltip: 1200;     /* tooltips/popovers */
 }
 /* Theme tokens for dark mode */
 [data-theme="dark"] {

app/src/styles/components/_code.css

@@ -13,6 +13,7 @@ code {
 /* Sync Shiki variables with current theme */
 /* Standard wrapper look for code blocks */
 .astro-code { border: 1px solid var(--border-color); border-radius: 6px; padding: 0; font-size: 14px; --code-gutter-width: 2.5em; }
+.astro-code { position: relative; }
 
 /* Prevent code blocks from breaking layout on small screens */
 .astro-code { overflow-x: auto; width: 100%; max-width: 100%; box-sizing: border-box; -webkit-overflow-scrolling: touch; }
@@ -81,3 +82,45 @@ html[data-theme='light'] .astro-code {
 
 /* Overrides inside Accordion: remove padding and border on code containers */
 .accordion .astro-code { padding: 0; border: none; }
+
+/* Language/extension vignette for Shiki blocks (bottom-right, discreet) */
+.astro-code::after {
+  content: attr(data-language);
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  font-size: 10px;
+  line-height: 1;
+  text-transform: uppercase;
+  color: var(--muted-color);
+  background: var(--surface-bg);
+  border-top: 1px solid var(--border-color);
+  border-left: 1px solid var(--border-color);
+  opacity: 0.5;
+  border-radius: 8px 0 0 0; /* round only top-left */
+  padding: 4px 6px;
+  pointer-events: none;
+}
+
+/* Fallback if Shiki uses data-lang instead of data-language */
+.astro-code[data-lang]::after { content: attr(data-lang); }
+
+/* Normalize to extensions for common languages */
+.astro-code[data-language="typescript"]::after { content: "ts"; }
+.astro-code[data-language="tsx"]::after { content: "tsx"; }
+.astro-code[data-language="javascript"]::after,
+.astro-code[data-language="node"]::after,
+.astro-code[data-language="jsx"]::after { content: "js"; }
+.astro-code[data-language="python"]::after { content: "py"; }
+.astro-code[data-language="bash"]::after,
+.astro-code[data-language="shell"]::after,
+.astro-code[data-language="sh"]::after { content: "sh"; }
+.astro-code[data-language="markdown"]::after { content: "md"; }
+.astro-code[data-language="yaml"]::after,
+.astro-code[data-language="yml"]::after { content: "yml"; }
+.astro-code[data-language="html"]::after { content: "html"; }
+.astro-code[data-language="css"]::after { content: "css"; }
+.astro-code[data-language="json"]::after { content: "json"; }
+
+/* In Accordions, keep same bottom-right placement */
+.accordion .astro-code::after { right: 0; bottom: 0; }

app/src/styles/global.css

@@ -20,6 +20,30 @@
 img[data-zoomable] { cursor: zoom-in; }
 .medium-zoom--opened img[data-zoomable] { cursor: zoom-out; }
 
+/* Download button for img[data-downloadable] */
+figure.has-dl-btn { position: relative; }
+.dl-host { position: relative; }
+.img-dl-wrap { position: relative; display: inline-block; }
+.img-dl-btn {
+  position: absolute;
+  right: 8px;
+  bottom: 8px;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  border-radius: 6px;
+  color: white;
+  text-decoration: none;
+  border: 1px solid rgba(255,255,255,0.25);
+  z-index: var(--z-elevated);
+  display: none;
+}
+.img-dl-btn svg { width: 18px; height: 18px; fill: currentColor; }
+.img-dl-wrap:hover .img-dl-btn { display: inline-flex; }
+[data-theme="dark"] .img-dl-btn { background: rgba(255,255,255,0.15); color: white; border-color: rgba(255,255,255,0.25); }
+[data-theme="dark"] .img-dl-btn:hover { background: rgba(255,255,255,0.25); }
+
 /* ============================================================================ */
 /* Theme Toggle button (moved from component) */
 /* ============================================================================ */