big refactor

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

@@ -152,16 +152,23 @@ declare module 'astro:content' {
 
 	type ContentEntryMap = {
 		"chapters": {
-"available-blocks.mdx": {
-	id: "available-blocks.mdx";
-  slug: "available-blocks";
+"best-pratices.mdx": {
+	id: "best-pratices.mdx";
+  slug: "best-pratices";
   body: string;
   collection: "chapters";
   data: any
 } & { render(): Render[".mdx"] };
-"best-pratices.mdx": {
-	id: "best-pratices.mdx";
-  slug: "best-pratices";
+"components.mdx": {
+	id: "components.mdx";
+  slug: "components";
+  body: string;
+  collection: "chapters";
+  data: any
+} & { render(): Render[".mdx"] };
+"debug-components.mdx": {
+	id: "debug-components.mdx";
+  slug: "debug-components";
   body: string;
   collection: "chapters";
   data: any
@@ -180,6 +187,13 @@ declare module 'astro:content' {
   collection: "chapters";
   data: any
 } & { render(): Render[".mdx"] };
+"markdown.mdx": {
+	id: "markdown.mdx";
+  slug: "markdown";
+  body: string;
+  collection: "chapters";
+  data: any
+} & { render(): Render[".mdx"] };
 "writing-your-content.mdx": {
 	id: "writing-your-content.mdx";
   slug: "writing-your-content";

app/astro.config.mjs

@@ -8,137 +8,14 @@ import remarkFootnotes from 'remark-footnotes';
 import rehypeSlug from 'rehype-slug';
 import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import rehypeCitation from 'rehype-citation';
+import rehypeCodeCopyAndLabel from './plugins/rehype/code-copy-and-label.mjs';
+import rehypeReferencesAndFootnotes from './plugins/rehype/post-citation.mjs';
+import remarkIgnoreCitationsInCode from './plugins/remark/ignore-citations-in-code.mjs';
+import rehypeRestoreAtInCode from './plugins/rehype/restore-at-in-code.mjs';
+import rehypeWrapTables from './plugins/rehype/wrap-tables.mjs';
 // Built-in Shiki (dual themes) — no rehype-pretty-code
 
-// Minimal rehype plugin to wrap code blocks with a copy button and a language label
-function rehypeCodeCopyAndLabel() {
-  return (tree) => {
-    // Walk the tree; lightweight visitor to find <pre><code>
-    const visit = (node, parent) => {
-      if (!node || typeof node !== 'object') return;
-      const children = Array.isArray(node.children) ? node.children : [];
-      if (node.tagName === 'pre' && children.some(c => c.tagName === 'code')) {
-        // Find code child and guess language
-        const code = children.find(c => c.tagName === 'code');
-        const collectClasses = (val) => Array.isArray(val) ? val.map(String) : (typeof val === 'string' ? String(val).split(/\s+/) : []);
-        const fromClass = (names) => {
-          const hit = names.find((n) => /^language-/.test(String(n)));
-          return hit ? String(hit).replace(/^language-/, '') : '';
-        };
-        const codeClasses = collectClasses(code?.properties?.className);
-        const preClasses = collectClasses(node?.properties?.className);
-        const candidates = [
-          code?.properties?.['data-language'],
-          fromClass(codeClasses),
-          node?.properties?.['data-language'],
-          fromClass(preClasses),
-        ];
-        let lang = candidates.find(Boolean) || '';
-        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');
-          const hasNonWhitespaceText = (node) => {
-            if (!node) return false;
-            if (node.type === 'text') return /\S/.test(String(node.value || ''));
-            const kids = Array.isArray(node.children) ? node.children : [];
-            return kids.some(hasNonWhitespaceText);
-          };
-          const collectLines = (node, acc) => {
-            if (!node || typeof node !== 'object') return;
-            if (isLineEl(node)) acc.push(node);
-            const kids = Array.isArray(node.children) ? node.children : [];
-            kids.forEach((k) => collectLines(k, acc));
-          };
-          const lines = [];
-          collectLines(code, lines);
-          const nonEmpty = lines.filter((ln) => hasNonWhitespaceText(ln)).length;
-          return nonEmpty || 0;
-        };
-        const countLinesFromText = () => {
-          // Parse raw text content of the <code> node including nested spans
-          const extractText = (node) => {
-            if (!node) return '';
-            if (node.type === 'text') return String(node.value || '');
-            const kids = Array.isArray(node.children) ? node.children : [];
-            return kids.map(extractText).join('');
-          };
-          const raw = extractText(code);
-          if (!raw || !/\S/.test(raw)) return 0;
-          return raw.split('\n').filter(line => /\S/.test(line)).length;
-        };
-        const lines = countLinesFromShiki() || countLinesFromText();
-        const isSingleLine = lines <= 1;
-        // Also treat code blocks shorter than a threshold as single-line (defensive)
-        if (!isSingleLine) {
-          const approxChars = (() => {
-            const extract = (n) => Array.isArray(n?.children) ? n.children.map(extract).join('') : (n?.type === 'text' ? String(n.value||'') : '');
-            return extract(code).length;
-          })();
-          if (approxChars < 6) {
-            // e.g., "npm i" alone
-            // downgrade to single-line behavior
-            node.__forceSingle = true;
-          }
-        }
-        // Ensure CSS-only label works: set data-language on <code> and <pre>, and wrapper
-        code.properties = code.properties || {};
-        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': ext },
-          children: (isSingleLine || node.__forceSingle) ? [ node ] : [
-            {
-              type: 'element',
-              tagName: 'button',
-              properties: { className: ['code-copy', 'button--ghost'], type: 'button', 'aria-label': 'Copy code' },
-              children: [
-                {
-                  type: 'element',
-                  tagName: 'svg',
-                  properties: { viewBox: '0 0 24 24', 'aria-hidden': 'true', focusable: 'false' },
-                  children: [
-                    { type: 'element', tagName: 'path', properties: { d: 'M16 1H4c-1.1 0-2 .9-2 2v12h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z' }, children: [] }
-                  ]
-                }
-              ]
-            },
-            node
-          ]
-        };
-        if (parent && Array.isArray(parent.children)) {
-          const idx = parent.children.indexOf(node);
-          if (idx !== -1) parent.children[idx] = wrapper;
-        }
-        return; // don't visit nested
-      }
-      children.forEach((c) => visit(c, node));
-    };
-    visit(tree, null);
-  };
-}
+// Plugins moved to app/plugins/*
 
 export default defineConfig({
   output: 'static',
@@ -151,15 +28,6 @@ export default defineConfig({
   devToolbar: {
     enabled: false
   },
-  // Expose a public flag to control TOC auto-collapse behavior at runtime
-  // This can be overridden via environment variable PUBLIC_TOC_AUTO_COLLAPSE
-  // (Vite define provides a default fallback when env is not set.)
-  vite: {
-    define: {
-      'import.meta.env.PUBLIC_TOC_AUTO_COLLAPSE': JSON.stringify(false),
-      'import.meta.env.PUBLIC_TABLE_OF_CONTENT_AUTO_COLLAPSE': JSON.stringify(false)
-    }
-  },
   markdown: {
     shikiConfig: {
       themes: {
@@ -174,6 +42,7 @@ export default defineConfig({
       }
     },
     remarkPlugins: [
+      remarkIgnoreCitationsInCode,
       remarkMath,
       [remarkFootnotes, { inlineNotes: true }]
     ],
@@ -185,7 +54,10 @@ export default defineConfig({
         bibliography: 'src/content/bibliography.bib',
         linkCitations: true
       }],
-      rehypeCodeCopyAndLabel
+      rehypeReferencesAndFootnotes,
+      rehypeRestoreAtInCode,
+      rehypeCodeCopyAndLabel,
+      rehypeWrapTables
     ]
   }
 });

app/plugins/rehype/code-copy-and-label.mjs

@@ -0,0 +1,129 @@
+// Minimal rehype plugin to wrap code blocks with a copy button and a language label
+// Exported as a standalone module to keep astro.config.mjs lean
+export default function rehypeCodeCopyAndLabel() {
+  return (tree) => {
+    // Walk the tree; lightweight visitor to find <pre><code>
+    const visit = (node, parent) => {
+      if (!node || typeof node !== 'object') return;
+      const children = Array.isArray(node.children) ? node.children : [];
+      if (node.tagName === 'pre' && children.some(c => c.tagName === 'code')) {
+        // Find code child and guess language
+        const code = children.find(c => c.tagName === 'code');
+        const collectClasses = (val) => Array.isArray(val) ? val.map(String) : (typeof val === 'string' ? String(val).split(/\s+/) : []);
+        const fromClass = (names) => {
+          const hit = names.find((n) => /^language-/.test(String(n)));
+          return hit ? String(hit).replace(/^language-/, '') : '';
+        };
+        const codeClasses = collectClasses(code?.properties?.className);
+        const preClasses = collectClasses(node?.properties?.className);
+        const candidates = [
+          code?.properties?.['data-language'],
+          fromClass(codeClasses),
+          node?.properties?.['data-language'],
+          fromClass(preClasses),
+        ];
+        let lang = candidates.find(Boolean) || '';
+        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);
+        // 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');
+          const hasNonWhitespaceText = (node) => {
+            if (!node) return false;
+            if (node.type === 'text') return /\S/.test(String(node.value || ''));
+            const kids = Array.isArray(node.children) ? node.children : [];
+            return kids.some(hasNonWhitespaceText);
+          };
+          const collectLines = (node, acc) => {
+            if (!node || typeof node !== 'object') return;
+            if (isLineEl(node)) acc.push(node);
+            const kids = Array.isArray(node.children) ? node.children : [];
+            kids.forEach((k) => collectLines(k, acc));
+          };
+          const lines = [];
+          collectLines(code, lines);
+          const nonEmpty = lines.filter((ln) => hasNonWhitespaceText(ln)).length;
+          return nonEmpty || 0;
+        };
+        const countLinesFromText = () => {
+          // Parse raw text content of the <code> node including nested spans
+          const extractText = (node) => {
+            if (!node) return '';
+            if (node.type === 'text') return String(node.value || '');
+            const kids = Array.isArray(node.children) ? node.children : [];
+            return kids.map(extractText).join('');
+          };
+          const raw = extractText(code);
+          if (!raw || !/\S/.test(raw)) return 0;
+          return raw.split('\n').filter(line => /\S/.test(line)).length;
+        };
+        const lines = countLinesFromShiki() || countLinesFromText();
+        const isSingleLine = lines <= 1;
+        // Also treat code blocks shorter than a threshold as single-line (defensive)
+        if (!isSingleLine) {
+          const approxChars = (() => {
+            const extract = (n) => Array.isArray(n?.children) ? n.children.map(extract).join('') : (n?.type === 'text' ? String(n.value||'') : '');
+            return extract(code).length;
+          })();
+          if (approxChars < 6) {
+            node.__forceSingle = true;
+          }
+        }
+        // Ensure CSS-only label works: set data-language on <code> and <pre>, and wrapper
+        code.properties = code.properties || {};
+        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': ext },
+          children: (isSingleLine || node.__forceSingle) ? [ node ] : [
+            {
+              type: 'element',
+              tagName: 'button',
+              properties: { className: ['code-copy', 'button--ghost'], type: 'button', 'aria-label': 'Copy code' },
+              children: [
+                {
+                  type: 'element',
+                  tagName: 'svg',
+                  properties: { viewBox: '0 0 24 24', 'aria-hidden': 'true', focusable: 'false' },
+                  children: [
+                    { type: 'element', tagName: 'path', properties: { d: 'M16 1H4c-1.1 0-2 .9-2 2v12h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z' }, children: [] }
+                  ]
+                }
+              ]
+            },
+            node
+          ]
+        };
+        if (parent && Array.isArray(parent.children)) {
+          const idx = parent.children.indexOf(node);
+          if (idx !== -1) parent.children[idx] = wrapper;
+        }
+        return; // don't visit nested
+      }
+      children.forEach((c) => visit(c, node));
+    };
+    visit(tree, null);
+  };
+}
+
+

app/plugins/rehype/post-citation.mjs

@@ -0,0 +1,441 @@
+// rehype plugin to post-process citations and footnotes at build-time
+// - Normalizes the bibliography into <ol class="references"> with <li id="...">
+// - Linkifies DOI/URL occurrences inside references
+// - Appends back-reference links (↩ back: 1, 2, ...) from each reference to in-text citation anchors
+// - Cleans up footnotes block (.footnotes)
+
+export default function rehypeReferencesAndFootnotes() {
+  return (tree) => {
+    const isElement = (n) => n && typeof n === 'object' && n.type === 'element';
+    const getChildren = (n) => (Array.isArray(n?.children) ? n.children : []);
+
+    const walk = (node, parent, fn) => {
+      if (!node || typeof node !== 'object') return;
+      fn && fn(node, parent);
+      const kids = getChildren(node);
+      for (const child of kids) walk(child, node, fn);
+    };
+
+    const ensureArray = (v) => (Array.isArray(v) ? v : v != null ? [v] : []);
+
+    const hasClass = (el, name) => {
+      const cn = ensureArray(el?.properties?.className).map(String);
+      return cn.includes(name);
+    };
+
+    const setAttr = (el, key, val) => {
+      el.properties = el.properties || {};
+      if (val == null) delete el.properties[key];
+      else el.properties[key] = val;
+    };
+
+    const getAttr = (el, key) => (el?.properties ? el.properties[key] : undefined);
+
+    // Shared helpers for backlinks + backrefs block
+    const collectBacklinksForIdSet = (idSet, anchorPrefix) => {
+      const idToBacklinks = new Map();
+      const idToAnchorNodes = new Map();
+      if (!idSet || idSet.size === 0) return { idToBacklinks, idToAnchorNodes };
+      walk(tree, null, (node) => {
+        if (!isElement(node) || node.tagName !== 'a') return;
+        const href = String(getAttr(node, 'href') || '');
+        if (!href.startsWith('#')) return;
+        const id = href.slice(1);
+        if (!idSet.has(id)) return;
+        // Ensure a stable id
+        let anchorId = String(getAttr(node, 'id') || '');
+        if (!anchorId) {
+          const list = idToBacklinks.get(id) || [];
+          anchorId = `${anchorPrefix}-${id}-${list.length + 1}`;
+          setAttr(node, 'id', anchorId);
+        }
+        const list = idToBacklinks.get(id) || [];
+        list.push(anchorId);
+        idToBacklinks.set(id, list);
+        const nodes = idToAnchorNodes.get(id) || [];
+        nodes.push(node);
+        idToAnchorNodes.set(id, nodes);
+      });
+      return { idToBacklinks, idToAnchorNodes };
+    };
+
+    const createBackIcon = () => ({
+      type: 'element',
+      tagName: 'svg',
+      properties: {
+        className: ['back-icon'],
+        width: 12,
+        height: 12,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+        stroke: 'currentColor',
+        'stroke-width': 2,
+        'stroke-linecap': 'round',
+        'stroke-linejoin': 'round',
+        'aria-hidden': 'true',
+        focusable: 'false'
+      },
+      children: [
+        { type: 'element', tagName: 'line', properties: { x1: 12, y1: 19, x2: 12, y2: 5 }, children: [] },
+        { type: 'element', tagName: 'polyline', properties: { points: '5 12 12 5 19 12' }, children: [] }
+      ]
+    });
+
+    const appendBackrefsBlock = (listElement, idToBacklinks, ariaLabel) => {
+      if (!listElement || !idToBacklinks || idToBacklinks.size === 0) return;
+      for (const li of getChildren(listElement)) {
+        if (!isElement(li) || li.tagName !== 'li') continue;
+        const id = String(getAttr(li, 'id') || '');
+        if (!id) continue;
+        const keys = idToBacklinks.get(id);
+        if (!keys || !keys.length) continue;
+        // Remove pre-existing .backrefs in this li to avoid duplicates
+        li.children = getChildren(li).filter((n) => !(isElement(n) && n.tagName === 'small' && hasClass(n, 'backrefs')));
+        const small = {
+          type: 'element',
+          tagName: 'small',
+          properties: { className: ['backrefs'] },
+          children: []
+        };
+        if (keys.length === 1) {
+          // Single backlink: just the icon wrapped in the anchor
+          const a = {
+            type: 'element',
+            tagName: 'a',
+            properties: { href: `#${keys[0]}`, 'aria-label': ariaLabel },
+            children: [ createBackIcon() ]
+          };
+          small.children.push(a);
+        } else {
+          // Multiple backlinks: icon + label + numbered links
+          small.children.push(createBackIcon());
+          small.children.push({ type: 'text', value: ' back: ' });
+          keys.forEach((backId, idx) => {
+            small.children.push({
+              type: 'element',
+              tagName: 'a',
+              properties: { href: `#${backId}`, 'aria-label': ariaLabel },
+              children: [ { type: 'text', value: String(idx + 1) } ]
+            });
+            if (idx < keys.length - 1) small.children.push({ type: 'text', value: ', ' });
+          });
+        }
+        li.children.push(small);
+      }
+    };
+    // Remove default back-reference anchors generated by remark-footnotes inside a footnote item
+    const getTextContent = (el) => {
+      if (!el) return '';
+      const stack = [el];
+      let out = '';
+      while (stack.length) {
+        const cur = stack.pop();
+        if (!cur) continue;
+        if (cur.type === 'text') out += String(cur.value || '');
+        const kids = getChildren(cur);
+        for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+      }
+      return out;
+    };
+
+    const removeFootnoteBackrefAnchors = (el) => {
+      if (!isElement(el)) return;
+      const kids = getChildren(el);
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const child = kids[i];
+        if (isElement(child)) {
+          if (
+            child.tagName === 'a' && (
+              getAttr(child, 'data-footnote-backref') != null ||
+              hasClass(child, 'footnote-backref') ||
+              String(getAttr(child, 'role') || '').toLowerCase() === 'doc-backlink' ||
+              String(getAttr(child, 'aria-label') || '').toLowerCase().includes('back to content') ||
+              String(getAttr(child, 'href') || '').startsWith('#fnref') ||
+              // Fallback: text-based detection like "↩" or "↩2"
+              /^\s*↩\s*\d*\s*$/u.test(getTextContent(child))
+            )
+          ) {
+            // Remove the anchor
+            el.children.splice(i, 1);
+            continue;
+          }
+          // Recurse into element
+          removeFootnoteBackrefAnchors(child);
+          // If a wrapper like <sup> or <span> became empty, remove it
+          const becameKids = getChildren(child);
+          if ((child.tagName === 'sup' || child.tagName === 'span') && (!becameKids || becameKids.length === 0)) {
+            el.children.splice(i, 1);
+          }
+        }
+      }
+    };
+
+
+    const normDoiHref = (href) => {
+      if (!href) return href;
+      const DUP = /https?:\/\/(?:dx\.)?doi\.org\/(?:https?:\/\/(?:dx\.)?doi\.org\/)+/gi;
+      const ONE = /https?:\/\/(?:dx\.)?doi\.org\/(10\.[^\s<>"']+)/i;
+      href = String(href).replace(DUP, 'https://doi.org/');
+      const m = href.match(ONE);
+      return m ? `https://doi.org/${m[1]}` : href;
+    };
+
+    const DOI_BARE = /\b10\.[0-9]{4,9}\/[\-._;()\/:A-Z0-9]+\b/gi;
+    const URL_GEN = /\bhttps?:\/\/[^\s<>()"']+/gi;
+
+    const linkifyTextNode = (textNode) => {
+      const text = String(textNode.value || '');
+      let last = 0;
+      const parts = [];
+      const pushText = (s) => { if (s) parts.push({ type: 'text', value: s }); };
+
+      const matches = [];
+      // Collect URL matches
+      let m;
+      URL_GEN.lastIndex = 0;
+      while ((m = URL_GEN.exec(text)) !== null) {
+        matches.push({ type: 'url', start: m.index, end: URL_GEN.lastIndex, raw: m[0] });
+      }
+      // Collect DOI matches
+      DOI_BARE.lastIndex = 0;
+      while ((m = DOI_BARE.exec(text)) !== null) {
+        matches.push({ type: 'doi', start: m.index, end: DOI_BARE.lastIndex, raw: m[0] });
+      }
+      matches.sort((a, b) => a.start - b.start);
+
+      for (const match of matches) {
+        if (match.start < last) continue; // overlapping
+        pushText(text.slice(last, match.start));
+        if (match.type === 'url') {
+          const href = normDoiHref(match.raw);
+          const doiOne = href.match(/https?:\/\/(?:dx\.)?doi\.org\/(10\.[^\s<>"']+)/i);
+          const a = {
+            type: 'element',
+            tagName: 'a',
+            properties: { href, target: '_blank', rel: 'noopener noreferrer' },
+            children: [{ type: 'text', value: doiOne ? doiOne[1] : href }]
+          };
+          parts.push(a);
+        } else {
+          const href = `https://doi.org/${match.raw}`;
+          const a = {
+            type: 'element',
+            tagName: 'a',
+            properties: { href, target: '_blank', rel: 'noopener noreferrer' },
+            children: [{ type: 'text', value: match.raw }]
+          };
+          parts.push(a);
+        }
+        last = match.end;
+      }
+
+      pushText(text.slice(last));
+      return parts;
+    };
+
+    const linkifyInElement = (el) => {
+      const kids = getChildren(el);
+      for (let i = 0; i < kids.length; i++) {
+        const child = kids[i];
+        if (!child) continue;
+        if (child.type === 'text') {
+          const replacement = linkifyTextNode(child);
+          if (replacement.length === 1 && replacement[0].type === 'text') continue;
+          // Replace the single text node with multiple nodes
+          el.children.splice(i, 1, ...replacement);
+          i += replacement.length - 1;
+        } else if (isElement(child)) {
+          if (child.tagName === 'a') {
+            const href = normDoiHref(getAttr(child, 'href'));
+            setAttr(child, 'href', href);
+            const m = String(href || '').match(/https?:\/\/(?:dx\.)?doi\.org\/(10\.[^\s<>"']+)/i);
+            if (m && (!child.children || child.children.length === 0)) {
+              child.children = [{ type: 'text', value: m[1] }];
+            }
+            continue;
+          }
+          linkifyInElement(child);
+        }
+      }
+      // Deduplicate adjacent identical anchors
+      for (let i = 1; i < el.children.length; i++) {
+        const prev = el.children[i - 1];
+        const curr = el.children[i];
+        if (isElement(prev) && isElement(curr) && prev.tagName === 'a' && curr.tagName === 'a') {
+          const key = `${getAttr(prev, 'href') || ''}|${(prev.children?.[0]?.value) || ''}`;
+          const key2 = `${getAttr(curr, 'href') || ''}|${(curr.children?.[0]?.value) || ''}`;
+          if (key === key2) {
+            el.children.splice(i, 1);
+            i--;
+          }
+        }
+      }
+    };
+
+    // Find references container and normalize its list
+    const findReferencesRoot = () => {
+      let found = null;
+      walk(tree, null, (node) => {
+        if (found) return;
+        if (!isElement(node)) return;
+        const id = getAttr(node, 'id');
+        if (id === 'references' || hasClass(node, 'references') || hasClass(node, 'bibliography')) {
+          found = node;
+        }
+      });
+      return found;
+    };
+
+    const toOrderedList = (container) => {
+      // If there is already an <ol>, use it; otherwise convert common structures
+      let ol = getChildren(container).find((c) => isElement(c) && c.tagName === 'ol');
+      if (!ol) {
+        ol = { type: 'element', tagName: 'ol', properties: { className: ['references'] }, children: [] };
+        const candidates = getChildren(container).filter((n) => isElement(n));
+        if (candidates.length) {
+          for (const node of candidates) {
+            if (hasClass(node, 'csl-entry') || node.tagName === 'li' || node.tagName === 'p' || node.tagName === 'div') {
+              const li = { type: 'element', tagName: 'li', properties: {}, children: getChildren(node) };
+              if (getAttr(node, 'id')) setAttr(li, 'id', getAttr(node, 'id'));
+              ol.children.push(li);
+            }
+          }
+        }
+        // Replace container children by the new ol
+        container.children = [ol];
+      }
+      if (!hasClass(ol, 'references')) {
+        const cls = ensureArray(ol.properties?.className).map(String);
+        if (!cls.includes('references')) cls.push('references');
+        ol.properties = ol.properties || {};
+        ol.properties.className = cls;
+      }
+      return ol;
+    };
+
+    const refsRoot = findReferencesRoot();
+    let refsOl = null;
+    const refIdSet = new Set();
+    const refIdToExternalHref = new Map();
+
+    if (refsRoot) {
+      refsOl = toOrderedList(refsRoot);
+      // Collect item ids and linkify their content
+      for (const li of getChildren(refsOl)) {
+        if (!isElement(li) || li.tagName !== 'li') continue;
+        if (!getAttr(li, 'id')) {
+          // Try to find a nested element with id to promote
+          const nestedWithId = getChildren(li).find((n) => isElement(n) && getAttr(n, 'id'));
+          if (nestedWithId) setAttr(li, 'id', getAttr(nestedWithId, 'id'));
+        }
+        const id = getAttr(li, 'id');
+        if (id) refIdSet.add(String(id));
+        linkifyInElement(li);
+        // Record first external link href (e.g., DOI/URL) if present
+        if (id) {
+          let externalHref = null;
+          const stack = [li];
+          while (stack.length) {
+            const cur = stack.pop();
+            const kids = getChildren(cur);
+            for (const k of kids) {
+              if (isElement(k) && k.tagName === 'a') {
+                const href = String(getAttr(k, 'href') || '');
+                if (/^https?:\/\//i.test(href)) {
+                  externalHref = href;
+                  break;
+                }
+              }
+              if (isElement(k)) stack.push(k);
+            }
+            if (externalHref) break;
+          }
+          if (externalHref) refIdToExternalHref.set(String(id), externalHref);
+        }
+      }
+      setAttr(refsRoot, 'data-built-refs', '1');
+    }
+
+    // Collect in-text anchors that point to references ids
+    const { idToBacklinks: refIdToBacklinks, idToAnchorNodes: refIdToCitationAnchors } = collectBacklinksForIdSet(refIdSet, 'refctx');
+
+    // Append backlinks into references list items
+    appendBackrefsBlock(refsOl, refIdToBacklinks, 'Back to citation');
+
+    // Rewrite in-text citation anchors to external link when available
+    if (refIdToCitationAnchors.size > 0) {
+      for (const [id, anchors] of refIdToCitationAnchors.entries()) {
+        const ext = refIdToExternalHref.get(id);
+        if (!ext) continue;
+        for (const a of anchors) {
+          setAttr(a, 'data-ref-id', id);
+          setAttr(a, 'href', ext);
+          const existingTarget = getAttr(a, 'target');
+          if (!existingTarget) setAttr(a, 'target', '_blank');
+          const rel = String(getAttr(a, 'rel') || '');
+          const relSet = new Set(rel ? rel.split(/\s+/) : []);
+          relSet.add('noopener');
+          relSet.add('noreferrer');
+          setAttr(a, 'rel', Array.from(relSet).join(' '));
+        }
+      }
+    }
+
+    // Footnotes cleanup + backrefs harmonized with references
+    const cleanupFootnotes = () => {
+      let root = null;
+      walk(tree, null, (node) => {
+        if (!isElement(node)) return;
+        if (hasClass(node, 'footnotes')) root = node;
+      });
+      if (!root) return { root: null, ol: null, idSet: new Set() };
+      // Remove <hr> direct children
+      root.children = getChildren(root).filter((n) => !(isElement(n) && n.tagName === 'hr'));
+      // Ensure an <ol>
+      let ol = getChildren(root).find((c) => isElement(c) && c.tagName === 'ol');
+      if (!ol) {
+        ol = { type: 'element', tagName: 'ol', properties: {}, children: [] };
+        const items = getChildren(root).filter((n) => isElement(n) && (n.tagName === 'li' || hasClass(n, 'footnote') || n.tagName === 'p' || n.tagName === 'div'));
+        if (items.length) {
+          for (const it of items) {
+            const li = { type: 'element', tagName: 'li', properties: {}, children: getChildren(it) };
+            // Promote nested id if present (e.g., <p id="fn-1">)
+            const nestedWithId = getChildren(it).find((n) => isElement(n) && getAttr(n, 'id'));
+            if (nestedWithId) setAttr(li, 'id', getAttr(nestedWithId, 'id'));
+            ol.children.push(li);
+          }
+        }
+        root.children = [ol];
+      }
+      // For existing structures, try to promote ids from children when missing
+      for (const li of getChildren(ol)) {
+        if (!isElement(li) || li.tagName !== 'li') continue;
+        if (!getAttr(li, 'id')) {
+          const nestedWithId = getChildren(li).find((n) => isElement(n) && getAttr(n, 'id'));
+          if (nestedWithId) setAttr(li, 'id', getAttr(nestedWithId, 'id'));
+        }
+        // Remove default footnote backrefs anywhere inside (to avoid duplication)
+        removeFootnoteBackrefAnchors(li);
+      }
+      setAttr(root, 'data-built-footnotes', '1');
+      // Collect id set
+      const idSet = new Set();
+      for (const li of getChildren(ol)) {
+        if (!isElement(li) || li.tagName !== 'li') continue;
+        const id = getAttr(li, 'id');
+        if (id) idSet.add(String(id));
+      }
+      return { root, ol, idSet };
+    };
+
+    const { root: footRoot, ol: footOl, idSet: footIdSet } = cleanupFootnotes();
+
+    // Collect in-text anchors pointing to footnotes
+    const { idToBacklinks: footIdToBacklinks } = collectBacklinksForIdSet(footIdSet, 'footctx');
+
+    // Append backlinks into footnote list items (identical pattern to references)
+    appendBackrefsBlock(footOl, footIdToBacklinks, 'Back to footnote call');
+  };
+}
+
+

app/plugins/rehype/restore-at-in-code.mjs

@@ -0,0 +1,22 @@
+// Rehype plugin to restore '@' inside code nodes after rehype-citation ran
+export default function rehypeRestoreAtInCode() {
+  return (tree) => {
+    const restoreInNode = (node) => {
+      if (!node || typeof node !== 'object') return;
+      const isText = node.type === 'text';
+      if (isText && typeof node.value === 'string' && node.value.includes('__AT_SENTINEL__')) {
+        node.value = node.value.replace(/__AT_SENTINEL__/g, '@');
+      }
+      const isCodeEl = node.type === 'element' && node.tagName === 'code';
+      const children = Array.isArray(node.children) ? node.children : [];
+      if (isCodeEl && children.length) {
+        children.forEach(restoreInNode);
+        return;
+      }
+      children.forEach(restoreInNode);
+    };
+    restoreInNode(tree);
+  };
+}
+
+

app/plugins/rehype/wrap-tables.mjs

@@ -0,0 +1,43 @@
+// rehype plugin: wrap bare <table> elements in a <div class="table-scroll"> container
+// so that tables stay width:100% while enabling horizontal scroll when content overflows
+
+export default function rehypeWrapTables() {
+  return (tree) => {
+    const isElement = (n) => n && typeof n === 'object' && n.type === 'element';
+    const getChildren = (n) => (Array.isArray(n?.children) ? n.children : []);
+
+    const walk = (node, parent, fn) => {
+      if (!node || typeof node !== 'object') return;
+      fn && fn(node, parent);
+      const kids = getChildren(node);
+      for (const child of kids) walk(child, node, fn);
+    };
+
+    const ensureArray = (v) => (Array.isArray(v) ? v : v != null ? [v] : []);
+    const hasClass = (el, name) => ensureArray(el?.properties?.className).map(String).includes(name);
+
+    const wrapTable = (tableNode, parent) => {
+      if (!parent || !Array.isArray(parent.children)) return;
+      // Don't double-wrap if already inside .table-scroll
+      if (parent.tagName === 'div' && hasClass(parent, 'table-scroll')) return;
+
+      const wrapper = {
+        type: 'element',
+        tagName: 'div',
+        properties: { className: ['table-scroll'] },
+        children: [tableNode]
+      };
+
+      const idx = parent.children.indexOf(tableNode);
+      if (idx >= 0) parent.children.splice(idx, 1, wrapper);
+    };
+
+    walk(tree, null, (node, parent) => {
+      if (!isElement(node)) return;
+      if (node.tagName !== 'table') return;
+      wrapTable(node, parent);
+    });
+  };
+}
+
+

app/plugins/remark/ignore-citations-in-code.mjs

@@ -0,0 +1,21 @@
+// Remark plugin to ignore citations inside code (block and inline)
+export default function remarkIgnoreCitationsInCode() {
+  return (tree) => {
+    const visit = (node) => {
+      if (!node || typeof node !== 'object') return;
+      const type = node.type;
+      if (type === 'code' || type === 'inlineCode') {
+        if (typeof node.value === 'string' && node.value.includes('@')) {
+          // Use a sentinel to avoid rehype-citation, will be restored later in rehype
+          node.value = node.value.replace(/@/g, '__AT_SENTINEL__');
+        }
+        return; // do not traverse into code
+      }
+      const children = Array.isArray(node.children) ? node.children : [];
+      children.forEach(visit);
+    };
+    visit(tree);
+  };
+}
+
+

app/src/components/Accordion.astro

@@ -76,6 +76,8 @@ const wrapperClass = ["accordion", className].filter(Boolean).join(" ");
 
 <style>
   .accordion {
+    margin: 0 0 var(--spacing-4);
+    padding: 0;
     border: 1px solid var(--border-color);
     border-radius: 10px;
     background: var(--surface-bg);
@@ -87,12 +89,13 @@ const wrapperClass = ["accordion", className].filter(Boolean).join(" ");
   }
 
   .accordion__summary {
+    margin: 0;
     list-style: none;
     display: flex;
     align-items: center;
     justify-content: space-between;
     gap: 4px;
-    padding: 4px;
+    padding: 10px 8px;
     cursor: pointer;
     color: var(--text-color);
     user-select: none;
@@ -131,7 +134,8 @@ const wrapperClass = ["accordion", className].filter(Boolean).join(" ");
   }
 
   .accordion__content {
-    padding: 12px 4px 4px;
+    margin: 0;
+    padding: 0;
   }
 
   /* Ensure the very last slotted element has no bottom spacing */
@@ -140,15 +144,30 @@ const wrapperClass = ["accordion", className].filter(Boolean).join(" ");
     margin-bottom: 0 !important;
   }
 
+  /* Ensure the very first slotted element has no top spacing */
+  .accordion .accordion__content > :global(*:first-child) {
+    margin-top: 0 !important;
+  }
+
+  /* Content padding: default for direct children, opt-out for code/tables */
+  .accordion .accordion__content > :global(*) {
+    padding: 8px;
+  }
+  .accordion .accordion__content > :global(.table-scroll),
+  .accordion .accordion__content > :global(pre),
+  .accordion .accordion__content > :global(.code-card) {
+    padding: 0;
+  }
+
   /* Separator between header and content when open (edge-to-edge) */
   .accordion[open] .accordion__content-wrapper::before {
     content: "";
     position: absolute;
     left: 0;
     right: 0;
-    top: 6px; /* space below header */
+    top: 0px; /* space below header */
     height: 1px;
-    background: var(--neutral-300);
+    background: var(--border-color);
     pointer-events: none;
   }
 
@@ -158,6 +177,8 @@ const wrapperClass = ["accordion", className].filter(Boolean).join(" ");
     outline-offset: 3px;
     border-radius: 8px;
   }
+
+
 </style>
 
 

app/src/components/Footer.astro

@@ -2,10 +2,12 @@
 interface Props {
   citationText: string;
   bibtex: string;
+  licence?: string;
+  doi?: string;
 }
-const { citationText, bibtex } = Astro.props as Props;
+const { citationText, bibtex, licence, doi } = Astro.props as Props;
 ---
-<footer class="distill-footer">
+<footer class="footer">
   <div class="footer-inner">
     <section class="citation-block">
       <h3>Citation</h3>
@@ -15,6 +17,18 @@ const { citationText, bibtex } = Astro.props as Props;
       <p>BibTeX citation</p>
       <pre class="citation long">{bibtex}</pre>
     </section>
+    {doi && (
+      <section class="doi-block">
+        <h3>DOI</h3>
+        <p><a href={`https://doi.org/${doi}`} target="_blank" rel="noopener noreferrer">{doi}</a></p>
+      </section>
+    )}
+    {licence && (
+      <section class="reuse-block">
+        <h3>Reuse</h3>
+        <p set:html={licence}></p>
+      </section>
+    )}
     <section class="references-block">
       <slot />
     </section>
@@ -24,7 +38,7 @@ const { citationText, bibtex } = Astro.props as Props;
 
 <script is:inline>
   (() => {
-    const getFooter = () => document.currentScript?.closest('footer') || document.querySelector('footer.distill-footer');
+    const getFooter = () => document.currentScript?.closest('footer') || document.querySelector('footer.footer');
     const footer = getFooter();
     if (!footer) return;
     const target = footer.querySelector('.references-block');
@@ -32,14 +46,6 @@ const { citationText, bibtex } = Astro.props as Props;
 
     const contentRoot = document.querySelector('section.content-grid main') || document.querySelector('main') || document.body;
 
-    const findFirstOutsideFooter = (selectors) => {
-      for (const sel of selectors) {
-        const el = contentRoot.querySelector(sel);
-        if (el && !footer.contains(el)) return el;
-      }
-      return null;
-    };
-
     const ensureHeading = (text) => {
       const exists = Array.from(target.children).some((c) => c.tagName === 'H3' && c.textContent.trim().toLowerCase() === text.toLowerCase());
       if (!exists) {
@@ -51,10 +57,6 @@ const { citationText, bibtex } = Astro.props as Props;
 
     const moveIntoFooter = (element, headingText) => {
       if (!element) return false;
-      if (element.classList.contains('footnotes')) {
-        const hr = element.querySelector('hr');
-        if (hr) hr.remove();
-      }
       // Remove an eventual heading already included inside the block (avoid duplicates)
       const firstHeading = element.querySelector(':scope > h1, :scope > h2, :scope > h3');
       if (firstHeading) {
@@ -68,10 +70,18 @@ const { citationText, bibtex } = Astro.props as Props;
       target.appendChild(element);
       return true;
     };
-
     const run = () => {
+      const findFirstOutsideFooter = (selectors) => {
+        for (const sel of selectors) {
+          const el = contentRoot.querySelector(sel);
+          if (el && !footer.contains(el)) return el;
+        }
+        return null;
+      };
+
       const referencesEl = findFirstOutsideFooter(['#references', '.references', '.bibliography']);
       const footnotesEl = findFirstOutsideFooter(['.footnotes']);
+
       const movedRefs = moveIntoFooter(referencesEl, 'References');
       const movedNotes = moveIntoFooter(footnotesEl, 'Footnotes');
       return movedRefs || movedNotes;
@@ -94,3 +104,159 @@ const { citationText, bibtex } = Astro.props as Props;
 </script>
 
 
+<style is:global>
+  .footer {
+    contain: layout style;
+    font-size: 0.8em;
+    line-height: 1.7em;
+    margin-top: 60px;
+    margin-bottom: 0;
+    border-top: 1px solid rgba(0, 0, 0, 0.1);
+    color: rgba(0, 0, 0, 0.5);
+  }
+
+  .footer-inner {
+    max-width: 1280px;
+    margin: 0 auto;
+    padding: 60px 16px 48px;
+    display: grid;
+    grid-template-columns: 220px minmax(0, 680px) 260px;
+    gap: 32px;
+    align-items: start;
+  }
+
+  /* Use the parent grid (3 columns like .content-grid) */
+  .citation-block,
+  .references-block,
+  .reuse-block,
+  .doi-block {
+    display: contents;
+  }
+
+  .citation-block > h3,
+  .references-block > h3,
+  .reuse-block > h3,
+  .doi-block > h3 {
+    grid-column: 1;
+    font-size: 15px;
+    margin: 0;
+    text-align: right;
+    padding-right: 30px;
+  }
+
+  .citation-block > :not(h3),
+  .references-block > :not(h3),
+  .reuse-block > :not(h3),
+  .doi-block > :not(h3) {
+    grid-column: 2;
+  }
+
+  @media (max-width: var(--bp-content-collapse)) {
+    .footer-inner {
+      grid-template-columns: 1fr;
+      gap: 16px;
+    }
+
+    .footer-inner > h3 {
+      grid-column: auto;
+      margin-top: 16px;
+    }
+  }
+
+  .citation-block h3 {
+    margin: 0 0 8px;
+  }
+
+  .citation-block h4 {
+    margin: 16px 0 8px;
+    font-size: 14px;
+    text-transform: uppercase;
+    color: var(--muted-color);
+  }
+
+  .citation-block p,
+  .reuse-block p,
+  .doi-block p,
+  .footnotes ol,
+  .footnotes ol p,
+  .references {
+    margin-top: 0;
+  }
+
+  /* Distill-like appendix citation styling */
+  .citation {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+    font-size: 11px;
+    line-height: 15px;
+    border-left: 1px solid rgba(0, 0, 0, 0.1);
+    padding-left: 18px;
+    border: 1px solid rgba(0,0,0,0.1);
+    background: rgba(0, 0, 0, 0.02);
+    padding: 10px 18px;
+    border-radius: 3px;
+    color: rgba(150, 150, 150, 1);
+    overflow: hidden;
+    margin-top: -12px;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+  }
+
+  .citation a {
+    color: rgba(0, 0, 0, 0.6);
+    text-decoration: underline;
+  }
+
+  .citation.short {
+    margin-top: -4px;
+  }
+
+  .references-block h3 {
+    margin: 0;
+  }
+
+  /* Distill-like list styling for references/footnotes */
+  .references-block ol {
+    padding: 0 0 0 15px;
+  }
+
+  @media (min-width: 768px) {
+    .references-block ol {
+      padding: 0 0 0 30px;
+      margin-left: -30px;
+    }
+  }
+
+  .references-block li {
+    margin-bottom: 1em;
+  }
+
+  .references-block a {
+    color: var(--text-color);
+  }
+
+  [data-theme="dark"] .footer { border-top-color: rgba(255,255,255,.15); color: rgba(200,200,200,.8); }
+  [data-theme="dark"] .citation { background: rgba(255,255,255,0.04); border-color: rgba(255,255,255,.15); color: rgba(200,200,200,1); }
+[data-theme="dark"] .citation a { color: rgba(255,255,255,0.75); }
+
+
+  @media (max-width: var(--bp-content-collapse)) {
+    .footer-inner {
+      display: block;
+      padding: 40px 16px;
+    }
+  }
+
+  /* Footer links: use primary color consistently */
+  .footer a {
+    color: var(--primary-color);
+    border-bottom: 1px solid var(--link-underline);
+    text-decoration: none;
+  }
+  .footer a:hover {
+    color: var(--primary-color-hover);
+    border-bottom-color: var(--link-underline-hover);
+  }
+  [data-theme="dark"] .footer a {
+    color: var(--primary-color);
+  }
+</style>

app/src/components/Hero.astro

@@ -5,12 +5,32 @@ interface Props {
   title: string; // may contain HTML (e.g., <br/>)
   titleRaw?: string; // plain title for slug/PDF (optional)
   description?: string;
-  authors?: string[];
-  affiliation?: string;
+  authors?: Array<string | { name: string; url?: string; affiliationIndices?: number[] }>;
+  affiliations?: Array<{ id: number; name: string; url?: string }>;
+  affiliation?: string; // legacy single affiliation
   published?: string;
+  doi?: string;
 }
 
-const { title, titleRaw, description, authors = [], affiliation, published } = Astro.props as Props;
+const { title, titleRaw, description, authors = [], affiliations = [], affiliation, published, doi } = Astro.props as Props;
+
+type Author = { name: string; url?: string; affiliationIndices?: number[] };
+
+function normalizeAuthors(input: Array<string | { name?: string; url?: string; link?: string; affiliationIndices?: number[] }>): Author[] {
+  return (Array.isArray(input) ? input : [])
+    .map((a) => {
+      if (typeof a === 'string') {
+        return { name: a } as Author;
+      }
+      const name = (a?.name ?? '').toString();
+      const url = (a?.url ?? a?.link) as string | undefined;
+      const affiliationIndices = Array.isArray((a as any)?.affiliationIndices) ? (a as any).affiliationIndices : undefined;
+      return { name, url, affiliationIndices } as Author;
+    })
+    .filter((a) => a.name && a.name.trim().length > 0);
+}
+
+const normalizedAuthors: Author[] = normalizeAuthors(authors as any);
 
 function stripHtml(text: string): string {
   return String(text || '').replace(/<[^>]*>/g, '');
@@ -37,15 +57,36 @@ const pdfFilename = `${slugify(pdfBase)}.pdf`;
   </div>
 </section>
 
-<header class="meta">
+<header class="meta" aria-label="Article meta information">
   <div class="meta-container">
-    {authors.length > 0 && (
+    {normalizedAuthors.length > 0 && (
       <div class="meta-container-cell">
-        <h3>Author {authors.length > 1 ? 's' : ''}</h3>
-        <p>{authors.join(', ')}</p>
+        <h3>Author{normalizedAuthors.length > 1 ? 's' : ''}</h3>
+        <ul class="authors">
+          {normalizedAuthors.map((a, i) => {
+            const supers = Array.isArray(a.affiliationIndices) && a.affiliationIndices.length
+              ? <sup>{a.affiliationIndices.join(',')}</sup>
+              : null;
+            return (
+              <li>
+                {a.url ? <a href={a.url}>{a.name}</a> : a.name}{supers}
+              </li>
+            );
+          })}
+        </ul>
       </div>
     )}
-    {affiliation && (
+    {(Array.isArray(affiliations) && affiliations.length > 0) && (
+      <div class="meta-container-cell">
+        <h3>Affiliation{affiliations.length > 1 ? 's' : ''}</h3>
+        <ol class="affiliations">
+          {affiliations.map((af) => (
+            <li value={af.id}>{af.url ? <a href={af.url} target="_blank" rel="noopener noreferrer">{af.name}</a> : af.name}</li>
+          ))}
+        </ol>
+      </div>
+    )}
+    {(!affiliations || affiliations.length === 0) && affiliation && (
       <div class="meta-container-cell">
         <h3>Affiliation</h3>
         <p>{affiliation}</p>
@@ -57,49 +98,114 @@ const pdfFilename = `${slugify(pdfBase)}.pdf`;
         <p>{published}</p>
       </div>
     )}
+    <!-- {doi && (
+      <div class="meta-container-cell">
+        <h3>DOI</h3>
+        <p><a href={`https://doi.org/${doi}`} target="_blank" rel="noopener noreferrer">{doi}</a></p>
+      </div>
+    )} -->
     <div class="meta-container-cell meta-container-cell--pdf">
       <h3>PDF</h3>
-      <p><button id="download-pdf-btn" data-pdf-filename={pdfFilename}>Download PDF</button></p>
+      <p>
+        <a class="button" href={`/${pdfFilename}`} download={pdfFilename} aria-label={`Download PDF ${pdfFilename}`}>
+          Download PDF
+        </a>
+      </p>
     </div>
   </div>
 </header>
 
-<script>
-  // Attach a handler to trigger a programmatic download
-  (() => {
-    const ready = () => {
-      const btn = document.getElementById('download-pdf-btn');
-      if (!btn) return;
-      btn.addEventListener('click', () => {
-        const a = document.createElement('a');
-        const pdf = btn.getAttribute('data-pdf-filename') || 'article.pdf';
-        a.href = `/${pdf}`;
-        a.setAttribute('download', pdf);
-        document.body.appendChild(a);
-        a.click();
-        a.remove();
-      });
-    };
-    if (document.readyState === 'loading') {
-      document.addEventListener('DOMContentLoaded', ready, { once: true });
-    } else { ready(); }
-  })();
-</script>
 
 <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: 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; }
+  .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: 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;
+  }
 
   /* Meta (byline-like header) */
-  .meta { border-top: 1px solid var(--border-color); border-bottom: 1px solid var(--border-color); padding: 1rem 0; font-size: 0.9rem; line-height: 1.8em; }
-  .meta-container { max-width: 720px; display: flex; flex-direction: row; justify-content: space-between; margin: 0 auto; gap: 8px; }
-  .meta-container-cell { display: flex; flex-direction: column; gap: 8px; }
-  .meta-container-cell h3 { margin: 0; font-size: 12px; font-weight: 400; color: var(--muted-color); text-transform: uppercase; letter-spacing: .02em; }
-  .meta-container-cell p { margin: 0; }
-  @media print { .meta-container-cell--pdf { display: none !important; } }
+  .meta {
+    border-top: 1px solid var(--border-color);
+    border-bottom: 1px solid var(--border-color);
+    padding: 1rem 0;
+    font-size: 0.9rem;
+  }
+  .meta-container {
+    max-width: 760px;
+    display: flex;
+    flex-direction: row;
+    justify-content: space-between;
+    margin: 0 auto;
+    padding: 0 var(--content-padding-x);
+    gap: 8px;
+  }
+  /* Subtle underline for links in meta; keep buttons without underline */
+  .meta-container a {
+    color: var(--primary-color);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    text-decoration-thickness: 0.06em;
+    text-decoration-color: var(--link-underline);
+    transition: text-decoration-color .15s ease-in-out;
+  }
+  .meta-container a:hover {
+    text-decoration-color: var(--link-underline-hover);
+  }
+  .meta-container a.button,
+  .meta-container .button {
+    text-decoration: none;
+  }
+  .meta-container-cell {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .meta-container-cell h3 {
+    margin: 0;
+    font-size: 12px;
+    font-weight: 400;
+    color: var(--muted-color);
+    text-transform: uppercase;
+    letter-spacing: .02em;
+  }
+  .meta-container-cell p {
+    margin: 0;
+  } 
+  .authors {
+    margin: 0;
+    list-style-type: none;
+    padding-left: 0;
+  }
+  .affiliations {
+    margin: 0;
+    padding-left: 1.25em;
+  }
+  .affiliations li {
+    margin: 0;
+  }
+  @media print {
+    .meta-container-cell--pdf {
+      display: none !important;
+    }
+  }
 </style>
 
 

app/src/components/HtmlEmbed.astro

@@ -68,8 +68,8 @@ const mountId = `frag-${Math.random().toString(36).slice(2)}`;
   else execute();
   </script>
 
-<style>
-  .html-embed { margin: 0; overflow: hidden; }
+<style is:global>
+  .html-embed { margin: 0 0 var(--block-spacing-y); overflow: hidden; }
   .html-embed__title { 
     text-align: left; 
     font-weight: 600; 
@@ -94,9 +94,38 @@ const mountId = `frag-${Math.random().toString(36).slice(2)}`;
     color: var(--muted-color); 
     margin: 6px 0 0 0; 
   }
-  @media (prefers-color-scheme: dark) {
-    [data-theme="dark"] .html-embed__card:not(.is-frameless) { background: #12151b; border-color: rgba(255,255,255,.15); }
-  }
+  /* Plotly – fragments & controls */
+  .html-embed__card svg text { fill: var(--text-color) !important; }
+  .html-embed__card label { color: var(--text-color) !important; }
+  .plotly-graph-div { width: 100% !important; min-height: 320px; }
+  @media (max-width: 768px) { .plotly-graph-div { min-height: 260px; } }
+  [id^="plot-"] { display: flex; flex-direction: column; align-items: center; gap: 15px; }
+  .plotly_caption { font-style: italic; margin-top: 10px; }
+  .plotly_controls { display: flex; flex-wrap: wrap; justify-content: center; gap: 30px; }
+  .plotly_input_container { display: flex; align-items: center; flex-direction: column; gap: 10px; }
+  .plotly_input_container > select { padding: 2px 4px; line-height: 1.5em; text-align: center; border-radius: 4px; font-size: 12px; background-color: var(--neutral-200); outline: none; border: 1px solid var(--neutral-300); }
+  .plotly_slider { display: flex; align-items: center; gap: 10px; }
+  .plotly_slider > input[type="range"] { -webkit-appearance: none; appearance: none; height: 2px; background: var(--neutral-400); border-radius: 5px; outline: none; }
+  .plotly_slider > input[type="range"]::-webkit-slider-thumb { -webkit-appearance: none; width: 18px; height: 18px; border-radius: 50%; background: var(--primary-color); cursor: pointer; }
+  .plotly_slider > input[type="range"]::-moz-range-thumb { width: 18px; height: 18px; border-radius: 50%; background: var(--primary-color); cursor: pointer; }
+  .plotly_slider > span { font-size: 14px; line-height: 1.6em; min-width: 16px; }
+  /* Dark mode overrides for Plotly readability */
+  [data-theme="dark"] .html-embed__card:not(.is-frameless) { background: #12151b; border-color: rgba(255,255,255,.15); }
+  [data-theme="dark"] .html-embed__card .xaxislayer-above text,
+  [data-theme="dark"] .html-embed__card .yaxislayer-above text,
+  [data-theme="dark"] .html-embed__card .infolayer text,
+  [data-theme="dark"] .html-embed__card .legend text,
+  [data-theme="dark"] .html-embed__card .annotation text,
+  [data-theme="dark"] .html-embed__card .colorbar text,
+  [data-theme="dark"] .html-embed__card .hoverlayer text { fill: #fff !important; }
+  [data-theme="dark"] .html-embed__card .xaxislayer-above path,
+  [data-theme="dark"] .html-embed__card .yaxislayer-above path,
+  [data-theme="dark"] .html-embed__card .xlines-above,
+  [data-theme="dark"] .html-embed__card .ylines-above { stroke: rgba(255,255,255,.35) !important; }
+  [data-theme="dark"] .html-embed__card .gridlayer path { stroke: rgba(255,255,255,.15) !important; }
+  [data-theme="dark"] .html-embed__card .legend rect.bg { fill: rgba(0,0,0,.25) !important; stroke: rgba(255,255,255,.2) !important; }
+  [data-theme="dark"] .html-embed__card .hoverlayer .bg { fill: rgba(0,0,0,.8) !important; stroke: rgba(255,255,255,.2) !important; }
+  [data-theme="dark"] .html-embed__card .colorbar .cbbg { fill: rgba(0,0,0,.25) !important; stroke: rgba(255,255,255,.2) !important; }
   @media print {
     .html-embed, .html-embed__card { max-width: 100% !important; width: 100% !important; margin-left: 0 !important; margin-right: 0 !important; }
     .html-embed__card { padding: 6px; }

app/src/components/Note.astro

@@ -10,21 +10,27 @@ const wrapperClass = ["note", `note--${variant}`, className].filter(Boolean).joi
 const hasHeader = (emoji && String(emoji).length > 0) || (title && String(title).length > 0);
 ---
 <div class={wrapperClass} {...props}>
-  {hasHeader && <div class="note__header">
-    {emoji && <span class="note__emoji">{emoji}</span>}
-    {title && <span class="note__title">{title}</span>}
-  </div>}
-  <div class="note__content">
-    <slot />
+  <div class="note__layout">
+    {emoji && <div class="note__icon" aria-hidden="true">
+      <span class="note__emoji">{emoji}</span>
+    </div>}
+    <div class="note__body">
+      {title && <div class="note__title">{title}</div>}
+      <div class="note__content">
+        <slot />
+      </div>
+    </div>
   </div>
 </div>
 
 <style>
-  .note { background: var(--surface-bg); border-left: 2px solid var(--border-color); border-radius: 4px; padding: 10px 14px; margin: 12px 0; }
-  .note__header { display: flex; align-items: center; gap: 6px; font-weight: 600; color: var(--text-color); margin-bottom: 6px; }
-  .note__emoji { font-size: 24px; line-height: 1; }
-  .note__title { font-size: 13px; letter-spacing: .2px; }
-  .note__content { color: var(--text-color); font-size: 0.95rem; }
+  .note { background: var(--surface-bg); border-left: 2px solid var(--border-color); border-radius: 4px; padding: 10px 14px; margin: var(--block-spacing-y) 0; }
+  .note__layout { display: flex; align-items: center; gap: 10px; }
+  .note__icon { flex: 0 0 auto; line-height: 1; }
+  .note__emoji { font-size: 32px; line-height: 1; display: block; }
+  .note__body { flex: 1 1 auto; min-width: 0; }
+  .note__title { font-size: 13px; letter-spacing: .2px; font-weight: 600; color: var(--text-color); margin-bottom: 4px; text-align: left; }
+  .note__content { color: var(--text-color); font-size: 0.95rem; text-align: left; }
   /* Ensure the very last slotted element has no bottom margin */
   .note .note__content > :global(*:last-child) { margin-bottom: 0 !important; }
 

app/src/components/ResponsiveImage.astro

@@ -165,3 +165,49 @@ const dataDownloadable = (downloadable === true || (imgProps as any)['data-downl
 </script>
 
 
+<style>
+
+  figure { margin: var(--block-spacing-y) 0; }
+  figcaption { text-align: left; font-size: 0.9rem; color: var(--muted-color); margin-top: 6px; }
+  .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); }
+
+    /* Opt-in zoomable images */
+  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); }
+</style>

app/src/components/Sidenote.astro

@@ -1,12 +1,37 @@
 ---
 ---
-<div class="margin-aside">
-  <div class="margin-aside__main">
+<div class="aside">
+  <div class="aside__main">
     <slot />
   </div>
-  <aside class="margin-aside__aside">
+  <aside class="aside__aside">
     <slot name="aside" />
   </aside>
 </div>
 
 
+<style is:global>
+  .aside {
+    position: relative;
+    margin: 12px 0;
+  }
+
+  .aside__aside {
+    position: absolute;
+    top: 0;
+    right: -260px; /* push into the right grid column (width 260 + gap 32) */
+    width: 260px;
+    border-radius: 8px;
+    padding: 0 30px;
+    font-size: 0.9rem;
+    color: var(--muted-color);
+  }
+
+  @media (max-width: var(--bp-content-collapse)) {
+    .aside__aside {
+      position: static;
+      width: auto;
+      margin-top: 8px;
+    }
+  }
+</style>

app/src/components/{TableOfContent.astro → TableOfContents.astro}

@@ -2,12 +2,11 @@
 export interface Props { tableOfContentAutoCollapse?: boolean }
 const { tableOfContentAutoCollapse = false } = Astro.props as Props;
 ---
-<aside class="toc" data-auto-collapse={tableOfContentAutoCollapse ? '1' : '0'}>
+<aside class="table-of-contents" data-auto-collapse={tableOfContentAutoCollapse ? '1' : '0'}>
   <div class="title">Table of Contents</div>
   <div id="article-toc-placeholder"></div>
-  
 </aside>
-<details class="toc-mobile">
+<details class="table-of-contents-mobile">
   <summary>Table of Contents</summary>
   <div id="article-toc-mobile-placeholder"></div>
 </details>
@@ -98,7 +97,7 @@ const { tableOfContentAutoCollapse = false } = Astro.props as Props;
       ...(holder ? holder.querySelectorAll('a') : []),
       ...(holderMobile ? holderMobile.querySelectorAll('a') : [])
     ];
-    const autoCollapse = (document.querySelector('aside.toc')?.getAttribute('data-auto-collapse') === '1');
+    const autoCollapse = (document.querySelector('aside.table-of-contents')?.getAttribute('data-auto-collapse') === '1');
 
     // Inject styles for collapsible & animation
     const ensureStyles = () => {
@@ -106,10 +105,10 @@ const { tableOfContentAutoCollapse = false } = Astro.props as Props;
       const style = document.createElement('style');
       style.id = 'toc-collapse-style';
       style.textContent = `
-        aside.toc nav.toc-collapsible > ul > li > ul,
-        details.toc-mobile nav.toc-collapsible > ul > li > ul { overflow: hidden; transition: height 200ms ease; }
-        aside.toc nav.toc-collapsible > ul > li.collapsed > ul,
-        details.toc-mobile nav.toc-collapsible > ul > li.collapsed > ul { display: block; }
+        aside.table-of-contents nav.table-of-contents-collapsible > ul > li > ul,
+        details.table-of-contents-mobile nav.table-of-contents-collapsible > ul > li > ul { overflow: hidden; transition: height 200ms ease; }
+        aside.table-of-contents nav.table-of-contents-collapsible > ul > li.collapsed > ul,
+        details.table-of-contents-mobile nav.table-of-contents-collapsible > ul > li.collapsed > ul { display: block; }
       `;
       document.head.appendChild(style);
     };
@@ -125,8 +124,8 @@ const { tableOfContentAutoCollapse = false } = Astro.props as Props;
     const setNavCollapsible = () => {
       const sideNav = holder ? holder.querySelector('nav') : null;
       const mobileNav = holderMobile ? holderMobile.querySelector('nav') : null;
-      if (sideNav) sideNav.classList.add('toc-collapsible');
-      if (mobileNav) mobileNav.classList.add('toc-collapsible');
+      if (sideNav) sideNav.classList.add('table-of-contents-collapsible');
+      if (mobileNav) mobileNav.classList.add('table-of-contents-collapsible');
     };
 
     const measure = (el) => {
@@ -205,6 +204,9 @@ const { tableOfContentAutoCollapse = false } = Astro.props as Props;
       if (activeIdx !== prevActiveIdx) setCollapsedState(activeIdx);
     };
 
+    // If auto-collapse, collapse immediately (expand first section) before any scroll
+    if (autoCollapse) setCollapsedState(0);
+
     window.addEventListener('scroll', onScroll);
     // Initialize state
     onScroll();
@@ -227,4 +229,128 @@ const { tableOfContentAutoCollapse = false } = Astro.props as Props;
   } else { buildTOC(); }
 </script>
 
+<style is:global>
+  /* Sticky aside */
+  .table-of-contents {
+    position: sticky;
+    top: 32px;
+  }
+
+  .table-of-contents nav {
+    border-left: 1px solid var(--border-color);
+    padding-left: 16px;
+    font-size: 13px;
+  }
+
+  .table-of-contents .title {
+    font-weight: 600;
+    font-size: 14px;
+    margin-bottom: 8px;
+  }
+
+  /* Look & feel */
+  .table-of-contents nav ul {
+    margin: 0 0 6px;
+    padding-left: 1em;
+  }
+
+  .table-of-contents nav li {
+    list-style: none;
+    margin: .25em 0;
+  }
+
+  .table-of-contents nav a,
+  .table-of-contents nav a:link,
+  .table-of-contents nav a:visited {
+    color: var(--text-color);
+    text-decoration: none;
+    border-bottom: none;
+  }
+
+  .table-of-contents nav > ul > li > a {
+    font-weight: 700;
+  }
+
+  .table-of-contents nav a:hover {
+    text-decoration: underline solid var(--muted-color);
+  }
+
+  .table-of-contents nav a.active {
+    text-decoration: underline;
+  }
+
+  /* Mobile accordion */
+  .table-of-contents-mobile {
+    display: none;
+    margin: 8px 0 16px;
+  }
+
+  .table-of-contents-mobile > summary {
+    cursor: pointer;
+    list-style: none;
+    padding: 8px 12px;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    color: var(--text-color);
+    font-weight: 600;
+  }
+
+  .table-of-contents-mobile[open] > summary {
+    border-bottom-left-radius: 0;
+    border-bottom-right-radius: 0;
+  }
 
+  .table-of-contents-mobile nav {
+    border-left: none;
+    padding: 10px 12px;
+    font-size: 14px;
+    border: 1px solid var(--border-color);
+    border-top: none;
+    border-bottom-left-radius: 8px;
+    border-bottom-right-radius: 8px;
+  }
+
+  .table-of-contents-mobile nav ul {
+    margin: 0 0 6px;
+    padding-left: 1em;
+  }
+
+  .table-of-contents-mobile nav li {
+    list-style: none;
+    margin: .25em 0;
+  }
+
+  .table-of-contents-mobile nav a,
+  .table-of-contents-mobile nav a:link,
+  .table-of-contents-mobile nav a:visited {
+    color: var(--text-color);
+    text-decoration: none;
+    border-bottom: none;
+  }
+
+  .table-of-contents-mobile nav > ul > li > a {
+    font-weight: 700;
+  }
+
+  .table-of-contents-mobile nav a:hover {
+    text-decoration: underline solid var(--muted-color);
+  }
+
+  .table-of-contents-mobile nav a.active {
+    text-decoration: underline;
+  }
+
+  [data-theme="dark"] .table-of-contents nav { border-left-color: rgba(255,255,255,.15); }
+
+  /* Responsive: hide sticky TOC, show mobile */
+  @media (max-width: var(--bp-content-collapse)) {
+    .table-of-contents {
+      position: static;
+      display: none;
+    }
+
+    .table-of-contents-mobile {
+      display: block;
+    }
+  }
+</style>

app/src/components/ThemeToggle.astro

@@ -44,3 +44,10 @@
 </button>
 
 
+<style>
+  #theme-toggle { display: inline-flex; align-items: center; gap: 8px; border: none; background: transparent; padding: 6px 10px; border-radius: 8px; cursor: pointer; margin: 12px 16px; color: var(--text-color) !important; }
+#theme-toggle .icon.dark { display: none; }
+[data-theme="dark"] #theme-toggle .icon.light { display: none; }
+[data-theme="dark"] #theme-toggle .icon.dark { display: inline; }
+#theme-toggle .icon { filter: none !important; }
+</style>

app/src/content/article.mdx

@@ -4,20 +4,37 @@ title: "Bringing paper to life:\n A modern template for\n scientific writing
 subtitle: "A modern, MDX-first research article template with math, citations and interactive figures."
 description: "A modern, MDX-first research article template with math, citations and interactive figures."
 authors:
-  - "Thibaud Frere"
-affiliation: "Hugging Face"
+  - name: "Thibaud Frere"
+    url: "https://huggingface.co/tfrere"
+    affiliations: [1]
+  - name: "Alice Example"
+    url: "https://example.com/~alice"
+    affiliations: [1, 2]
+  - name: "Bob Researcher"
+affiliations:
+  - name: "Hugging Face"
+    url: "https://huggingface.co"
+  - name: "Example University"
+    url: "https://example.edu"
 published: "Sep. 01, 2025"
+doi: 10.1234/abcd.efgh
+licence: >
+  Diagrams and text are licensed under <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener noreferrer">CC‑BY 4.0</a> with the source available on <a href="https://huggingface.co/spaces/tfrere/research-article-template" target="_blank" rel="noopener noreferrer">Hugging Face</a>, unless noted otherwise.
+  Figures reused from other sources are excluded and marked in their captions (“Figure from …”).
 tags:
   - research
   - template
-tocAutoCollapse: true
+tableOfContentsAutoCollapse: true
 ---
 
 import Introduction from "./chapters/introduction.mdx";
 import BestPractices from "./chapters/best-pratices.mdx";
 import WritingYourContent from "./chapters/writing-your-content.mdx";
-import AvailableBlocks from "./chapters/available-blocks.mdx";  
+import AvailableBlocks from "./chapters/markdown.mdx";  
 import GettingStarted from "./chapters/getting-started.mdx";
+import Markdown from "./chapters/markdown.mdx";
+import Components from "./chapters/components.mdx";
+import DebugComponents from "./chapters/debug-components.mdx";
 
 <Introduction />
 
@@ -25,7 +42,10 @@ import GettingStarted from "./chapters/getting-started.mdx";
 
 <WritingYourContent />
 
-<AvailableBlocks />
+<Markdown />
+
+<Components />
 
 <BestPractices />
 
+<DebugComponents />

app/src/content/bibliography.bib

@@ -6,18 +6,6 @@
   year={2017}
 }
 
-@article{example2023,
-  title={Example Paper Title},
-  author={Example, A. and Another, A.},
-  journal={Journal of Examples},
-  volume={1},
-  number={1},
-  pages={1--10},
-  year={2023},
-  publisher={Example Publisher}
-}
-
-
 @book{mckinney2017python,
   title={Python for Data Analysis},
   author={McKinney, Wes},

app/src/content/chapters/{available-blocks.mdx → components.mdx}

@@ -9,102 +9,21 @@ import FullWidth from '../../components/FullWidth.astro';
 import Accordion from '../../components/Accordion.astro';
 import ResponsiveImage from '../../components/ResponsiveImage.astro';
 
-## Available components
+## Components
 
 **All** the following **components** are available in the **article.mdx** file. You can also create your own **components** by creating a new file in the `/components` folder.
+You have to import them in the **.mdx** file you want to use them in.
 
 <br/>
 <div className="button-group">
-  <a className="button" href="#math">Math</a>
-  <a className="button" href="#code-blocks">Code</a>
-  <a className="button" href="#citations-and-notes">Citations & notes</a>
   <a className="button" href="#responsiveimage">ResponsiveImage</a>
-  <a className="button" href="#mermaid-diagrams">Mermaid</a>
   <a className="button" href="#placement">Placement</a>
   <a className="button" href="#accordion">Accordion</a>
   <a className="button" href="#note">Note</a>
-  <a className="button" href="#minimal-table">Minimal table</a>
-  <a className="button" href="#audio">Audio</a>
-  <a className="button" href="#htmlembeds">HtmlEmbeds</a>
+  <a className="button" href="#htmlembed">HtmlEmbed</a>
+  <a className="button" href="#iframe">Iframe</a>
 </div>
 
-### Math
-
-KaTeX is used for math rendering.
-
-**Inline**
-
-This is an inline math equation: $x^2 + y^2 = z^2$. 
-
-
-<small className="muted">Example</small>
-```mdx
-$x^2 + y^2 = z^2$
-```
-
-**Block**
-
-$$
-\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
-$$
-
-<small className="muted">Example</small>
-```mdx
-$$
-\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
-$$
-```
-
-### Code
-
-Use fenced code blocks with a language for syntax highlighting.
-
-```python
-def greet(name: str) -> None:
-    print(f"Hello, {name}!")
-
-greet("Astro")
-```
-
-<small className="muted">Example</small>
-````mdx
-```python
-def greet(name: str) -> None:
-    print(f"Hello, {name}!")
-
-greet("Astro")
-```
-````
-
-
-### Citation and footnote
-
-**Citations** use the `@` syntax (e.g., `[@vaswani2017attention]` or `@vaswani2017attention` in narrative form) and are **automatically** collected to render the **bibliography** at the end of the article. The citation keys come from `app/src/content/bibliography.bib`.
-
-**Footnotes** use an identifier like `[^f1]` and a definition anywhere in the document, e.g., `[^f1]: Your explanation`. They are **numbered** and **listed automatically** at the end of the article.
-
-Here are a few variations using the same bibliography:
-
-1) **In-text citation** with brackets: [@example2023].
-
-2) **Narrative citation**: As shown by @vaswani2017attention, transformers enable efficient sequence modeling.
-
-3) **Multiple citations** and a **footnote** together: see [@vaswani2017attention; @example2023] for related work. Also note this footnote[^f1].
-
-[^f1]: Footnote attached to the sentence above.
-
-<small className="muted">Example</small>
-```mdx
-1) In-text citation with brackets: [@example2023].
-
-2) Narrative citation: As shown by @vaswani2017attention, transformers enable efficient sequence modeling.
-
-3) Multiple citations and a footnote together: see [@vaswani2017attention; @example2023] for related work. Also note this footnote[^f1].
-
-[^f1]: Footnote attached to the sentence above.
-```
-
-
 ### ResponsiveImage
 
 **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**.
@@ -145,95 +64,58 @@ import myImage from './assets/images/placeholder.jpg'
 ```
 
 
+### Placement
 
-### Mermaid diagram
-
-Native mermaid diagrams are supported. You can use the <a target="_blank" href="https://mermaid.live/edit#pako:eNpVjUFPg0AQhf_KZk6a0AYsCywHE0u1lyZ66EnoYQMDSyy7ZFlSK_DfXWiMOqd58773ZoBcFQgxlGd1yQXXhhx3mSR2ntJE6LozDe9OZLV6HPdoSKMkXkeyvdsr0gnVtrWs7m_8doZIMhxmDIkRtfyYblay5F8ljmSXHnhrVHv66xwvaiTPaf0mbP1_R2i0qZe05HHJVznXJOF6QcCBStcFxEb36ECDuuGzhGF2MzACG8wgtmuBJe_PJoNMTjbWcvmuVPOT1KqvBNj6c2dV3xbc4K7mlea_CMoCdaJ6aSCm3lIB8QCfED94dM2o77ssjFzK3MiBq2WCNWUeiza-H26YvU8OfC0_3XVII9eLQuYFIaVBGEzfyTJ22g"> live editor</a> to create your diagram and copy the code to your article.
+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.
 
+#### Sidenotes
 
-```mermaid
-erDiagram
-  DATASET ||--o{ SAMPLE : contains
-  RUN }o--o{ SAMPLE : uses
-  RUN ||--|| MODEL : trains
-  RUN ||--o{ METRIC : logs
+<Sidenote>
+  This paragraph presents a **key idea** concisely.
+  <Fragment slot="aside">
+    **Side note** for brief context or a definition.
+  </Fragment>
+  </Sidenote>
 
-  DATASET {
-    string id
-    string name
-  }
+<small className="muted">Example</small>
+```mdx
+import Sidenote from '../components/Sidenote.astro'
 
-  SAMPLE {
-    string id
-    string uri
-  }
+<Sidenote>
+  Main paragraph with the core idea.
+  <Fragment slot="aside">Short side note.</Fragment>
+</Sidenote>
+```
 
-  MODEL {
-    string id
-    string framework
-  }
 
-  RUN {
-    string id
-    date startedAt
-  }
+#### Wide example
 
-  METRIC {
-    string name
-    float value
-  }
-```
+<Wide>
+  <div className="demo-wide">demo wide</div>
+</Wide>
 
 <small className="muted">Example</small>
-````mdx
-```mermaid
-erDiagram
-  DATASET ||--o{ SAMPLE : contains
-  RUN }o--o{ SAMPLE : uses
-  RUN ||--|| MODEL : trains
-  RUN ||--o{ METRIC : logs
-
-  DATASET {
-    string id
-    string name
-  }
-
-  SAMPLE {
-    string id
-    string uri
-  }
-
-  MODEL {
-    string id
-    string framework
-  }
-
-  RUN {
-    string id
-    date startedAt
-  }
-
-  METRIC {
-    string name
-    float value
-  }
-```
-````
-
+```mdx
+import Wide from '../components/Wide.astro'
 
-### Separator
+<Wide>
+  Your content here...
+</Wide>
+```
 
-Use `---` on its own line to insert a horizontal separator between sections. This is a standard Markdown “thematic break”. Don’t confuse it with the `---` used at the very top of the file to delimit the frontmatter.
+#### Full-width example
 
----
+<FullWidth>
+  <div className="demo-full-width">demo full-width</div>
+</FullWidth>
 
 <small className="muted">Example</small>
 ```mdx
-Intro paragraph.
+import FullWidth from '../components/FullWidth.astro'
 
----
-
-Next section begins here.
+<FullWidth>
+  Your content here...
+</FullWidth>
 ```
 
 
@@ -287,7 +169,8 @@ Small contextual callout for tips, caveats, or emphasis.
 | `title`  | No       | string                       | Short title displayed in header     |
 | `emoji`  | No       | string                       | Emoji displayed before the title    |
 | `class`  | No       | string                       | Extra classes for custom styling    |
-| `variant`| No       | 'info' | 'success' | 'danger' | Visual intent of the note            |
+| `variant`| No       | 'info' | 'success' | 'danger' | Visual intent of the note          |
+
 
 <Note title="Heads‑up" emoji="💡" variant="info">
   Use notes to surface context without breaking reading flow.
@@ -327,35 +210,6 @@ import Note from '../../components/Note.astro'
 ```
 
 
-### Minimal table
-
-| Method | Score |
-|---|---|
-| A | 0.78 |
-| B | 0.86 |
-
-<small className="muted">Example</small>
-```mdx
-| Method | Score |
-| --- | --- |
-| A | 0.78 |
-| B | 0.86 |
-```
-
-### Audio
-
-<audio controls src={audioDemo}/>
-<br/>
-<small className="muted">Example</small>
-```mdx
-import audioDemo from './assets/audio/audio-example.wav'
-
-<audio controls src={audioDemo}/>
-```
-
-
-
-
 ### HtmlEmbed
 
 The main purpose of the ```HtmlEmbed``` component is to **embed** a **Plotly** or **D3.js** chart in your article. **Libraries** are already imported in the template.

app/src/content/chapters/debug-components.mdx

@@ -0,0 +1,37 @@
+import Accordion from '../../components/Accordion.astro';
+import HtmlEmbed from '../../components/HtmlEmbed.astro';
+import ResponsiveImage from '../../components/ResponsiveImage.astro';
+import Wide from '../../components/Wide.astro';
+import FullWidth from '../../components/FullWidth.astro';
+import Note from '../../components/Note.astro';
+
+| Prop                   | Required |
+|------------------------|----------|
+| `zoomable`        | No       |
+| `downloadable`    | No       |
+| `loading="lazy"`       | No       |
+| `caption`              | No       |
+
+<Accordion title="table">
+  | 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).                  
+| `frameless` | No       | Removes the card background and border for seamless embeds.                                      
+| `align`     | No       | Aligns the title/description text. One of `left` (default), `center`, `right`.                  
+</Accordion>
+
+
+<Accordion title="simple">
+  <p>Simple example</p>
+</Accordion>
+
+<Accordion title="code">
+  ```mdx
+  import HtmlEmbed from '../components/HtmlEmbed.astro'
+
+  <HtmlEmbed src="plotly-line.html" title="Plotly Line" desc="Some chart description" />
+  <HtmlEmbed src="d3-line-example.html" title="D3 Line" desc="Some chart description" />
+  ```
+</Accordion>

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

@@ -47,6 +47,8 @@ npm install
 
 <br/>And that's it!
 
+**You're ready to go!** 🎉
+
 ### Development
 
 ```bash

app/src/content/chapters/introduction.mdx

@@ -13,24 +13,24 @@ import Sidenote from "../../components/Sidenote.astro";
 
 <Sidenote>
 <div className="tag-list">
-  <span className="tag">Markdown based</span>
+  <span className="tag">Markdown-based</span>
   <span className="tag">KaTeX math</span>
   <span className="tag">Syntax highlighting</span>
   <span className="tag">Citations & footnotes</span>
-  <span className="tag">Automatic build</span>
   <span className="tag">Table of contents</span>
-  <span className="tag">Dark theme</span>
-  <span className="tag">HTML Embeds</span>
+  <span className="tag">Mermaid diagrams</span>
   <span className="tag">Plotly ready</span>
   <span className="tag">D3.js ready</span>
-  <span className="tag">SEO Friendly</span>
-  <span className="tag">Mermaid diagrams</span>
-  <span className="tag">Lightweight bundle</span>
-  <span className="tag">Mobile friendly</span>
+  <span className="tag">HTML embeds</span>
+  <span className="tag">Gradio app embeds</span>
+  <span className="tag">Dataviz color palettes</span>
   <span className="tag">Optimized images</span>
+  <span className="tag">Lightweight bundle</span>
+  <span className="tag">SEO-friendly</span>
+  <span className="tag">Automatic build</span>
   <span className="tag">Automatic PDF export</span>
-  <span className="tag">Dataviz color palettes</span>
-  <span className="tag">Embed gradio apps</span>
+  <span className="tag">Dark theme</span>
+  <span className="tag">Mobile friendly</span>
 </div>
 <Fragment slot="aside">
     If you have questions, remarks or suggestions, open a discussion on the <a href="https://huggingface.co/spaces/tfrere/research-blog-template/discussions?status=open&type=discussion">Community tab</a>!
@@ -42,9 +42,11 @@ The web enables what static PDFs can’t: **interactive diagrams**, **progressiv
 
 If you write technical blogs or research notes, you’ll benefit from a **ready‑to‑publish workflow** with clear notation, optimized media, and **automatic builds**.
 
-This project draws strong inspiration from [**Distill**](https://distill.pub) (2016–2021), which championed clear, web‑native scholarship and set a high standard for interactive scientific communication.
+### Inspired by Distill
 
 <Sidenote>
+This project draws strong inspiration from [**Distill**](https://distill.pub) (2016–2021), which championed clear, web‑native scholarship and set a high standard for interactive scientific communication.
+
 To give you a sense of what inspired this template, here is a short, curated list of well‑designed and often interactive works from Distill:
 
 - [Growing Neural Cellular Automata](https://distill.pub/2020/growing-ca/)

app/src/content/chapters/markdown.mdx

@@ -0,0 +1,285 @@
+import { Image } from 'astro:assets';
+import placeholder from '../assets/images/placeholder.png';
+import audioDemo from '../assets/audio/audio-example.wav';
+import HtmlEmbed from '../../components/HtmlEmbed.astro';
+import Sidenote from '../../components/Sidenote.astro';
+import Wide from '../../components/Wide.astro';
+import Note from '../../components/Note.astro';
+import FullWidth from '../../components/FullWidth.astro';
+import Accordion from '../../components/Accordion.astro';
+import ResponsiveImage from '../../components/ResponsiveImage.astro';
+
+## Markdown
+
+All the following **markdown features** are available **natively** in the `article.mdx` file. See also the complete [**Markdown documentation**](https://www.markdownguide.org/basic-syntax/).
+
+<br/>
+<div className="button-group">
+  <a className="button" href="#math">Math</a>
+  <a className="button" href="#code-blocks">Code</a>
+  <a className="button" href="#citations-and-notes">Citations</a>
+  <a className="button" href="#footnotes">Footnotes</a>
+  <a className="button" href="#mermaid-diagrams">Mermaid</a>
+  <a className="button" href="#separator">Separator</a>
+  <a className="button" href="#table">Table</a>
+  <a className="button" href="#audio">Audio</a>
+</div>
+
+### Math
+
+KaTeX is used for math rendering.
+
+**Inline**
+
+This is an inline math equation: $x^2 + y^2 = z^2$. 
+
+
+<small className="muted">Example</small>
+```mdx
+$x^2 + y^2 = z^2$
+```
+
+**Block**
+
+$$
+\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
+$$
+
+<small className="muted">Example</small>
+```mdx
+$$
+\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
+$$
+```
+
+### Code
+
+Use fenced code blocks with a language for syntax highlighting.
+
+```python
+def greet(name: str) -> None:
+    print(f"Hello, {name}!")
+
+greet("Astro")
+```
+
+<small className="muted">Example</small>
+````mdx
+```python
+def greet(name: str) -> None:
+    print(f"Hello, {name}!")
+
+greet("Astro")
+```
+````
+
+### Citations
+
+**Citations** use the `@` syntax (e.g., `[@vaswani2017attention]` or `@vaswani2017attention` in narrative form) and are **automatically** collected to render the **bibliography** at the end of the article. The citation keys come from `app/src/content/bibliography.bib`.
+
+1) In-text citation with brackets: [@vaswani2017attention].
+
+2) Narrative citation: As shown by @kingma2015adam, stochastic optimization is widely used.
+
+3) Multiple citations and a footnote together: see [@mckinney2017python; @he2016resnet] for related work.
+
+4) All citations in one group: [@vaswani2017attention; @mckinney2017python; @he2016resnet; @silver2017mastering; @openai2023gpt4; @doe2020thesis; @cover2006entropy; @zenodo2021dataset; @sklearn2024; @smith2024privacy; @kingma2015adam; @raffel2020t5].
+
+<small className="muted">Example</small>
+```mdx
+1) In-text citation with brackets: [@vaswani2017attention].
+
+2) Narrative citation: As shown by @kingma2015adam, stochastic optimization is widely used.
+
+3) Multiple citations and a footnote together: see [@mckinney2017python; @he2016resnet] for related work.
+
+4) All citations in one group: [@vaswani2017attention; @mckinney2017python; @he2016resnet; @silver2017mastering; @openai2023gpt4; @doe2020thesis; @cover2006entropy; @zenodo2021dataset; @sklearn2024; @smith2024privacy; @kingma2015adam; @raffel2020t5].
+```
+
+### Footnotes
+
+**Footnotes** use an identifier like `[^f1]` and a definition anywhere in the document, e.g., `[^f1]: Your explanation`. They are **numbered** and **listed automatically** at the end of the article.
+
+1) Footnote attached to the sentence above[^f1].
+
+[^f1]: Footnote attached to the sentence above.
+
+2) Multi-paragraph footnote example[^f2].
+
+[^f2]: Multi-paragraph footnote. First paragraph.
+
+    Second paragraph with a link to [Astro](https://astro.build).
+
+2) Footnote containing a list[^f3].
+
+[^f3]: Footnote with a list:
+
+    - First item
+    - Second item
+
+3) Footnote with an inline code and an indented code block[^f4].
+
+[^f4]: Footnote with code snippet:
+
+    ```ts
+    function add(a: number, b: number) {
+      return a + b;
+    }
+    ```
+    Result: `add(2, 3) === 5`.
+
+4) Footnote that includes citations inside[^f5] and another footnote[^f1].
+
+[^f5]: Footnote containing citations [@vaswani2017attention] and [@kingma2015adam].
+
+<small className="muted">Example</small>
+```mdx
+1) Footnote attached to the sentence above[^f1].
+
+2) Multi-paragraph footnote example[^f2].
+
+2) Footnote containing a list[^f3].
+
+3) Footnote with an inline code and an indented code block[^f4].
+
+4) Footnote that includes citations inside[^f5].
+
+[^f1]: Footnote attached to the sentence above.
+
+[^f2]: Multi-paragraph footnote. First paragraph.
+
+    Second paragraph with a link to [Astro](https://astro.build).
+
+[^f3]: Footnote with a list:
+
+    - First item
+    - Second item
+
+[^f4]: Footnote with code snippet:
+
+        function add(a: number, b: number) {
+          return a + b;
+        }
+
+    Result: `add(2, 3) === 5`.
+
+[^f5]: Footnote containing citations [@vaswani2017attention] and [@kingma2015adam].
+```
+
+
+### Mermaid diagram
+
+Native mermaid diagrams are supported. You can use the <a target="_blank" href="https://mermaid.live/edit#pako:eNpVjUFPg0AQhf_KZk6a0AYsCywHE0u1lyZ66EnoYQMDSyy7ZFlSK_DfXWiMOqd58773ZoBcFQgxlGd1yQXXhhx3mSR2ntJE6LozDe9OZLV6HPdoSKMkXkeyvdsr0gnVtrWs7m_8doZIMhxmDIkRtfyYblay5F8ljmSXHnhrVHv66xwvaiTPaf0mbP1_R2i0qZe05HHJVznXJOF6QcCBStcFxEb36ECDuuGzhGF2MzACG8wgtmuBJe_PJoNMTjbWcvmuVPOT1KqvBNj6c2dV3xbc4K7mlea_CMoCdaJ6aSCm3lIB8QCfED94dM2o77ssjFzK3MiBq2WCNWUeiza-H26YvU8OfC0_3XVII9eLQuYFIaVBGEzfyTJ22g"> live editor</a> to create your diagram and copy the code to your article.
+
+
+```mermaid
+erDiagram
+  DATASET ||--o{ SAMPLE : contains
+  RUN }o--o{ SAMPLE : uses
+  RUN ||--|| MODEL : trains
+  RUN ||--o{ METRIC : logs
+
+  DATASET {
+    string id
+    string name
+  }
+
+  SAMPLE {
+    string id
+    string uri
+  }
+
+  MODEL {
+    string id
+    string framework
+  }
+
+  RUN {
+    string id
+    date startedAt
+  }
+
+  METRIC {
+    string name
+    float value
+  }
+```
+
+<small className="muted">Example</small>
+````mdx
+```mermaid
+erDiagram
+  DATASET ||--o{ SAMPLE : contains
+  RUN }o--o{ SAMPLE : uses
+  RUN ||--|| MODEL : trains
+  RUN ||--o{ METRIC : logs
+
+  DATASET {
+    string id
+    string name
+  }
+
+  SAMPLE {
+    string id
+    string uri
+  }
+
+  MODEL {
+    string id
+    string framework
+  }
+
+  RUN {
+    string id
+    date startedAt
+  }
+
+  METRIC {
+    string name
+    float value
+  }
+```
+````
+
+
+### Separator
+
+Use `---` on its own line to insert a horizontal separator between sections. This is a standard Markdown “thematic break”. Don’t confuse it with the `---` used at the very top of the file to delimit the frontmatter.
+
+---
+
+<small className="muted">Example</small>
+```mdx
+Intro paragraph.
+
+---
+
+Next section begins here.
+```
+
+### Table
+
+| Method | Score |
+|---|---|
+| A | 0.78 |
+| B | 0.86 |
+
+<small className="muted">Example</small>
+```mdx
+| Method | Score |
+| --- | --- |
+| A | 0.78 |
+| B | 0.86 |
+```
+
+### Audio
+
+<audio controls src={audioDemo}/>
+<br/>
+<small className="muted">Example</small>
+```mdx
+import audioDemo from './assets/audio/audio-example.wav'
+
+<audio controls src={audioDemo}/>
+```
+

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

@@ -8,7 +8,7 @@ import FullWidth from '../../components/FullWidth.astro';
 import HtmlEmbed from '../../components/HtmlEmbed.astro';
 import audioDemo from '../assets/audio/audio-example.wav';
 
-## Writing Your Content
+## Writing your content
 
 ### **Introduction**
 
@@ -21,62 +21,59 @@ Everything is **self-contained** under `app/src/content/`:
 
 The `article.mdx` file is the **main entry point** of your article.
 
+**MDX** is a mix of **Markdown** and **HTML/JSX**: write regular Markdown, and embed **interactive components** inline when needed. We’ll describe the available options you can use later in this guide.
+
+Here's what the file looks like in detail:
+
 <small className="muted">app/src/content/article.mdx</small>
 ```mdx
-{/* HEADER */}
+{/* -- Header ---------------------------- */}
 ---
+{/* ---- Required parameters ------------- */}
 title: "This is the main title"
 subtitle: "This will be displayed just below the banner"
 description: "A modern, MDX-first research article template with math, citations, and interactive figures."
-authors:
-  - "Thibaud Frere"
-  - "Alice Martin"
-  - "Robert Brown"
-affiliation: "Hugging Face"
 published: "Feb 19, 2025"
 tags:
   - research
   - template
-{/* Optional override of the default Open Graph image */}
-ogImage: "https://override-example.com/your-og-image.png"
-{/* By default the table of contents is not collapsing */}
-tocAutoCollapse: true
+authors:
+  - name: "Thibaud Frere" {/* Author name */}
+    url: "https://huggingface.co/tfrere" {/* Optional author url */}
+    affiliations: [1] {/* Optional author affiliations based on the list below */}
+  - name: "Alice Martin"
+    url: "https://example.com/~alice"
+    affiliations: [1, 2]
+  - name: "Robert Brown"
+    url: "https://example.com/~bob"
+    affiliations: [2]
+    
+{/* ---- Optional parameters ------------- */}
+affiliations: {/* Affiliations list */}
+  - name: "Hugging Face"
+    url: "https://huggingface.co"
+  - name: "Example University"
+    url: "https://example.edu"
+doi: 10.1234/abcd.efgh  {/* Add a DOI to your article */}
+{/* Add a licence text to the end of your article */}
+licence: Diagrams and text are licensed under <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener noreferrer">CC‑BY 4.0</a> with the source available on <a href="https://huggingface.co/spaces/stfrere/research-article-template">Hugging Face</a>, unless noted otherwise. Figures reused from other sources are excluded and marked in their captions (“Figure from …”).
+seoThumbImage: "https://example.com/thumb.png" {/* Override default thumbnail */}
+tableOfContentsAutoCollapse: true {/* By default the table of contents is not collapsing */}
 ---
 
-{/* IMPORTS */}
-import { Image } from 'astro:assets';
-import placeholder from './assets/images/placeholder.jpg';
-
-{/* CONTENT */}
-# Hello, world
-
-This is a short paragraph written in Markdown. Below is an example image:
-
-<Image src={placeholder} alt="Example image" />
-```
-
-### MDX 
-
-**MDX** is a mix of **Markdown** and **HTML/JSX**: write regular Markdown, and embed **interactive components** inline when needed. We’ll describe the available components you can use later in this guide.
-
-For Markdown syntax, see the complete [**Markdown documentation**](https://www.markdownguide.org/basic-syntax/).
-
-<small className="muted">Example</small>
-```mdx
-{/* IMPORTS */}
-import { Image } from 'astro:assets'
-import placeholder from './assets/images/placeholder.png'
+{/* -- Imports -------------------------- */}
+import placeholder from '../assets/images/placeholder.png'
+import ResponsiveImage from '../components/ResponsiveImage.astro'
 import Sidenote from '../components/Sidenote.astro'
 
-# Mixing Markdown and components
-
-This paragraph is written in Markdown. 
-
-<Sidenote>A short callout inserted via a component.</Sidenote>
-
-Below is an image imported via Astro and optimized at build time:
+{/* -- Markdown content ------------------ */}
+<Sidenote>
+  This paragraph is written in Markdown. 
+  <Fragment slot="aside">A short callout inserted via a component.</Fragment>
+</Sidenote>
+<ResponsiveImage src={placeholder} alt="Sample image with optimization" />
 
-<Image src={placeholder} alt="Sample image with Astro optimization" />
+This paragraph is also written in Markdown. 
 ```
 
 
@@ -102,6 +99,8 @@ import MyChapter from './chapters/my-chapter.mdx';
  
 The **Table of contents** is generated **automatically** from your **H2–H4** headings. Keep headings **short** and **descriptive**; links work on **desktop** and **mobile**.
 
+<Note variant="info">You can make the table of contents collapse by changing the `tableOfContentsAutoCollapse` parameter in the frontmatter. Which is `true` by default.</Note>
+
 ### Theme
 
 All **interactive elements** (buttons, inputs, cards, etc.) are themed with the **primary color** you choose.
@@ -167,57 +166,3 @@ document.documentElement.style.setProperty('--palette-count', '8');
 document.documentElement.style.setProperty('--palette-diverging-count', '7');
 window.ColorPalettes.refresh();
 ```
-
-### Placement
-
-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.
-
-#### Sidenotes
-
-<Sidenote>
-  This paragraph presents a **key idea** concisely.
-  <Fragment slot="aside">
-    **Side note** for brief context or a definition.
-  </Fragment>
-  </Sidenote>
-
-<small className="muted">Example</small>
-```mdx
-import Sidenote from '../components/Sidenote.astro'
-
-<Sidenote>
-  Main paragraph with the core idea.
-  <Fragment slot="aside">Short side note.</Fragment>
-</Sidenote>
-```
-
-
-#### Wide example
-
-<Wide>
-  <div className="demo-wide">demo wide</div>
-</Wide>
-
-<small className="muted">Example</small>
-```mdx
-import Wide from '../components/Wide.astro'
-
-<Wide>
-  Your content here...
-</Wide>
-```
-
-#### Full-width example
-
-<FullWidth>
-  <div className="demo-full-width">demo full-width</div>
-</FullWidth>
-
-<small className="muted">Example</small>
-```mdx
-import FullWidth from '../components/FullWidth.astro'
-
-<FullWidth>
-  Your content here...
-</FullWidth>
-```

app/src/pages/index.astro

@@ -4,7 +4,7 @@ import Hero from '../components/Hero.astro';
 import Footer from '../components/Footer.astro';
 import ThemeToggle from '../components/ThemeToggle.astro';
 import Seo from '../components/Seo.astro';
-import TableOfContent from '../components/TableOfContent.astro';
+import TableOfContents from '../components/TableOfContents.astro';
 // Default OG image served from public/
 const ogDefaultUrl = '/thumb.jpg';
 import 'katex/dist/katex.min.css';
@@ -18,11 +18,78 @@ const docTitleHtml = (articleFM?.title ?? 'Untitled article')
   .replace(/\n/g, '<br/>');
 const subtitle = articleFM?.subtitle ?? '';
 const description = articleFM?.description ?? '';
-const authors = articleFM?.authors ?? [];
+// Accept authors as string[] or array of objects { name, url, affiliations? }
+const rawAuthors = (articleFM as any)?.authors ?? [];
+type Affiliation = { id: number; name: string; url?: string };
+type Author = { name: string; url?: string; affiliationIndices?: number[] };
+
+// Normalize affiliations from frontmatter: supports strings or objects { id?, name, url? }
+const rawAffils = (articleFM as any)?.affiliations ?? (articleFM as any)?.affiliation ?? [];
+const normalizedAffiliations: Affiliation[] = (() => {
+  const seen: Map<string, number> = new Map();
+  const list: Affiliation[] = [];
+  const pushUnique = (name: string, url?: string) => {
+    const key = `${String(name).trim()}|${url ? String(url).trim() : ''}`;
+    if (seen.has(key)) return seen.get(key)!;
+    const id = list.length + 1;
+    list.push({ id, name: String(name).trim(), url: url ? String(url) : undefined });
+    seen.set(key, id);
+    return id;
+  };
+  const input = Array.isArray(rawAffils) ? rawAffils : (rawAffils ? [rawAffils] : []);
+  for (const a of input) {
+    if (typeof a === 'string') {
+      pushUnique(a);
+    } else if (a && typeof a === 'object') {
+      const name = a.name ?? a.label ?? a.text ?? a.affiliation ?? '';
+      if (!String(name).trim()) continue;
+      const url = a.url || a.link;
+      // Respect provided numeric id for display stability if present and sequential; otherwise reassign
+      pushUnique(String(name), url ? String(url) : undefined);
+    }
+  }
+  return list;
+})();
+
+// Helper: ensure an affiliation exists and return its id
+const ensureAffiliation = (val: any): number | undefined => {
+  if (val == null) return undefined;
+  if (typeof val === 'number' && Number.isFinite(val) && val > 0) {
+    return Math.floor(val);
+  }
+  const name = typeof val === 'string' ? val : (val?.name ?? val?.label ?? val?.text ?? val?.affiliation);
+  if (!name || !String(name).trim()) return undefined;
+  const existing = normalizedAffiliations.find(a => a.name === String(name).trim());
+  if (existing) return existing.id;
+  const id = normalizedAffiliations.length + 1;
+  normalizedAffiliations.push({ id, name: String(name).trim(), url: val?.url || val?.link });
+  return id;
+};
+
+// Normalize authors and map affiliations -> indices (Distill-like)
+const normalizedAuthors: Author[] = (Array.isArray(rawAuthors) ? rawAuthors : [])
+  .map((a: any) => {
+    if (typeof a === 'string') {
+      return { name: a } as Author;
+    }
+    const name = String(a?.name || '').trim();
+    const url = a?.url || a?.link;
+    let indices: number[] | undefined = undefined;
+    const raw = a?.affiliations ?? a?.affiliation ?? a?.affils;
+    if (raw != null) {
+      const entries = Array.isArray(raw) ? raw : [raw];
+      const ids = entries.map(ensureAffiliation).filter((x): x is number => typeof x === 'number');
+      const unique = Array.from(new Set(ids)).sort((x, y) => x - y);
+      if (unique.length) indices = unique;
+    }
+    return { name, url, affiliationIndices: indices } as Author;
+  })
+  .filter((a: Author) => a.name && a.name.trim().length > 0);
+const authorNames: string[] = normalizedAuthors.map(a => a.name);
 const published = articleFM?.published ?? undefined;
 const tags = articleFM?.tags ?? [];
-// Prefer ogImage from frontmatter if provided
-const fmOg = articleFM?.ogImage as string | undefined;
+// Prefer seoThumbImage from frontmatter if provided
+const fmOg = articleFM?.seoThumbImage as string | undefined;
 const imageAbs: string = fmOg && fmOg.startsWith('http')
   ? fmOg
   : (Astro.site ? new URL((fmOg ?? ogDefaultUrl), Astro.site).toString() : (fmOg ?? ogDefaultUrl));
@@ -43,33 +110,27 @@ const extractYear = (val: string | undefined): number | undefined => {
 };
 
 const year = extractYear(published);
-const citationAuthorsText = authors.join(', ');
+const citationAuthorsText = authorNames.join(', ');
 const citationText = `${citationAuthorsText}${year ? ` (${year})` : ''}. "${titleFlat}".`;
 
-const authorsBib = authors.join(' and ');
-const keyAuthor = (authors[0] || 'article').split(/\s+/).slice(-1)[0].toLowerCase();
+const authorsBib = authorNames.join(' and ');
+const keyAuthor = (authorNames[0] || 'article').split(/\s+/).slice(-1)[0].toLowerCase();
 const keyTitle = titleFlat.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '').slice(0, 24);
 const bibKey = `${keyAuthor}${year ?? ''}_${keyTitle}`;
-const bibtex = `@misc{${bibKey},\n  title={${titleFlat}},\n  author={${authorsBib}},\n  ${year ? `year={${year}}` : ''}\n}`;
-// Determine if TOC auto-collapse is enabled via (priority):
-// 1) article frontmatter: tableOfContentAutoCollapse (fallback: tocAutoCollapse)
-// 2) public env flag: PUBLIC_TOC_AUTO_COLLAPSE
-// Falls back to 'false' when not defined (string or boolean)
-const __env = (import.meta as any)?.env || {};
-const envCollapse = (
-  String((__env.PUBLIC_TABLE_OF_CONTENT_AUTO_COLLAPSE ?? __env.PUBLIC_TOC_AUTO_COLLAPSE ?? 'false')).toLowerCase() === 'true'
-  || (__env.PUBLIC_TABLE_OF_CONTENT_AUTO_COLLAPSE === true)
-  || (__env.PUBLIC_TOC_AUTO_COLLAPSE === true)
-);
+const doi = (ArticleMod as any)?.frontmatter?.doi ? String((ArticleMod as any).frontmatter.doi) : undefined;
+const bibtex = `@misc{${bibKey},\n  title={${titleFlat}},\n  author={${authorsBib}},\n  ${year ? `year={${year}},\n  ` : ''}${doi ? `doi={${doi}}` : ''}\n}`;
+const envCollapse = false;
 const tableOfContentAutoCollapse = Boolean(
-  (articleFM as any)?.tableOfContentAutoCollapse ?? (articleFM as any)?.tocAutoCollapse ?? envCollapse
+  (articleFM as any)?.tableOfContentAutoCollapse ?? (articleFM as any)?.tableOfContentsAutoCollapse ?? envCollapse
 );
+// Licence note (HTML allowed)
+const licence = (articleFM as any)?.licence ?? (articleFM as any)?.license ?? (articleFM as any)?.licenseNote;
 ---
 <html lang="en" data-theme="light" data-toc-auto-collapse={tableOfContentAutoCollapse ? '1' : '0'}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <Seo title={docTitle} description={description} authors={authors} published={published} tags={tags} image={imageAbs} />
+    <Seo title={docTitle} description={description} authors={authorNames} published={published} tags={tags} image={imageAbs} />
     <script is:inline>
       (() => {
         try {
@@ -90,10 +151,10 @@ const tableOfContentAutoCollapse = Boolean(
   </head>
   <body>
     <ThemeToggle />
-    <Hero title={docTitleHtml} titleRaw={docTitle} description={subtitle} authors={articleFM?.authors} affiliation={articleFM?.affiliation} published={articleFM?.published} />
+    <Hero title={docTitleHtml} titleRaw={docTitle} description={subtitle} authors={normalizedAuthors as any} affiliations={normalizedAffiliations as any} affiliation={articleFM?.affiliation} published={articleFM?.published} doi={doi} />
 
     <section class="content-grid">
-      <TableOfContent tableOfContentAutoCollapse={tableOfContentAutoCollapse} />
+      <TableOfContents tableOfContentAutoCollapse={tableOfContentAutoCollapse} />
       <main>
         <Article />
         <style is:inline>
@@ -103,7 +164,7 @@ const tableOfContentAutoCollapse = Boolean(
       </main>
     </section>
 
-    <Footer citationText={citationText} bibtex={bibtex} />
+    <Footer citationText={citationText} bibtex={bibtex} licence={licence} doi={doi} />
 
 
     <script>

app/src/styles/_base.css

@@ -1,16 +1,5 @@
-/* ============================================================================ */
-/* Base / Reset */
-/* ============================================================================ */
-html { box-sizing: border-box; }
-*, *::before, *::after { box-sizing: inherit; }
-body { margin: 0; font-family: system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica Neue, Arial, Apple Color Emoji, Segoe UI Emoji; color: var(--text-color); }
-audio { display: block; width: 100%; }
-/* Avoid constraining <main> inside grid; scope container sizing elsewhere if needed */
-/* main { max-width: 980px; margin: 24px auto; padding: 16px; } */
+@import "https://fonts.googleapis.com/css2?family=Source+Sans+Pro:ital,wght@0,200..900;1,200..900&display=swap";
 
-/* ============================================================================ */
-/* Typography (inspired by Distill) */
-/* ============================================================================ */
 html { font-size: 14px; line-height: 1.6; }
 @media (min-width: 768px) { html { font-size: 16px; } }
 @media (min-width: 1024px) { html { font-size: 17px; } }
@@ -70,226 +59,12 @@ html { font-size: 14px; line-height: 1.6; }
   margin: var(--spacing-4) 0;
 }
 
-/* Rely on Shiki's own token spans; no class remap */
-/* Placeholder block (discreet centered text) */
-.placeholder-block {
-  display: grid;
-  place-items: center;
-  min-height: 120px;
-  color: var(--muted-color);
-  font-size: 12px;
-  border: 1px dashed var(--border-color);
-  border-radius: 8px;
-  background: var(--surface-bg);
-}
-
-/* Demo blocks for width helpers */
-.demo-wide,
-.demo-full-width {
-  display: grid;
-  place-items: center;
-  min-height: 150px;
-  color: var(--muted-color);
-  font-size: 12px;
-  border: 1px dashed var(--border-color);
-  border-radius: 8px;
-  background: var(--surface-bg);
-}
-
-
-.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; }
 
-/*
-.code-block {
-  background: rgba(120, 120, 120, 0.5);
-  border: 1px solid var(--border-color);
-  border-radius: 6px;
-  padding: var(--spacing-3);
-  font-size: 14px;
-  overflow: auto;
-}
-*/
-
-/* ============================================================================ */
-/* Media / Figures */
-/* ============================================================================ */
-img,
-picture {
-  max-width: 100%;
-  height: auto;
-  display: block;
-  position: relative;
-  z-index: var(--z-elevated);
-}
-
-/* Inline feature tags */
-.tag-list { display: flex; flex-wrap: wrap; gap: 8px; margin: 8px 0 16px; }
-.tag {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  padding: 4px 8px;
-  font-size: 12px;
-  line-height: 1;
-  border-radius: 999px;
-  background: var(--surface-bg);
-  border: 1px solid var(--border-color);
-  color: var(--text-color);
-}
-[data-theme="dark"] .tag { background: #1a1f27; border-color: rgba(255,255,255,.15); }
-
-
-
-/* ============================================================================ */
-/* Figures, captions & image credits */
-/* ============================================================================ */
-figure { margin: 12px 0; }
-figcaption { text-align: left; font-size: 0.9rem; color: var(--muted-color); margin-top: 6px; }
-.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) */
-/* ============================================================================ */
-button, .button {
-  appearance: none;
-  background: linear-gradient(15deg, var(--primary-color) 0%, var(--primary-color-hover) 35%);
-  color: white!important;
-  border: 1px solid transparent;
-  border-radius: 6px;
-  padding: 8px 12px;
-  font-size: 14px;
-  line-height: 1;
-  cursor: pointer;
-  display: inline-block;
-  transition: background-color .15s ease, border-color .15s ease, box-shadow .15s ease, transform .02s ease;
-}
-/* Icon-only buttons: equal X/Y padding */
-button:has(> svg:only-child),
-.button:has(> svg:only-child) {
-  padding: 8px !important;
-}
-button:hover, .button:hover {
-  filter: brightness(96%);
-}
-button:active, .button:active {
-  transform: translateY(1px);
-}
-button:focus-visible, .button:focus-visible {
-  outline: none;
-}
-button:disabled, .button:disabled {
-  opacity: .6;
-  cursor: not-allowed;
-}
-
-/* Ghost/Muted button: subtle outline, primary color text/border */
-.button--ghost {
-  background: transparent !important;
-  color: var(--primary-color) !important;
-  border-color: var(--primary-color) !important;
-}
-.button--ghost:hover {
-  color: var(--primary-color-hover) !important;
-  border-color: var(--primary-color-hover) !important;
-  filter: none;
-}
-
-.button-group .button {
-  margin: 5px;
-}
-
-/* ============================================================================ */
-/* Print styles */
-/* ========================================================================= */
-@media print {
-  html, body { background: #fff; }
-  /* Margins handled by Playwright; avoid extra global margins */
-  body { margin: 0; }
-
-  /* Keep the banner (hero), hide non-essential UI elements */
-  #theme-toggle { display: none !important; }
-
-  /* Links: remove underline */
-  .content-grid main a { text-decoration: none; border-bottom: 1px solid rgba(0,0,0,.2); }
-
-  /* Avoid breaks inside complex blocks */
-  .content-grid main pre,
-  .content-grid main blockquote,
-  .content-grid main table,
-  .content-grid main figure { break-inside: avoid; page-break-inside: avoid; }
-
-  /* Soft page breaks around main headings */
-  .content-grid main h2 { page-break-before: auto; page-break-after: avoid; break-after: avoid-page; }
-
-  /* Small icon labels not needed when printing */
-  .code-lang-chip { display: none !important; }
-
-  /* Adjust more contrasty colors for print */
-  :root {
-    --border-color: rgba(0,0,0,.2);
-    --link-underline: rgba(0,0,0,.3);
-    --link-underline-hover: rgba(0,0,0,.4);
-  }
-
-  /* Force single column to reduce widows/orphans and awkward breaks */
-  .content-grid { grid-template-columns: 1fr !important; }
-  .toc, .right-aside, .toc-mobile { display: none !important; }
-  main > nav:first-of-type { display: none !important; }
-
-  /* Avoid page breaks inside complex visual blocks */
-  .hero,
-  .hero-banner,
-  .d3-galaxy,
-  .d3-galaxy svg,
-  .html-embed__card,
-  .html-embed__card,
-  .js-plotly-plot,
-  figure,
-  pre,
-  table,
-  blockquote,
-  .wide,
-  .full-width {
-    break-inside: avoid;
-    page-break-inside: avoid;
-  }
-  /* Prefer keeping header+lead together */
-  .hero { page-break-after: avoid; }
-}
-
 .muted {
   color: var(--muted-color);
 }
 
-
+[data-footnote-ref] {
+  margin-left: 4px;
+}

app/src/styles/_layout.css

@@ -1,9 +1,6 @@
 /* ============================================================================ */
-/* Layout – 3-column grid (TOC / Article / Aside) */
+/* Layout – 3-column grid (Table of Contents / Article / Aside) */
 /* ============================================================================ */
-:root {
-  --content-padding-x: 16px;
-}
 
 .content-grid {
   max-width: 1280px;
@@ -16,75 +13,27 @@
   align-items: start;
 }
 
-.content-grid > main { max-width: 100%;
+.content-grid > main {
+  max-width: 100%;
   margin: 0;
   padding: 0;
 }
 
-@media (max-width: 1100px) {
-  .content-grid { overflow: hidden; }
+@media (max-width: var(--bp-content-collapse)) {
+  .content-grid {
+    overflow: hidden;
+  }
 }
 
-/* TOC (left column) */
-.toc { position: sticky; top: 24px; }
-.toc nav { border-left: 1px solid var(--border-color); padding-left: 16px; font-size: 13px; }
-.toc .title { font-weight: 600; font-size: 14px; margin-bottom: 8px; }
-
-/* Hide in-article TOC (duplicated by sticky aside) */
-main > nav:first-of-type { display: none; }
-
-/* TOC look & feel */
-.toc nav ul { margin: 0 0 6px; padding-left: 1em; }
-.toc nav li { list-style: none; margin: .25em 0; }
-.toc nav a { color: var(--text-color); text-decoration: none; border-bottom: none; }
-.toc nav > ul > li > a { font-weight: 700; }
-.toc nav a:hover { text-decoration: underline solid var(--muted-color); }
-.toc nav a.active { text-decoration: underline; }
-
-/* Mobile TOC accordion */
-.toc-mobile { display: none; margin: 8px 0 16px; }
-.toc-mobile > summary { cursor: pointer; list-style: none; padding: 8px 12px; border: 1px solid var(--border-color); border-radius: 8px; color: var(--text-color); font-weight: 600; }
-.toc-mobile[open] > summary { border-bottom-left-radius: 0; border-bottom-right-radius: 0; }
-.toc-mobile nav { border-left: none; padding: 10px 12px; font-size: 14px; border: 1px solid var(--border-color); border-top: none; border-bottom-left-radius: 8px; border-bottom-right-radius: 8px; }
-.toc-mobile nav ul { margin: 0 0 6px; padding-left: 1em; }
-.toc-mobile nav li { list-style: none; margin: .25em 0; }
-.toc-mobile nav a { color: var(--text-color); text-decoration: none; border-bottom: none; }
-.toc-mobile nav > ul > li > a { font-weight: 700; }
-.toc-mobile nav a:hover { text-decoration: underline solid var(--muted-color); }
-.toc-mobile nav a.active { text-decoration: underline; }
-
-/* Right aside (notes) */
-.right-aside { position: sticky; top: 24px; }
-.right-aside .aside-card { background: var(--surface-bg); border: 1px solid var(--border-color); border-radius: 8px; padding: 10px; margin-bottom: 10px; font-size: 0.9rem; color: var(--text-color); }
 
 /* Responsive – collapse to single column */
-@media (max-width: 1100px) {
-  .content-grid { grid-template-columns: 1fr; }
-  .toc { position: static; display: none; }
-  .toc-mobile { display: block; }
-  .right-aside { display: none; }
-  main > nav:first-of-type { display: block; }
-}
-
-
-
-.margin-aside { position: relative; margin: 12px 0; }
+@media (max-width: var(--bp-content-collapse)) {
+  .content-grid {
+    grid-template-columns: 1fr;
+  }
 
-.margin-aside__aside {
-  position: absolute;
-  top: 0;
-  right: -260px; /* push into the right grid column (width 260 + gap 32) */
-  width: 260px;
-  border-radius: 8px;
-  padding: 0 30px;
-  font-size: 0.9rem;
-  color: var(--muted-color);
-}
-@media (max-width: 1100px) {
-  .margin-aside__aside {
-    position: static;
-    width: auto;
-    margin-top: 8px;
+  main > nav:first-of-type {
+    display: block;
   }
 }
 
@@ -92,22 +41,18 @@ main > nav:first-of-type { display: none; }
 /* ============================================================================ */
 /* Width helpers – slightly wider than main column, and full-width to viewport */
 /* ---------------------------------------------------------------------------- */
-/* Usage in MDX: */
-/* <div className="wide"> ... </div> */
-/* <div className="full-width"> ... </div> */
-/* These center the content relative to the viewport while keeping it responsive. */
-/* */
-/* Notes: */
-/* - These helpers work inside the main article column; they break out visually */
-/*   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-width { box-sizing: border-box; position: relative; z-index: var(--z-elevated); }
+.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 */
   width: min(1100px, 100vw - 32px);
-  margin-left: 50%;
+  margin-left: calc(50% + var(--content-padding-x) * 2);
   transform: translateX(-50%);
 }
 
@@ -118,7 +63,7 @@ main > nav:first-of-type { display: none; }
   margin-right: calc(50% - 50vw);
 }
 
-@media (max-width: 1100px) {
+@media (max-width: var(--bp-content-collapse)) {
   .wide,
   .full-width {
     width: 100%;

app/src/styles/_print.css

@@ -0,0 +1,66 @@
+
+/* ============================================================================ */
+/* Print styles */
+/* ========================================================================= */
+@media print {
+    html, body { background: #fff; }
+    /* Margins handled by Playwright; avoid extra global margins */
+    body { margin: 0; }
+  
+    /* Keep the banner (hero), hide non-essential UI elements */
+    #theme-toggle { display: none !important; }
+  
+    /* Links: remove underline */
+    .content-grid main a { text-decoration: none; border-bottom: 1px solid rgba(0,0,0,.2); }
+  
+    /* Avoid breaks inside complex blocks */
+    .content-grid main pre,
+    .content-grid main blockquote,
+    .content-grid main table,
+    .content-grid main figure { break-inside: avoid; page-break-inside: avoid; }
+  
+    /* Soft page breaks around main headings */
+    .content-grid main h2 { page-break-before: auto; page-break-after: avoid; break-after: avoid-page; }
+  
+    /* Small icon labels not needed when printing */
+    .code-lang-chip { display: none !important; }
+  
+    /* Adjust more contrasty colors for print */
+    :root {
+      --border-color: rgba(0,0,0,.2);
+      --link-underline: rgba(0,0,0,.3);
+      --link-underline-hover: rgba(0,0,0,.4);
+    }
+  
+    /* Force single column to reduce widows/orphans and awkward breaks */
+    .content-grid { grid-template-columns: 1fr !important; }
+    .table-of-contents, .right-aside, .table-of-contents-mobile { display: none !important; }
+    main > nav:first-of-type { display: none !important; }
+  
+    /* Avoid page breaks inside complex visual blocks */
+    .hero,
+    .hero-banner,
+    .d3-galaxy,
+    .d3-galaxy svg,
+    .html-embed__card,
+    .html-embed__card,
+    .js-plotly-plot,
+    figure,
+    pre,
+    table,
+    blockquote,
+    .wide,
+    .full-width {
+      break-inside: avoid;
+      page-break-inside: avoid;
+    }
+    /* Prefer keeping header+lead together */
+    .hero { page-break-after: avoid; }
+  }
+  
+  .muted {
+    color: var(--muted-color);
+  }
+  
+  
+  

app/src/styles/_reset.css

@@ -0,0 +1,13 @@
+html { box-sizing: border-box; }
+*, *::before, *::after { box-sizing: inherit; }
+body { margin: 0; font-family: var(--default-font-family); color: var(--text-color); }
+audio { display: block; width: 100%; }
+
+img,
+picture {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  position: relative;
+  z-index: var(--z-elevated);
+}

app/src/styles/_variables.css

@@ -1,28 +1,34 @@
 /* ============================================================================ */
-/* Theme Variables (inspired by Distill) */
+/* Design Tokens */
 /* ============================================================================ */
 :root {
-  /* Neutral palette */
+  /* Neutrals */
   --neutral-600: rgb(107, 114, 128);
   --neutral-400: rgb(185, 185, 185);
   --neutral-300: rgb(228, 228, 228);
   --neutral-200: rgb(245, 245, 245);
 
-  /* Primary brand color */
-  --primary-color: rgb(232, 137, 171);
-  --primary-color-hover: rgb(212, 126, 156);
+  --default-font-family: Source Sans Pro,ui-sans-serif,system-ui,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
+
+  /* Brand (OKLCH base + derived states) */
+  --primary-base: oklch(0.75 0.12 340);
+  --primary-color: var(--primary-base);
+  --primary-color-hover: oklch(from var(--primary-color) calc(l - 0.05) c h);
+  --primary-color-active: oklch(from var(--primary-color) calc(l - 0.10) c h);
   --on-primary: #ffffff;
 
+  /* Text & Surfaces */
   --text-color: rgba(0,0,0,.85);
   --muted-color: rgba(0,0,0,.6);
   --border-color: rgba(0,0,0,.1);
-
-  /* Light surfaces & links */
   --surface-bg: #fafafa;
   --code-bg: #f6f8fa;
-  --link-underline: var(--primary-color); /* based on --primary-color */
+
+  /* Links */
+  --link-underline: var(--primary-color);
   --link-underline-hover: var(--primary-color-hover);
 
+  /* Spacing scale */
   --spacing-1: 8px;
   --spacing-2: 12px;
   --spacing-3: 16px;
@@ -34,32 +40,63 @@
   --spacing-9: 64px;
   --spacing-10: 72px;
 
-  /* Palettes config */
-  --palette-count: 6; /* default number of colors per palette */
+  /* Breakpoints */
+  --bp-xs: 480px;
+  --bp-sm: 640px;
+  --bp-md: 768px;
+  --bp-lg: 1024px;
+  --bp-content-collapse: 1100px; /* layout single-column */
+  --bp-xl: 1280px;
+
+  /* Layout */
+  --content-padding-x: 16px; /* default page gutter */
+  --block-spacing-y: var(--spacing-4); /* default vertical spacing between block components */
 
-  /* 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 */
+  /* Config */
+  --palette-count: 6;
+
+  /* Button tokens */
+  --button-radius: 6px;
+  --button-padding-x: 12px;
+  --button-padding-y: 8px;
+  --button-font-size: 14px;
+  --button-icon-padding: 8px;
+  /* Big button */
+  --button-big-padding-x: 16px;
+  --button-big-padding-y: 12px;
+  --button-big-font-size: 16px;
+  --button-big-icon-padding: 12px;
+
+  /* Table tokens */
+  --table-border-radius: 8px;
+  --table-header-bg: oklch(from var(--surface-bg) calc(l - 0.02) c h);
+  --table-row-odd-bg: oklch(from var(--surface-bg) calc(l - 0.01) c h);
+
+  /* Z-index */
+  --z-base: 0;
+  --z-content: 1;
+  --z-elevated: 10;
+  --z-overlay: 1000;
+  --z-modal: 1100;
+  --z-tooltip: 1200;
 }
-/* Theme tokens for dark mode */
+
+/* ============================================================================ */
+/* Dark Theme Overrides */
+/* ============================================================================ */
 [data-theme="dark"] {
   --text-color: rgba(255,255,255,.9);
   --muted-color: rgba(255,255,255,.7);
   --border-color: rgba(255,255,255,.15);
   --surface-bg: #12151b;
   --code-bg: #12151b;
-  /* Primary in dark mode */
-  --primary-color: rgb(232, 137, 171);
-  --primary-color-hover: rgb(212, 126, 156);
+
+  /* Primary (lower L in dark) */
+  --primary-color: oklch(from var(--primary-base) calc(l - 0.08) c h);
+  --primary-color-hover: oklch(from var(--primary-color) calc(l - 0.05) c h);
+  --primary-color-active: oklch(from var(--primary-color) calc(l - 0.10) c h);
   --on-primary: #0f1115;
 
   color-scheme: dark;
   background: #0f1115;
-}
-
-
-
+}

app/src/styles/components/_button.css

@@ -0,0 +1,58 @@
+button, .button {
+    appearance: none;
+    background: linear-gradient(15deg, var(--primary-color) 0%, var(--primary-color-hover) 35%);
+    color: white!important;
+    border: 1px solid transparent;
+    border-radius: var(--button-radius);
+    padding: var(--button-padding-y) var(--button-padding-x);
+    font-size: var(--button-font-size);
+    line-height: 1;
+    cursor: pointer;
+    display: inline-block;
+    text-decoration: none;
+    transition: background-color .15s ease, border-color .15s ease, box-shadow .15s ease, transform .02s ease;
+  }
+  /* Icon-only buttons: equal X/Y padding */
+  button:has(> svg:only-child),
+  .button:has(> svg:only-child) {
+    padding: var(--button-icon-padding) !important;
+  }
+  button:hover, .button:hover {
+    filter: brightness(96%);
+  }
+  button:active, .button:active {
+    transform: translateY(1px);
+  }
+  button:focus-visible, .button:focus-visible {
+    outline: none;
+  }
+  button:disabled, .button:disabled {
+    opacity: .6;
+    cursor: not-allowed;
+  }
+  
+  /* Ghost/Muted button: subtle outline, primary color text/border */
+  .button--ghost {
+    background: transparent !important;
+    color: var(--primary-color) !important;
+    border-color: var(--primary-color) !important;
+  }
+  .button--ghost:hover {
+    color: var(--primary-color-hover) !important;
+    border-color: var(--primary-color-hover) !important;
+    filter: none;
+  }
+  
+  /* Big button: larger padding and font size */
+  .button--big {
+    padding: var(--button-big-padding-y) var(--button-big-padding-x) !important;
+    font-size: var(--button-big-font-size);
+  }
+  .button--big:has(> svg:only-child) {
+    padding: var(--button-big-icon-padding) !important;
+  }
+  
+  .button-group .button {
+    margin: 5px;
+  }
+  

app/src/styles/components/_code.css

@@ -1,8 +1,10 @@
+/* ============================================================================ */
+/* Inline code */
+/* ============================================================================ */
 code {
   font-size: 14px;
   font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
   background-color: var(--code-bg);
-  padding: 0.2em 0.4em;
   border-radius: 0.3em;
   border: 1px solid var(--border-color);
   color: var(--text-color);
@@ -10,56 +12,129 @@ code {
   line-height: 1.5;
 }
 
-/* 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; }
+/* ============================================================================ */
+/* Shiki code blocks */
+/* ============================================================================ */
+.astro-code {
+  position: relative;
+  border: 1px solid var(--border-color);
+  border-radius: 6px;
+  padding: 0;
+  font-size: 14px;
+  --code-gutter-width: 2.5em;
+}
+
+/* Shared sizing & horizontal scroll for code containers */
+.astro-code,
+section.content-grid pre {
+  overflow-x: auto;
+  width: 100%;
+  max-width: 100%;
+  box-sizing: border-box;
+  -webkit-overflow-scrolling: touch;
+  padding: 0;
+}
+
+/* Consistent vertical spacing for code blocks */
+.astro-code,
+section.content-grid pre {
+  margin: 0 0 var(--block-spacing-y);
+}
 
-/* 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; }
-section.content-grid pre { overflow-x: auto; width: 100%; max-width: 100%; box-sizing: border-box; -webkit-overflow-scrolling: touch; padding: 0; }
-section.content-grid pre code { display: inline-block; min-width: 100%; }
+section.content-grid pre { margin: 0; }
+
+section.content-grid pre code {
+  display: inline-block;
+  min-width: 100%;
+}
 
-/* Wrap long lines on mobile to avoid overflow (URLs, etc.) */
 /* Wrap long lines only on small screens to prevent layout overflow */
-@media (max-width: 1100px) {
+@media (max-width: var(--bp-content-collapse)) {
   .astro-code,
-  section.content-grid pre { white-space: pre-wrap; overflow-wrap: anywhere; word-break: break-word; }
-  section.content-grid pre code { white-space: pre-wrap; display: block; min-width: 0; }
+  section.content-grid pre {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    word-break: break-word;
+  }
+
+  section.content-grid pre code {
+    white-space: pre-wrap;
+    display: block;
+    min-width: 0;
+  }
 }
 
-html[data-theme='light'] .astro-code { background-color: var(--code-bg); }
-
-html[data-theme='dark'] .astro-code { background-color: var(--shiki-dark-bg); }
+/* Themes */
+[data-theme='light'] .astro-code { background-color: var(--code-bg); }
 
 /* Apply token color from per-span vars exposed by Shiki dual themes */
-html[data-theme='light'] .astro-code span { color: var(--shiki-light) !important; }
-html[data-theme='dark'] .astro-code span { color: var(--shiki-dark) !important; }
+[data-theme='light'] .astro-code span { color: var(--shiki-light) !important; }
+[data-theme='dark'] .astro-code span { color: var(--shiki-dark) !important; }
 
-/* Token color remapping using Shiki CSS variables on the wrapper */
 /* Optional: boost contrast for light theme */
-html[data-theme='light'] .astro-code {
+[data-theme='light'] .astro-code {
   --shiki-foreground: #24292f;
   --shiki-background: #ffffff;
 }
 
 /* Line numbers for Shiki-rendered code blocks */
-.astro-code code { counter-reset: astro-code-line; display: block; background: none; border: none;  }
-.astro-code .line { display: inline-block; position: relative; padding-left: calc(var(--code-gutter-width) + var(--spacing-1)); min-height: 1.25em; }
-.astro-code .line::before { counter-increment: astro-code-line; content: counter(astro-code-line); position: absolute; left: 0; top: 0; bottom: 0; width: calc(var(--code-gutter-width)); text-align: right; color: var(--muted-color); opacity: .30; user-select: none; padding-right: var(--spacing-2); border-right: 1px solid var(--border-color); }
+.astro-code code {
+  counter-reset: astro-code-line;
+  display: block;
+  background: none;
+  border: none;
+}
+
+.astro-code .line {
+  display: inline-block;
+  position: relative;
+  padding-left: calc(var(--code-gutter-width) + var(--spacing-1));
+  min-height: 1.25em;
+}
+
+.astro-code .line::before {
+  counter-increment: astro-code-line;
+  content: counter(astro-code-line);
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: calc(var(--code-gutter-width));
+  text-align: right;
+  color: var(--muted-color);
+  opacity: .3;
+  user-select: none;
+  padding-right: var(--spacing-2);
+  border-right: 1px solid var(--border-color);
+}
+
 .astro-code .line:empty::after { content: "\00a0"; }
+
 /* Hide trailing empty line added by parsers */
 .astro-code code > .line:last-child:empty { display: none; }
 
-/* (Removed JS fallback chip: label handled via CSS in _base.css) */
-
-/* Rehype-injected wrapper for non-Shiki pre blocks */
+/* ============================================================================ */
+/* Non-Shiki pre wrapper (rehype) */
+/* ============================================================================ */
 .code-card { position: relative; }
+
 .code-card .code-copy {
-  position: absolute; top: 6px; right: 6px; z-index: 3; padding: 6px 12px; border: none;
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  z-index: 3;
+  padding: 6px 12px;
+  border: none;
+}
+
+.code-card .code-copy svg {
+  width: 16px;
+  height: 16px;
+  display: block;
+  fill: currentColor;
 }
-.code-card .code-copy svg { width: 16px; height: 16px; display: block; fill: currentColor; }
-.code-card pre { margin: 0; margin-bottom: var(--spacing-1);}
+
+.code-card pre { margin: 0 0 var(--spacing-1); }
 
 /* Discreet filetype/language label shown under the Copy button */
 .code-card::after {
@@ -78,15 +153,18 @@ html[data-theme='light'] .astro-code {
 /* When no copy button (single-line), keep the label in the top-right corner */
 .code-card.no-copy::after { top: 8px; right: 8px; }
 
-
-
-/* Overrides inside Accordion: remove padding and border on code containers */
+/* ============================================================================ */
+/* Contextual overrides */
+/* ============================================================================ */
+/* Inside Accordions: remove padding and border on code containers */
 .accordion .astro-code { padding: 0; border: none; }
 
-/* Language/extension vignette for Shiki blocks (bottom-right, discreet) */
+/* ============================================================================ */
+/* Language/extension vignette (bottom-right, discreet) */
+/* ============================================================================ */
 .astro-code::after {
   content: attr(data-language);
-  position: absolute;
+  position: sticky;
   right: 0;
   bottom: 0;
   font-size: 10px;
@@ -96,7 +174,7 @@ html[data-theme='light'] .astro-code {
   background: var(--surface-bg);
   border-top: 1px solid var(--border-color);
   border-left: 1px solid var(--border-color);
-  opacity: 0.5;
+  opacity: 1;
   border-radius: 8px 0 0 0; /* round only top-left */
   padding: 4px 6px;
   pointer-events: none;

app/src/styles/components/_footer.css

@@ -1,56 +0,0 @@
-.distill-footer { contain: layout style; font-size: 0.8em; line-height: 1.7em; margin-top: 60px; margin-bottom: 0; border-top: 1px solid rgba(0, 0, 0, 0.1); color: rgba(0, 0, 0, 0.5); }
-.footer-inner { max-width: 1280px; margin: 0 auto; padding: 60px 16px 48px; display: grid; grid-template-columns: 220px minmax(0, 680px) 260px; gap: 32px; align-items: start; }
-
-/* Use the parent grid (3 columns like .content-grid) */
-.citation-block,
-.references-block { display: contents; }
-.citation-block > h3,
-.references-block > h3 { grid-column: 1; font-size: 15px; margin: 0; text-align: right; padding-right: 30px; }
-.citation-block > :not(h3),
-.references-block > :not(h3) { grid-column: 2; }
-@media (max-width: 1100px) {
-  .footer-inner { grid-template-columns: 1fr; gap: 16px; }
-  .footer-inner > h3 { grid-column: auto; margin-top: 16px; }
-}
-.citation-block h3 { margin: 0 0 8px; }
-.citation-block h4 { margin: 16px 0 8px; font-size: 14px; text-transform: uppercase; color: var(--muted-color); }
-
-.citation-block p, .references {
-  margin-top:0;
-}
-
-/* Distill-like appendix citation styling */
-.citation {
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-  font-size: 11px;
-  line-height: 15px;
-  border-left: 1px solid rgba(0, 0, 0, 0.1);
-  padding-left: 18px;
-  border: 1px solid rgba(0,0,0,0.1);
-  background: rgba(0, 0, 0, 0.02);
-  padding: 10px 18px;
-  border-radius: 3px;
-  color: rgba(150, 150, 150, 1);
-  overflow: hidden;
-  margin-top: -12px;
-  white-space: pre-wrap;
-  word-wrap: break-word;
-}
-
-.citation a { color: rgba(0, 0, 0, 0.6); text-decoration: underline; }
-
-.citation.short { margin-top: -4px; }
-
-.references-block h3 { margin: 0; }
-
-/* Distill-like list styling for references/footnotes */
-.references-block ol { padding: 0 0 0 15px; }
-@media (min-width: 768px) { .references-block ol { padding: 0 0 0 30px; margin-left: -30px; } }
-.references-block li { margin-bottom: 1em; }
-.references-block a { color: rgba(0, 0, 0, 0.6); }
-
-@media (max-width: 1100px) {
-  .footer-inner { display: block; padding: 40px 16px; }
-}
-
-

app/src/styles/components/_poltly.css

@@ -1,44 +0,0 @@
-/* ============================================================================ */
-/* Plotly – fragments & controls */
-/* ============================================================================ */
-.html-embed__card svg text { fill: var(--text-color) !important; }
-.html-embed__card label { color: var(--text-color) !important; }
-.plotly-graph-div { width: 100% !important; min-height: 320px; }
-@media (max-width: 768px) { .plotly-graph-div { min-height: 260px; } }
-[id^="plot-"] { display: flex; flex-direction: column; align-items: center; gap: 15px; }
-.plotly_caption { font-style: italic; margin-top: 10px; }
-.plotly_controls { display: flex; flex-wrap: wrap; justify-content: center; gap: 30px; }
-.plotly_input_container { display: flex; align-items: center; flex-direction: column; gap: 10px; }
-.plotly_input_container > select { padding: 2px 4px; line-height: 1.5em; text-align: center; border-radius: 4px; font-size: 12px; background-color: var(--neutral-200); outline: none; border: 1px solid var(--neutral-300); }
-.plotly_slider { display: flex; align-items: center; gap: 10px; }
-.plotly_slider > input[type="range"] { -webkit-appearance: none; appearance: none; height: 2px; background: var(--neutral-400); border-radius: 5px; outline: none; }
-.plotly_slider > input[type="range"]::-webkit-slider-thumb { -webkit-appearance: none; width: 18px; height: 18px; border-radius: 50%; background: var(--primary-color); cursor: pointer; }
-.plotly_slider > input[type="range"]::-moz-range-thumb { width: 18px; height: 18px; border-radius: 50%; background: var(--primary-color); cursor: pointer; }
-.plotly_slider > span { font-size: 14px; line-height: 1.6em; min-width: 16px; }
-
-/* ---------------------------------------------------------------------------- */
-/* Dark mode overrides for Plotly readability */
-/* ---------------------------------------------------------------------------- */
-[data-theme="dark"] .html-embed__card .xaxislayer-above text,
-[data-theme="dark"] .html-embed__card .yaxislayer-above text,
-[data-theme="dark"] .html-embed__card .infolayer text,
-[data-theme="dark"] .html-embed__card .legend text,
-[data-theme="dark"] .html-embed__card .annotation text,
-[data-theme="dark"] .html-embed__card .colorbar text,
-[data-theme="dark"] .html-embed__card .hoverlayer text { fill: #fff !important; }
-
-[data-theme="dark"] .html-embed__card .xaxislayer-above path,
-[data-theme="dark"] .html-embed__card .yaxislayer-above path,
-[data-theme="dark"] .html-embed__card .xlines-above,
-[data-theme="dark"] .html-embed__card .ylines-above { stroke: rgba(255,255,255,.35) !important; }
-
-[data-theme="dark"] .html-embed__card .gridlayer path { stroke: rgba(255,255,255,.15) !important; }
-
-/* Legend and hover backgrounds */
-[data-theme="dark"] .html-embed__card .legend rect.bg { fill: rgba(0,0,0,.25) !important; stroke: rgba(255,255,255,.2) !important; }
-[data-theme="dark"] .html-embed__card .hoverlayer .bg { fill: rgba(0,0,0,.8) !important; stroke: rgba(255,255,255,.2) !important; }
-
-/* Colorbar background (keep gradient intact) */
-[data-theme="dark"] .html-embed__card .colorbar .cbbg { fill: rgba(0,0,0,.25) !important; stroke: rgba(255,255,255,.2) !important; }
-
-

app/src/styles/components/_table.css

@@ -0,0 +1,95 @@
+.content-grid main table {
+    border-collapse: collapse;
+    table-layout: auto;
+    margin: 0;
+  }
+  .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 thead th {
+    border-bottom: 1px solid var(--border-color);
+  }
+  .content-grid main thead th {
+    background: var(--table-header-bg);
+    padding-top: 10px;
+    padding-bottom: 10px;
+    font-weight: 600;
+  }
+  
+  .content-grid main hr {
+    border: none;
+    border-bottom: 1px solid var(--border-color);
+    margin: var(--spacing-5) 0;
+  }
+  
+  /* Scroll wrapper: keeps table 100% width but enables horizontal scroll when needed */
+  .content-grid main .table-scroll {
+    width: 100%;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    border: 1px solid var(--border-color);
+    border-radius: var(--table-border-radius);
+    background: var(--surface-bg);
+    margin: 0 0 var(--block-spacing-y);
+  }
+  .content-grid main .table-scroll > table {
+    width: fit-content;
+    min-width: 100%;
+    max-width: none;
+  }
+  /* Vertical dividers between columns (no outer right border) */
+  .content-grid main .table-scroll > table th,
+  .content-grid main .table-scroll > table td {
+    border-right: 1px solid var(--border-color);
+  }
+  .content-grid main .table-scroll > table th:last-child,
+  .content-grid main .table-scroll > table td:last-child {
+    border-right: none;
+  }
+  .content-grid main .table-scroll > table thead th:first-child {
+    border-top-left-radius: var(--table-border-radius);
+  }
+  .content-grid main .table-scroll > table thead th:last-child {
+    border-top-right-radius: var(--table-border-radius);
+  }
+  .content-grid main .table-scroll > table tbody tr:last-child td:first-child {
+    border-bottom-left-radius: var(--table-border-radius);
+  }
+  .content-grid main .table-scroll > table tbody tr:last-child td:last-child {
+    border-bottom-right-radius: var(--table-border-radius);
+  }
+  /* Zebra striping for odd rows */
+  .content-grid main .table-scroll > table tbody tr:nth-child(odd) td {
+    background: var(--table-row-odd-bg);
+  }
+  /* Remove bottom border on last row */
+  .content-grid main .table-scroll > table tbody tr:last-child td {
+    border-bottom: none;
+  }
+  
+  /* Accordion context: remove outer borders/radius and fit content flush */
+  .accordion .accordion__content .table-scroll {
+    border: none;
+    border-radius: 0;
+    margin: 0;
+  }
+  .accordion .accordion__content .table-scroll > table thead th:first-child,
+  .accordion .accordion__content .table-scroll > table thead th:last-child,
+  .accordion .accordion__content .table-scroll > table tbody tr:last-child td:first-child,
+  .accordion .accordion__content .table-scroll > table tbody tr:last-child td:last-child {
+    border-radius: 0;
+  }
+  
+  /* Fallback for browsers without fit-content support */
+  @supports not (width: fit-content) {
+    .content-grid main .table-scroll > table {
+      width: max-content;
+      min-width: 100%;
+    }
+  }
+  

app/src/styles/components/_tag.css

@@ -0,0 +1,14 @@
+.tag-list { display: flex; flex-wrap: wrap; gap: 8px; margin: 8px 0 16px; }
+
+.tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 10px 16px;
+  font-size: 12px;
+  line-height: 1;
+  border-radius: 100px;
+  background: var(--surface-bg);
+  border: 1px solid var(--border-color);
+  color: var(--text-color);
+}

app/src/styles/global.css

@@ -1,56 +1,27 @@
 @import './_variables.css';
+@import './_reset.css';
 @import './_base.css';
 @import './_layout.css';
-@import './components/_footer.css';
+@import './_print.css';
 @import './components/_code.css';
-@import './components/_poltly.css';
+@import './components/_button.css';
+@import './components/_table.css';
+@import './components/_tag.css';
 
-/* Dark-mode form tweak */
-[data-theme="dark"] .plotly_input_container > select { background-color: #1a1f27; border-color: var(--border-color); color: var(--text-color); }
-
-[data-theme="dark"] .html-embed__card:not(.is-frameless) { background: #12151b; border-color: rgba(255,255,255,.15); }
-[data-theme="dark"] .right-aside .aside-card { background: #12151b; border-color: rgba(255,255,255,.15); }
-[data-theme="dark"] .content-grid main pre { background: #12151b; border-color: rgba(255,255,255,.15); }
-[data-theme="dark"] .toc nav { border-left-color: rgba(255,255,255,.15); }
-[data-theme="dark"] .distill-footer { border-top-color: rgba(255,255,255,.15); color: rgba(200,200,200,.8); }
-[data-theme="dark"] .citation { background: rgba(255,255,255,0.04); border-color: rgba(255,255,255,.15); color: rgba(200,200,200,1); }
-[data-theme="dark"] .citation a { color: rgba(255,255,255,0.75); }
-
-/* Opt-in zoomable images */
-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;
+.demo-wide,
+.demo-full-width {
+  display: grid;
+  place-items: center;
+  min-height: 150px;
+  color: var(--muted-color);
+  font-size: 12px;
+  border: 1px dashed var(--border-color);
+  border-radius: 8px;
+  background: var(--surface-bg);
+  margin-bottom: var(--block-spacing-y);
 }
-.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) */
-/* ============================================================================ */
-#theme-toggle { display: inline-flex; align-items: center; gap: 8px; border: none; background: transparent; padding: 6px 10px; border-radius: 8px; cursor: pointer; margin: 12px 16px; color: var(--text-color) !important; }
-#theme-toggle .icon.dark { display: none; }
-[data-theme="dark"] #theme-toggle .icon.light { display: none; }
-[data-theme="dark"] #theme-toggle .icon.dark { display: inline; }
-#theme-toggle .icon { filter: none !important; }
-
 
+.mermaid {
+    background: none!important;
+    margin-bottom: var(--block-spacing-y) !important;
+}