7 files changed, 56 insertions, 12 deletions
diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts
index fe8f48c5..a736bd15 100644
--- a/scripts/apidoc/apiDocsWriter.ts
+++ b/scripts/apidoc/apiDocsWriter.ts
@@ -37,6 +37,7 @@ editLink: false
  * @param moduleName The name of the module to write the docs for.
  * @param lowerModuleName The lowercase name of the module.
  * @param comment The module comments.
+ * @param examples The example code.
  * @param deprecated The deprecation message.
  * @param methods The methods of the module.
  */
@@ -44,6 +45,7 @@ export async function writeApiDocsModule(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
+  examples: string | undefined,
   deprecated: string | undefined,
   methods: Method[]
 ): Promise<ModuleSummary> {
@@ -51,6 +53,7 @@ export async function writeApiDocsModule(
     moduleName,
     lowerModuleName,
     comment,
+    examples,
     deprecated,
     methods
   );
@@ -83,12 +86,15 @@ export async function writeApiDocsModule(
  * @param moduleName The name of the module to write the docs for.
  * @param lowerModuleName The lowercase name of the module.
  * @param comment The module comments.
+ * @param examples The example code.
+ * @param deprecated The deprecation message.
  * @param methods The methods of the module.
  */
 async function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
+  examples: string | undefined,
   deprecated: string | undefined,
   methods: Method[]
 ): Promise<void> {
@@ -118,6 +124,8 @@ async function writeApiDocsModulePage(
 
   ${comment}
 
+  ${examples == null ? '' : `<div class="examples">${examples}</div>`}
+
   :::
 
   ${methods
diff --git a/scripts/apidoc/fakerClass.ts b/scripts/apidoc/fakerClass.ts
index 5ce3c063..d7206cf8 100644
--- a/scripts/apidoc/fakerClass.ts
+++ b/scripts/apidoc/fakerClass.ts
@@ -29,7 +29,7 @@ async function processClass(
 
   console.log(`Processing ${name} class`);
 
-  const { comment, deprecated } = analyzeModule(fakerClass);
+  const { comment, deprecated, examples } = analyzeModule(fakerClass);
   const methods: Method[] = [];
 
   console.debug(`- constructor`);
@@ -43,6 +43,7 @@ async function processClass(
     name,
     moduleFieldName,
     comment,
+    examples,
     deprecated,
     methods
   );
diff --git a/scripts/apidoc/fakerUtilities.ts b/scripts/apidoc/fakerUtilities.ts
index 59dadeba..d164857b 100644
--- a/scripts/apidoc/fakerUtilities.ts
+++ b/scripts/apidoc/fakerUtilities.ts
@@ -28,5 +28,12 @@ async function processUtilities(
     )
   );
 
-  return writeApiDocsModule('Utilities', 'utils', comment, undefined, methods);
+  return writeApiDocsModule(
+    'Utilities',
+    'utils',
+    comment,
+    undefined,
+    undefined,
+    methods
+  );
 }
diff --git a/scripts/apidoc/markdown.ts b/scripts/apidoc/markdown.ts
index 1ddd433e..7d44fc39 100644
--- a/scripts/apidoc/markdown.ts
+++ b/scripts/apidoc/markdown.ts
@@ -46,6 +46,16 @@ function comparableSanitizedHtml(html: string): string {
 }
 
 /**
+ * Converts a Typescript code block to an HTML string and sanitizes it.
+ * @param code The code to convert.
+ * @returns The converted HTML string.
+ */
+export function codeToHtml(code: string): string {
+  const delimiter = '```';
+  return mdToHtml(`${delimiter}ts\n${code}\n${delimiter}`);
+}
+
+/**
  * Converts Markdown to an HTML string and sanitizes it.
  * @param md The markdown to convert.
  * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`.
diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts
index 359282dc..89f234db 100644
--- a/scripts/apidoc/moduleMethods.ts
+++ b/scripts/apidoc/moduleMethods.ts
@@ -5,10 +5,12 @@ import type {
 } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsModule } from './apiDocsWriter';
+import { codeToHtml } from './markdown';
 import { analyzeSignature } from './signature';
 import {
   extractDeprecated,
   extractDescription,
+  extractJoinedRawExamples,
   extractModuleFieldName,
   extractModuleName,
   selectApiMethodSignatures,
@@ -41,7 +43,7 @@ async function processModule(
   const moduleName = extractModuleName(module);
   console.log(`Processing Module ${moduleName}`);
   const moduleFieldName = extractModuleFieldName(module);
-  const { comment, deprecated } = analyzeModule(module);
+  const { comment, deprecated, examples } = analyzeModule(module);
   const methods = await processModuleMethods(
     module,
     `faker.${moduleFieldName}.`
@@ -51,6 +53,7 @@ async function processModule(
     moduleName,
     moduleFieldName,
     comment,
+    examples,
     deprecated,
     methods
   );
@@ -65,10 +68,15 @@ async function processModule(
 export function analyzeModule(module: DeclarationReflection): {
   comment: string;
   deprecated: string | undefined;
+  examples: string | undefined;
 } {
+  const examplesRaw = extractJoinedRawExamples(module);
+  const examples = examplesRaw ? codeToHtml(examplesRaw) : undefined;
+
   return {
     comment: adjustUrls(extractDescription(module)),
     deprecated: extractDeprecated(module),
+    examples,
   };
 }
 
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index ea39f51b..2cba4904 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -14,12 +14,12 @@ import type {
   MethodParameter,
 } from '../../docs/.vitepress/components/api-docs/method';
 import { formatTypescript } from './format';
-import { mdToHtml } from './markdown';
+import { codeToHtml, mdToHtml } from './markdown';
 import {
   extractDeprecated,
   extractDescription,
+  extractJoinedRawExamples,
   extractRawDefault,
-  extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
@@ -28,8 +28,6 @@ import {
   toBlock,
 } from './typedoc';
 
-const code = '```';
-
 export async function analyzeSignature(
   signature: SignatureReflection,
   accessor: string,
@@ -74,9 +72,9 @@ export async function analyzeSignature(
 
   let examples = `${accessor}${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type?.toString()}\n`;
 
-  const exampleTags = extractRawExamples(signature);
-  if (exampleTags.length > 0) {
-    examples += `${exampleTags.join('\n').trim()}\n`;
+  const exampleTags = extractJoinedRawExamples(signature);
+  if (exampleTags) {
+    examples += exampleTags;
   }
 
   const seeAlsos = extractSeeAlsos(signature).map((seeAlso) =>
@@ -97,7 +95,7 @@ export async function analyzeSignature(
     sourcePath: extractSourcePath(signature),
     throws,
     returns: await typeToText(signature.type),
-    examples: mdToHtml(`${code}ts\n${examples}${code}`),
+    examples: codeToHtml(examples),
     deprecated,
     seeAlsos,
   };
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index 2e86f2c2..268ae1f4 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -244,11 +244,23 @@ export function extractRawDefault(reflection?: CommentHolder): string {
  *
  * @param reflection The reflection to extract the examples from.
  */
-export function extractRawExamples(reflection?: CommentHolder): string[] {
+function extractRawExamples(reflection?: CommentHolder): string[] {
   return extractRawCode('@example', reflection);
 }
 
 /**
+ * Extracts the examples from the jsdocs without the surrounding md code block, then joins them with newlines and trims.
+ *
+ * @param reflection The reflection to extract the examples from.
+ */
+export function extractJoinedRawExamples(
+  reflection?: CommentHolder
+): string | undefined {
+  const examples = extractRawExamples(reflection);
+  return examples.length === 0 ? undefined : examples.join('\n').trim();
+}
+
+/**
  * Extracts all the `@see` references from the jsdocs separately.
  *
  * @param reflection The reflection to extract the see also references from.