EXAMPLES/javascript-plugin

JavaScript Plugin

Demonstrates using frontmatter comments in TypeScript/JavaScript files to define example metadata, including region markers for code snippets.

meta-yml6 FILESpluginfrontmattertypescriptregions

JavaScript Plugin Example

This example demonstrates the @functional-examples/javascript plugin, which extracts code examples from JavaScript and TypeScript files using frontmatter metadata and region markers.

Usage

bash

1# Scan and display examples
2npx functional-examples scan
3
4# Output as JSON
5npx functional-examples scan -f json

Frontmatter Format

Frontmatter is written as YAML inside comment blocks at the top of a file. Here's how getting-started.ts defines its metadata:

// ---
// id: getting-started
// title: Getting Started
// description: A simple example demonstrating frontmatter metadata extraction
// tags:
//   - beginner
//   - tutorial
// ---

/**
 * A simple greeting function.
 *
 * @param name - The name to greet
 * @returns A greeting message
 */
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

// Example usage of the greet function
const message = greet('World');
console.log(message); // Output: Hello, World!

text

1Required fields: `id`, `title`. Optional: `description`, `tags`, and any custom fields.
2
3## Region Markers
4
5Extract specific code snippets with `#region` / `#endregion` markers. These are extracted as `hunks` in the scan output.
6
7For example, the `capitalize` utility:
8
9```typescript title="src/utils.ts#capitalize"
10/**
11 * Capitalize the first letter of a string.
12 */
13export function capitalize(str: string): string {
14  if (!str) return str;
15  return str.charAt(0).toUpperCase() + str.slice(1);
16}

And the truncate utility:

/**
 * Truncate a string to a maximum length.
 */
export function truncate(str: string, maxLength: number): string {
  if (str.length <= maxLength) return str;
  return str.slice(0, maxLength - 3) + '...';
}

text

1## Usage in Action
2
3```typescript title="src/getting-started.ts#usage"
4// Example usage of the greet function
5const message = greet('World');
6console.log(message); // Output: Hello, World!

Configuration Options

typescript

1createJavaScriptPlugin({
2  skipFrontmatter: true,  // Disable frontmatter parsing
3  skipRegions: true,      // Disable region extraction
4})

Supported Extensions

.js, .jsx, .ts, .tsx, .mjs, .cjs, .mts, .cts

All Example Files

FILE EXPLORER

README.md

1# JavaScript Plugin Example
2
3This example demonstrates the `@functional-examples/javascript` plugin, which extracts code examples from JavaScript and TypeScript files using frontmatter metadata and region markers.
4
5## Usage
6
7```bash
8# Scan and display examples
9npx functional-examples scan
10
11# Output as JSON
12npx functional-examples scan -f json
13```
14
15## Frontmatter Format
16
17Frontmatter is written as YAML inside comment blocks at the top of a file. Here's how `getting-started.ts` defines its metadata:
18
19<%= file('src/getting-started.ts') %>
20
21Required fields: `id`, `title`. Optional: `description`, `tags`, and any custom fields.
22
23## Region Markers
24
25Extract specific code snippets with `#region` / `#endregion` markers. These are extracted as `hunks` in the scan output.
26
27For example, the `capitalize` utility:
28
29<%= region('capitalize') %>
30
31And the `truncate` utility:
32
33<%= region('truncate') %>
34
35## Usage in Action
36
37<%= region('usage') %>
38
39## Configuration Options
40
41```typescript
42createJavaScriptPlugin({
43  skipFrontmatter: true,  // Disable frontmatter parsing
44  skipRegions: true,      // Disable region extraction
45})
46```
47
48## Supported Extensions
49
50`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`
51