Markdown Directives

This document lists all markdown directives supported by the site generator. Directives provide a clean syntax for embedding rich content like videos, images, and interactive visualizations.

Table of Contents

• YouTube
• Vimeo
• SVG
• D3
• Mermaid

YouTube

Description

Embeds a responsive YouTube video player directly in your markdown. The video maintains a 16:9 aspect ratio and includes full YouTube player features.

Syntax

::youtube[Video Title]{#VIDEO_ID}

Code Example

::youtube[Foster City, California]{#fxGWxCowBwU}

Rendering

The directive renders as a fully responsive YouTube iframe embed with:

• 16:9 aspect ratio maintained automatically
• Full-width responsive container
• Rounded corners with shadow
• Title caption displayed below the video
• Full YouTube features (fullscreen, share, etc.)

Parameters

Finding the Video ID:

• From URL: https://www.youtube.com/watch?v=fxGWxCowBwU
• Video ID: fxGWxCowBwU (the part after v=)

Vimeo

Description

Embeds a responsive Vimeo video player with optional title caption. Creates a clean, distraction-free viewing experience with minimal player controls.

Syntax

::vimeo[Video Title]{#videoId}

Code Example

::vimeo[CSM Farmers Market]{#137782295}

Rendering

The directive renders as a responsive Vimeo iframe embed with:

• 16:9 aspect ratio maintained automatically
• Full-width responsive container
• Rounded corners
• Clean player (no title overlay, byline, or portrait)
• Title caption displayed below the video
• Fullscreen and picture-in-picture support

Parameters

Finding the Video ID:

• From URL: https://vimeo.com/137782295
• Video ID: 137782295 (the number at the end)

SVG

Description

Embeds SVG images with fine-grained control over dimensions and styling. Provides more flexibility than standard markdown image syntax.

Syntax

::svg[Alt Text]{src="/path/to.svg" width="..." height="..." className="..."}

Code Example

::svg[Company Logo]{src="/assets/svg/logo.svg" width="100%" height="auto" className="rounded-lg shadow-md"}

Rendering

The directive renders as an SVG image with:

• Automatic centering with flexbox
• Maximum width constraint (100% of container)
• Vertical spacing (margin)
• Support for custom inline styles and CSS classes
• Responsive sizing when using percentage values

Parameters

Best Practices:

• Always include alt text for accessibility
• Use width="100%" and height="auto" for responsive images
• SVG files should be placed in the public directory

D3

Description

Embeds interactive D3.js visualizations by loading external data files and visualization scripts. Supports dynamic, data-driven charts and graphs.

Syntax

::d3[Title]{data="data-file.json" script="visualization.js" width="..." height="..." className="..."}

Code Example

::d3[Sales Chart]{data="sales-data.json" script="bar-chart.js" width="100%" height="400" className="border rounded"}

Rendering

The directive renders as an interactive D3.js visualization with:

• Loading state indicator while assets load
• Error handling with clear error messages
• Responsive container with horizontal scrolling for large visualizations
• White background with border
• Title caption displayed above the visualization
• Dynamic SVG rendering based on loaded data and script

Parameters

How it Works:

• Data files and scripts must be placed in /public/assets/viz/
• The script receives d3, data, svg, container, width, and height as parameters
• The visualization script should use D3.js to render into the provided SVG element

Example Script Structure:

// visualization.js
// d3, data, svg, container, width, height are available
const margin = { top: 20, right: 20, bottom: 40, left: 40 };
const chartWidth = width - margin.left - margin.right;
const chartHeight = height - margin.top - margin.bottom;
 
// Create chart using d3...

Mermaid

Description

Renders Mermaid diagrams from code blocks. Supports flowcharts, sequence diagrams, class diagrams, and many other diagram types using simple text syntax.

Syntax

<Mermaid chart={`graph TD;
    A[Start] --> B[End];`} theme="light" />

Code Example

<Mermaid chart={`graph TD;
    A[Input text] --> B(Text preprocessing);
    B --> C(Query understanding);
    C --> D(Indexing and retrieval);
    D --> E(Ranking and relevance scoring);
    E --> F(Results presentation);`} theme="light" />

Rendering

The directive renders as an interactive SVG diagram with:

• Client-side rendering in the browser
• White background with border
• Responsive container with horizontal scrolling for large diagrams
• Error handling with clear messages for invalid syntax
• Pan and zoom capabilities for large diagrams

Parameters

Supported Diagram Types:

• Flowcharts: graph TD, graph LR
• Sequence Diagrams: sequenceDiagram
• Class Diagrams: classDiagram
• State Diagrams: stateDiagram-v2
• Gantt Charts: gantt
• Pie Charts: pie
• Entity-Relationship Diagrams: erDiagram
• Git Graphs: gitGraph

Example - Sequence Diagram:

<Mermaid chart={`sequenceDiagram
    participant User
    participant Browser
    participant Server
    User->>Browser: Click link
    Browser->>Server: HTTP Request
    Server-->>Browser: HTTP Response
    Browser-->>User: Display page`} theme="light" />

Example - Class Diagram:

<Mermaid chart={`classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog`} theme="light" />

General Notes

Directive Processing

All directives are preprocessed before MDX compilation:

1. Content is read from markdown files
2. Directives are transformed to JSX components
3. MDX processes the JSX and renders React components
4. Static HTML is generated with the embedded content

Best Practices

• Always include titles/alt text for accessibility
• Use descriptive titles that provide context
• Verify resource paths (video IDs, file paths) are correct
• Test directives in development before deploying
• Quote special characters properly in titles and attributes

Troubleshooting

Directive shows as text instead of rendering:

• Check syntax matches exactly (spaces, brackets, quotes)
• Verify required parameters are provided
• Ensure resources exist (files, video IDs)

Rendering errors:

• Check browser console for detailed error messages
• Verify file paths are correct and files exist
• For D3: ensure scripts and data files are in /public/assets/viz/
• For Mermaid: validate diagram syntax using Mermaid Live Editor

Last Updated: January 2025