add code output

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

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

app/astro.config.mjs

@@ -11,8 +11,11 @@ import rehypeCitation from 'rehype-citation';
 import rehypeCodeCopy from './plugins/rehype/code-copy.mjs';
 import rehypeReferencesAndFootnotes from './plugins/rehype/post-citation.mjs';
 import remarkIgnoreCitationsInCode from './plugins/remark/ignore-citations-in-code.mjs';
+import remarkDirective from 'remark-directive';
+import remarkOutputContainer from './plugins/remark/output-container.mjs';
 import rehypeRestoreAtInCode from './plugins/rehype/restore-at-in-code.mjs';
 import rehypeWrapTables from './plugins/rehype/wrap-tables.mjs';
+import rehypeWrapOutput from './plugins/rehype/wrap-outputs.mjs';
 // Built-in Shiki (dual themes) — no rehype-pretty-code
 
 // Plugins moved to app/plugins/*
@@ -44,7 +47,9 @@ export default defineConfig({
     remarkPlugins: [
       remarkIgnoreCitationsInCode,
       remarkMath,
-      [remarkFootnotes, { inlineNotes: true }]
+      [remarkFootnotes, { inlineNotes: true }],
+      remarkDirective,
+      remarkOutputContainer
     ],
     rehypePlugins: [
       rehypeSlug,
@@ -57,6 +62,7 @@ export default defineConfig({
       rehypeReferencesAndFootnotes,
       rehypeRestoreAtInCode,
       rehypeCodeCopy,
+      rehypeWrapOutput,
       rehypeWrapTables
     ]
   }

app/plugins/rehype/wrap-outputs.mjs

@@ -0,0 +1,38 @@
+// Wrap plain-text content inside <section class="code-outputs"> into a <pre>
+export default function rehypeWrapOutput() {
+  return (tree) => {
+    const isWhitespace = (value) => typeof value === 'string' && !/\S/.test(value);
+    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 visit = (node) => {
+      if (!node || typeof node !== 'object') return;
+      const children = Array.isArray(node.children) ? node.children : [];
+      if (node.type === 'element' && node.tagName === 'section') {
+        const className = node.properties?.className || [];
+        const classes = Array.isArray(className) ? className : [className].filter(Boolean);
+        if (classes.includes('code-output')) {
+          const meaningful = children.filter((c) => !(c.type === 'text' && isWhitespace(c.value)));
+          if (meaningful.length === 1) {
+            const only = meaningful[0];
+            const isPlainParagraph = only.type === 'element' && only.tagName === 'p' && (only.children || []).every((c) => c.type === 'text');
+            const isPlainText = only.type === 'text';
+            if (isPlainParagraph || isPlainText) {
+              const text = isPlainText ? String(only.value || '') : extractText(only);
+              node.children = [
+                { type: 'element', tagName: 'pre', properties: {}, children: [ { type: 'text', value: text } ] }
+              ];
+            }
+          }
+        }
+      }
+      children.forEach(visit);
+    };
+    visit(tree);
+  };
+}
+
+

app/plugins/remark/output-container.mjs

@@ -0,0 +1,23 @@
+// Transform `:::output ... :::` into a <section class="code-output"> wrapper
+// Requires remark-directive to be applied before this plugin
+
+export default function remarkOutputContainer() {
+  return (tree) => {
+    const visit = (node) => {
+      if (!node || typeof node !== 'object') return;
+
+      if (node.type === 'containerDirective' && node.name === 'output') {
+        node.data = node.data || {};
+        node.data.hName = 'section';
+        node.data.hProperties = { className: ['code-output'] };
+      }
+
+      const children = Array.isArray(node.children) ? node.children : [];
+      for (const child of children) visit(child);
+    };
+
+    visit(tree);
+  };
+}
+
+

app/plugins/remark/outputs-container.mjs

@@ -0,0 +1,23 @@
+// Transform `:::outputs ... :::` into a <section class="code-outputs"> wrapper
+// Requires remark-directive to be applied before this plugin
+
+export default function remarkOutputsContainer() {
+  return (tree) => {
+    const visit = (node) => {
+      if (!node || typeof node !== 'object') return;
+
+      if (node.type === 'containerDirective' && node.name === 'outputs') {
+        node.data = node.data || {};
+        node.data.hName = 'section';
+        node.data.hProperties = { className: ['code-outputs'] };
+      }
+
+      const children = Array.isArray(node.children) ? node.children : [];
+      for (const child of children) visit(child);
+    };
+
+    visit(tree);
+  };
+}
+
+

app/src/components/Accordion.astro

@@ -88,6 +88,10 @@ const wrapperClass = ["accordion", className].filter(Boolean).join(" ");
     border-color: color-mix(in oklab, var(--border-color), var(--primary-color) 20%);
   }
 
+  .accordion[open] .accordion__summary {
+    border-bottom: 1px solid var(--border-color);
+  }
+
   .accordion__summary {
     margin: 0;
     list-style: none;

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

@@ -60,5 +60,5 @@ Picking the right visualization depends on your goal (compare values, show distr
   src={visualPoster}
   alt="Visual Vocabulary: choosing the right chart by task"
   linkHref="https://raw.githubusercontent.com/Financial-Times/chart-doctor/refs/heads/main/visual-vocabulary/poster.png"
-  caption={'Credits <a href="https://www.ft.com/" target="_blank" rel="noopener noreferrer">Financial-Times/chart-doctor</a> <br/>A handy reference to select chart types by purpose — click to enlarge.'}
+  caption={'Credits <a href="https://www.ft.com/" target="_blank" rel="noopener noreferrer">Financial-Times</a> <br/>A handy reference to select chart types by purpose — click to enlarge.'}
 />

app/src/content/chapters/markdown.mdx

@@ -44,7 +44,31 @@ $$
 
 ### Code
 
-Use fenced code blocks with a language for syntax highlighting (e.g., `python`).
+Use inline code with backticks \`...\` or \`\`\` fenced code blocks \`\`\` with a language for syntax highlighting (e.g., \`python\`).
+
+As an example, here is inline code: `greet("Astro")` and below is a block.
+
+
+```python
+def greet(name: str) -> None:
+    print(f"Hello, {name}!")
+```
+
+<Accordion title="Code example">
+````mdx
+`greet("Astro")`
+
+```python
+def greet(name: str) -> None:
+    print(f"Hello, {name}!")
+```
+````
+</Accordion>
+
+
+### Code output
+
+If you want to display the output of a code block, you can use the `:::output` directive. If it's directly below the code block, it will adapt to the code block's styling.
 
 ```python
 def greet(name: str) -> None:
@@ -52,6 +76,16 @@ def greet(name: str) -> None:
 
 greet("Astro")
 ```
+:::output
+Hello, Astro!
+:::
+
+Or it can also be used at a standalone block.
+
+:::output
+Hello i'm a standalone output block.
+:::
+
 
 <Accordion title="Code example">
 ````mdx
@@ -61,6 +95,15 @@ def greet(name: str) -> None:
 
 greet("Astro")
 ```
+:::output
+Hello, Astro!
+:::
+
+Or you can also use it at a standalone block.
+
+:::output
+Hello i'm a standalone outputs block.
+:::
 ````
 </Accordion>
 

app/src/env.d.ts

@@ -2,12 +2,6 @@
 /// <reference types="astro/client" />
 /// <reference types="vite/client" />
 
-interface ImportMetaEnv {
-  readonly PUBLIC_TABLE_OF_CONTENT_AUTO_COLLAPSE?: string | boolean;
-  // Back-compat
-  readonly PUBLIC_TOC_AUTO_COLLAPSE?: string | boolean;
-}
-
 interface ImportMeta {
   readonly env: ImportMetaEnv;
 }

app/src/pages/index.astro

@@ -6,7 +6,6 @@ import Footer from '../components/Footer.astro';
 import ThemeToggle from '../components/ThemeToggle.astro';
 import Seo from '../components/Seo.astro';
 import TableOfContents from '../components/TableOfContents.astro';
-import colorPalettesUrl from '../scripts/color-palettes.js?url';
 // Default OG image served from public/
 const ogDefaultUrl = '/thumb.auto.jpg';
 import 'katex/dist/katex.min.css';
@@ -144,7 +143,7 @@ const licence = (articleFM as any)?.licence ?? (articleFM as any)?.license ?? (a
         } catch {}
       })();
     </script>
-    <script type="module" src={colorPalettesUrl}></script>
+    <script type="module" src="/src/scripts/color-palettes.js"></script>
     
     <!-- TO MANAGE PROPERLY -->
     <script src="https://cdn.plot.ly/plotly-3.0.0.min.js" charset="utf-8"></script>

app/src/styles/components/_code.css

@@ -33,16 +33,17 @@ p code, .note code {
 /* 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;
   margin-bottom: var(--block-spacing-y) !important;
+  overflow: hidden!important;
+  overflow-x: auto;
 }
 
-section.content-grid pre { margin: 0; }
+section.content-grid pre.astro-code { margin: 0; padding: var(--spacing-1) 0; }
 
 section.content-grid pre code {
   display: inline-block;
@@ -193,3 +194,105 @@ section.content-grid pre code {
 
 /* In Accordions, keep same bottom-right placement */
 .accordion .astro-code::after { right: 0; bottom: 0; }
+
+/* ============================================================================ */
+/* Results blocks glued to code blocks */
+/* ============================================================================ */
+.code-output {
+  position: relative;
+  background: oklch(from var(--code-bg) calc(l - 0.005) c h);
+  border: 1px solid var(--border-color);
+  border-radius: 6px;
+  padding: calc(var(--spacing-3) + 6px) var(--spacing-3) var(--spacing-3) var(--spacing-3);
+  margin-top: 0;
+  margin-bottom: var(--block-spacing-y);
+}
+
+/* If immediately following a code container, keep tight visual connection */
+.code-card + .code-output,
+.astro-code + .code-output,
+section.content-grid pre + .code-output {
+  margin-top: 0;
+  border-top: none;
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+  box-shadow: inset 0 8px 12px -12px rgba(0, 0, 0, 0.15);
+
+}
+
+/* Remove bottom margin on code when immediately followed by results */
+.astro-code:has(+ .code-output) {
+  margin-bottom: 0 !important;
+}
+.code-card:has(+ .code-output) .astro-code {
+  margin-bottom: 0 !important;
+}
+section.content-grid pre:has(+ .code-output) {
+  margin-bottom: 0 !important;
+}
+
+/* Remove bottom border radius on code when followed by results */
+.astro-code:has(+ .code-output) {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+.code-card:has(+ .code-output) .astro-code {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+section.content-grid pre:has(+ .code-output) {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+/* Small top-left label */
+.code-output::before {
+  content: "Output";
+  position: absolute;
+  top: 0;
+  right: 0;
+  font-size: 10px;
+  line-height: 1;
+  color: var(--muted-color);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  border-top: none;
+  border-right: none;
+  border-radius: 0 0 0 6px;
+  padding: 10px 10px;
+}
+
+/* Very subtle top shadow so results feels under the code */
+.code-output {
+}
+
+.code-output > :where(*):first-child {
+  margin-top: 0 !important;
+}
+
+.code-output > :where(*):last-child {
+  margin-bottom: 0 !important;
+}
+
+/* ============================================================================ */
+/* Optional filename tag above code blocks */
+/* ============================================================================ */
+.code-filename {
+  display: inline-block;
+  font-size: 12px;
+  line-height: 1;
+  color: var(--muted-color);
+  background: var(--surface-bg);
+  border: 1px solid var(--border-color);
+  border-bottom: none;
+  border-radius: 6px 6px 0 0;
+  padding: 4px 8px;
+  margin: 0;
+}
+
+.code-filename + .code-card .astro-code,
+.code-filename + .astro-code,
+.code-filename + section.content-grid pre {
+  border-top-left-radius: 0;
+  border-top-right-radius: 6px;
+}