update doc

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

@@ -1,231 +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"] };
-"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/scripts/export-pdf.mjs

@@ -168,8 +168,19 @@ async function main() {
   // filename can be provided, else computed from DOM (button) or page title later
   let outFileBase = (args.filename && String(args.filename).replace(/\.pdf$/i, '')) || 'article';
 
-  console.log('> Building Astro site…');
-  await run('npm', ['run', 'build']);
+  // Build only if dist/ does not exist
+  const distDir = resolve(cwd, 'dist');
+  let hasDist = false;
+  try {
+    const st = await fs.stat(distDir);
+    hasDist = st && st.isDirectory();
+  } catch {}
+  if (!hasDist) {
+    console.log('> Building Astro site…');
+    await run('npm', ['run', 'build']);
+  } else {
+    console.log('> Skipping build (dist/ exists)…');
+  }
 
   console.log('> Starting Astro preview…');
   // Start preview in its own process group so we can terminate all children reliably
@@ -413,7 +424,7 @@ async function main() {
           /* Banner centering & visibility */
           .hero .points { mix-blend-mode: normal !important; }
           .d3-galaxy { width: 100% !important; height: 300px; max-width: 980px !important; margin-left: auto !important; margin-right: auto !important; }
-          .d3-galaxy svg { background: var(--surface-bg); width: 100% !important; height: auto !important; }
+          .d3-galaxy svg { width: 100% !important; height: auto !important; }
         ` });
       } catch {}
       await page.pdf({

app/src/content/chapters/components.mdx

@@ -34,12 +34,14 @@ You have to import them in the **.mdx** file you want to use them in.
 | `downloadable`    | No       | Adds a download button to fetch the image file.                                                               
 | `loading="lazy"`       | No       | Lazy loads the image.                                                                                               
 | `caption`              | No       | Adds a caption and credit.                                                                                          
+| `id`              | No       | Adds an `id` to the outer figure for deep-linking and cross-references.                                                                                          
 
 
 <ResponsiveImage
   src={placeholder}
   zoomable
   downloadable
+  id="placeholder-image"
   layout="fixed"
   alt="A placeholder image alt text"
   caption={'A placeholder image description <span class="image-credit">From the <a target="_blank" href="https://commons.wikimedia.org/wiki/File:RCA_Indian_Head_Test_Pattern.svg">RCA Indian Head Test Pattern</a></span>'}

app/src/content/chapters/markdown.mdx

@@ -16,8 +16,8 @@ All the following **markdown features** are available **natively** in the `artic
 <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="#citation-and-notes">Citation</a>
+  <a className="button" href="#footnote">Footnote</a>
   <a className="button" href="#mermaid-diagrams">Mermaid</a>
   <a className="button" href="#separator">Separator</a>
   <a className="button" href="#table">Table</a>
@@ -26,7 +26,7 @@ All the following **markdown features** are available **natively** in the `artic
 
 ### Math
 
-KaTeX is used for math rendering. You can use inline notation `$...$` inline or block `$$...$$` notation. This is an inline math equation: $x^2 + y^2 = z^2$. 
+KaTeX is used for math rendering. You can use **inline** notation `$...$` or **block** `$$...$$` notation. As an example, this is an **inline** math equation: $x^2 + y^2 = z^2$ and this is a **block**:
 
 $$
 \mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
@@ -64,9 +64,13 @@ greet("Astro")
 ````
 </Accordion>
 
-### Citations
+### Citation
 
-**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`.
+The **citation keys** come from `app/src/content/bibliography.bib`.
+
+**Citation** 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.
+
+<Note variant="info" emoji="💡">Multiple citations to the same citation key are automatically merged into a single citation.</Note>
 
 1) In-text citation with brackets: [@vaswani2017attention].
 
@@ -88,9 +92,9 @@ greet("Astro")
 ```
 </Accordion>
 
-### Footnotes
+### Footnote
 
-**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.
+**Footnote** 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].
 
@@ -120,9 +124,9 @@ greet("Astro")
     ```
     Result: `add(2, 3) === 5`.
 
-4) Footnote that includes citations inside[^f5] and another footnote[^f1].
+4) Footnote that includes citation inside[^f5] and another footnote[^f1].
 
-[^f5]: Footnote containing citations [@vaswani2017attention] and [@kingma2015adam].
+[^f5]: Footnote containing citation [@vaswani2017attention] and [@kingma2015adam].
 
 <Accordion title="Code example">
 ```mdx
@@ -134,7 +138,7 @@ greet("Astro")
 
 3) Footnote with an inline code and an indented code block[^f4].
 
-4) Footnote that includes citations inside[^f5].
+4) Footnote that includes citation inside[^f5].
 
 [^f1]: Footnote attached to the sentence above.
 
@@ -155,7 +159,34 @@ greet("Astro")
 
     Result: `add(2, 3) === 5`.
 
-[^f5]: Footnote containing citations [@vaswani2017attention] and [@kingma2015adam].
+[^f5]: Footnote containing citation [@vaswani2017attention] and [@kingma2015adam].
+```
+</Accordion>
+
+
+### Reference
+
+In research articles, you may have to make references to anything. They are basically html anchors. They can be used internally in the article or externally in other articles.
+
+1. **Title**<br/>
+  Each title is automatically generated with a slugged version  from the citation key. ( slugged title from the citation key )
+  like for example, the id `#mermaid-diagrams` is generated from the `Mermaid diagrams` title.
+  <br/><br/>**Example** [Mermaid diagrams](#mermaid-diagram)
+
+2. **Image and chart**<br/>
+  You can make a link to an image or a chart by adding an ID on it.<br/>`<HtmlEmbed id="neural-network-mnist-like"/>` then you can link to it with a link like `<a href="#neural-network-mnist-like">Fig 1</a>`.
+  <br/><br/>**Example** [Chart 1](#neural-network-mnist-like) or [Fig 1](#placeholder-image)
+
+<Accordion title="Code example">
+```mdx
+  #### Mermaid diagrams
+  [Mermaid diagrams](#mermaid-diagrams)
+  
+  <HtmlEmbed id="neural-network-mnist-like"/>
+  [Chart 1](#neural-network-mnist-like)
+
+  <ResponsiveImage id="placeholder-image" src="..."/>
+  [Fig 1](#placeholder-image)
 ```
 </Accordion>
 

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

@@ -17,7 +17,7 @@ Once you have set up your project and started the development server, you can st
 
 Your **article** lives in **one and unique place**. The `content` folder.
 
-<HtmlEmbed frameless src="content-structure.html" /> 
+<HtmlEmbed frameless src="demo/content-structure.html" /> 
 
 ### Article.mdx
 
@@ -130,7 +130,7 @@ Use the **color picker** below to see how the primary color affects the theme.
 #### Brand color
 
 <Sidenote>
-  <HtmlEmbed frameless src="color-picker.html" />
+  <HtmlEmbed frameless src="demo/color-picker.html" />
   <Fragment slot="aside">
     You can use the color picker to select the right color.
     
@@ -143,7 +143,7 @@ Use the **color picker** below to see how the primary color affects the theme.
 
 Here is a suggestion of **color palettes** for your **data visualizations** that align with your **brand identity**. These palettes are generated from your `--primary-color`.
 
-<HtmlEmbed frameless src="palettes.html" />
+<HtmlEmbed frameless src="demo/palettes.html" />
 <br/>
 **Use color with care.**
 Color should rarely be the only channel of meaning.