Skip to main content

​
Overview

lpd-mdx-preview is a VS Code extension that renders .mdx and .md files in a side panel with governed Mintlify built-ins, Livepeer custom component renderers, and Mermaid diagrams. It is the primary local authoring preview tool for this repo, but runtime-dependent surfaces still need verification in a Mintlify dev session. Keybinding: Cmd+Shift+V (Mac) / Ctrl+Shift+V (Windows/Linux) Location: tools/editor-extensions/lpd-mdx-preview/

​
Repo Context

tools/editor-extensions/lpd-mdx-preview
extension.js
package.json
README.md
lpd-mdx-preview-0.0.2.vsix

​
Installation

Works in VS Code, Cursor, and Windsurf (all VS Code forks). The same .vsix file installs in all three. All editors at once (recommended): 
bash tools/editor-extensions/install.sh
Detects which editors are installed (~/.vscode, ~/.cursor, ~/.windsurf) and deploys to each. The installer verifies that the checked-in .vsix matches source before installing. If the package is stale, the install fails and prints the exact rebuild command. Manual install: Extensions sidebar → ... menu → Install from VSIX → select tools/editor-extensions/lpd-mdx-preview/lpd-mdx-preview-0.0.2.vsix. Rebuild after source changes: 
cd tools/editor-extensions/lpd-mdx-preview
npx @vscode/vsce package --no-dependencies -o lpd-mdx-preview-0.0.2.vsix
Then re-run install.sh or reinstall manually.

​
Usage

Open any .mdx or .md file, then press Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows/Linux).The preview opens in a side panel and updates automatically as you type (300ms debounce).
The preview detects your VS Code colour theme automatically (auto mode). You can override this in settings:
"livepeer.mdxPreview.theme": "dark"
Options: auto | light | dark
Frontmatter is stripped from the preview body and rendered as a header bar showing: title, pageType, audience, status, purpose, and lastVerified.
Fenced code blocks tagged with mermaid are rendered using the bundled Mermaid.js with Livepeer theme colours. Diagrams update live as you edit.

​
Component Rendering Tiers

Custom components (your own project .jsx files) fall into Tier 3 — they render as labelled placeholders with their children content visible. Most Mintlify built-ins and the Livepeer component library render as styled HTML, but runtime-heavy built-ins such as OpenAPI remain approximate.

​
Component Reference

​
Tier 1 — Mintlify Built-ins

Purpose: Callout boxes for supplementary information.
<Note>Standard info callout.</Note>
<Tip>Helpful suggestion.</Tip>
<Warning>Something to watch out for.</Warning>
<Info>Neutral informational note.</Info>
PropTypeDefaultDescription
(none)——Content passed as children
Purpose: Generic callout with a custom Font Awesome icon.
<Callout icon="rocket">Custom callout with icon.</Callout>
PropTypeDefaultDescription
iconstringinfoFont Awesome icon name (e.g. rocket, star)
Purpose: Linked or unlinked content card with optional icon and arrow.
<Card title="Gateway Setup" icon="server" href="/v2/gateways/setup" arrow>
  Run your first gateway in minutes.
</Card>

<Card title="Horizontal" icon="code" href="/v2/developers" arrow horizontal>
  Displayed inline.
</Card>
PropTypeDefaultDescription
titlestring—Card heading
iconstring—Font Awesome icon name
hrefstring—Link target; wraps card in <a>
arrowbooleanfalseAppends → to title
horizontalbooleanfalseInline flex layout
Purpose: Responsive grid wrapper for <Card> components.
<CardGroup cols={2}>
  <Card title="One" />
  <Card title="Two" />
</CardGroup>
PropTypeDefaultDescription
cols1 | 2 | 3 | 42Number of grid columns
Purpose: Interactive tabbed content sections.
<Tabs>
  <Tab title="On-chain" icon="link">Content for tab one.</Tab>
  <Tab title="Off-chain" icon="cloud">Content for tab two.</Tab>
</Tabs>
Tab props:
PropTypeDefaultDescription
titlestringTabTab label
iconstring—Font Awesome icon name
Purpose: Collapsible content sections. Rendered as <details>/<summary> in the preview.
<AccordionGroup>
  <Accordion title="From a Cloud Background?" icon="cloud">
    Content here.
  </Accordion>
</AccordionGroup>
Accordion props:
PropTypeDefaultDescription
titlestringDetailsSummary/header text
iconstring—Font Awesome icon name
Purpose: Numbered step-by-step walkthrough.
<Steps>
  <Step title="Install dependencies">Run `npm install`.</Step>
  <Step title="Configure">Set your environment variables.</Step>
</Steps>
Step props:
PropTypeDefaultDescription
titlestring—Step heading
Purpose: Bordered container for isolating content visually. No props — content as children.
<Frame>
  <img src="/path/to/image.png" />
</Frame>
Purpose: Two-column layout grid. No props.
<Columns>
  <div>Left</div>
  <div>Right</div>
</Columns>
Purpose: Show/hide toggle for secondary content.
<Expandable title="Advanced options">Hidden until expanded.</Expandable>
PropTypeDefaultDescription
titlestringShow moreToggle label
Purpose: Code block container. Rendered as plain <pre><code> in the preview without syntax highlighting.
<CodeBlock language="bash">livepeer -gateway</CodeBlock>
PropTypeDefaultDescription
languagestring—Language identifier (e.g. bash, json)
Purpose: Inline Font Awesome icon.
<Icon icon="rocket" />
PropTypeDefaultDescription
iconstring—Font Awesome icon name
namestring—Alias for icon
Purpose: Changelog or versioned annotation with a label.
<Update label="Q4 2025">Off-chain gateway mode shipped.</Update>
PropTypeDefaultDescription
labelstring—Date or version label
datestring—Alias for label
Purpose: API response field documentation row.
<ResponseField name="id" type="string">
  Unique identifier for the job.
</ResponseField>
PropTypeDefaultDescription
namestring—Field name (rendered in accent colour)
typestring—Data type label
Purpose: API parameter documentation row.
<ParamField path="streamId" type="string" required>
  Stream identifier passed in the URL path.
</ParamField>
PropTypeDefaultDescription
pathstring—Path parameter name
querystring—Query parameter name
bodystring—Request-body field name
headerstring—Header name
typestring—Data type label
requiredbooleanfalseAdds a required marker
Purpose: High-severity callout variant.
<Danger>Do not expose this secret in client-side code.</Danger>
Purpose: Inline pill label with accent styling.
<Badge color="var(--accent)">Preview</Badge>
PropTypeDefaultDescription
colorstringvar(--accent)Accent colour used for border, text, and background tint
textstring—Fallback text when no children are passed
Purpose: Group multiple code blocks in one bordered container.
<CodeGroup>
  <CodeBlock language="bash">npm install</CodeBlock>
  <CodeBlock language="bash">npm run dev</CodeBlock>
</CodeGroup>
Purpose: Repo-style file tree rendering using canonical Mintlify syntax.
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.js" />
  </Tree.Folder>
</Tree>
Tree.Folder props:
PropTypeDefaultDescription
namestringfolderFolder label
defaultOpenbooleanfalseExpands the folder by default
Tree.File props:
PropTypeDefaultDescription
namestringfileFile label
Purpose: API reference embed. The preview renders a descriptive placeholder rather than the full interactive Mintlify API experience.
<OpenAPI method="get" path="/asset/{id}" />
PropTypeDefaultDescription
methodstring—HTTP method label
pathstring—API path shown in the placeholder
openapistring—Alias for path
Purpose: Styled HTML table with header and body rows.
<StyledTable>
  <TableRow header>
    <TableCell header>Column A</TableCell>
    <TableCell header>Column B</TableCell>
  </TableRow>
  <TableRow>
    <TableCell>Value</TableCell>
    <TableCell>Value</TableCell>
  </TableRow>
</StyledTable>
TableRow props:
PropTypeDefaultDescription
headerbooleanfalseRenders row with header background
TableCell props:
PropTypeDefaultDescription
headerbooleanfalseRenders as <th> with bold weight

​
Tier 2 — Livepeer Custom Components

​
Spacing

Purpose: Horizontal rule with optional centred label text.Location: snippets/components/elements/spacing/Divider.jsx
<CustomDivider />
<CustomDivider middleText="Role Evolution" />
PropTypeDefaultDescription
middleTextstring—Text centred in the divider
textstring—Alias for middleText
Purpose: Explicit vertical whitespace block.
<Spacer height="48px" />
PropTypeDefaultDescription
heightstring24pxCSS height value
sizestring—Alias for height
Purpose: Plain <hr> divider. No props.
<Divider />

​
Containers

Purpose: Constrains content width and centres it horizontally.Location: snippets/components/wrappers/containers/Containers.jsx
<CenteredContainer maxWidth="960px">
  Content here.
</CenteredContainer>
PropTypeDefaultDescription
maxWidthstring100%CSS max-width value
Purpose: Card-like container with a visible border.
<BorderedBox borderColor="#2d9a67" padding="24px">
  Content here.
</BorderedBox>
PropTypeDefaultDescription
borderColorstringvar(--border)CSS border colour
backgroundColorstringvar(--card-bg)CSS background colour
paddingstring16pxCSS padding
Purpose: Forces content to full available width. No props.
<FullWidthContainer>Content here.</FullWidthContainer>
Purpose: Flexbox layout wrapper.
<FlexContainer direction="row" gap="16px" align="center">
  <div>Item A</div>
  <div>Item B</div>
</FlexContainer>
PropTypeDefaultDescription
directionstring—CSS flex-direction (row, column)
gapstring12pxCSS gap
alignstring—CSS align-items
justifystring—CSS justify-content
wrapbooleanfalseEnables flex-wrap: wrap
Purpose: CSS Grid layout wrapper.
<GridContainer columns="repeat(3, 1fr)" gap="16px">
  <div>Cell 1</div>
  <div>Cell 2</div>
  <div>Cell 3</div>
</GridContainer>
PropTypeDefaultDescription
columnsstring—CSS grid-template-columns value
gapstring12pxCSS gap
Purpose: Scrollable container with a fixed maximum height.
<ScrollBox maxHeight="300px">Long content here.</ScrollBox>
PropTypeDefaultDescription
maxHeightstring400pxCSS max-height value

​
Diagrams

Purpose: Horizontally scrollable wrapper for Mermaid or wide diagram content.Location: snippets/components/displays/diagrams/ZoomableDiagram.jsx
<ScrollableDiagram title="Gateway Role Evolution" maxHeight="420px">
```mermaid
flowchart LR
  A --> B
```
</ScrollableDiagram>
PropTypeDefaultDescription
titlestring—Label shown above the diagram
maxHeightstring—CSS max-height to constrain tall diagrams
Purpose: Inline text link with → suffix.Location: snippets/components/elements/links/Links.jsx
<LinkArrow href="/v2/gateways/concepts/capabilities" label="Gateway Capabilities" newline={false} />
PropTypeDefaultDescription
hrefstring#Link target
labelstring—Link text
textstring—Alias for label
newlinebooleantrueIf false, renders inline (no line break)
Purpose: Card that links to a destination.
<GotoCard href="/v2/gateways/setup">Setup content here.</GotoCard>
PropTypeDefaultDescription
hrefstring#Link target

​
Text & Headings

Purpose: Styled italic accent text. Used below page titles. No props.
<Subtitle>Understand how gateways route workloads.</Subtitle>
Purpose: Blockquote with Livepeer accent border. FrameQuote adds an outer border frame. No props.
<Quote>Gateways are the demand side of the network.</Quote>
<FrameQuote>Framed and quoted.</FrameQuote>
Purpose: Heading components with optional Font Awesome icon prefix. Used on FrameMode pages.
<H2 icon="server">Gateway Setup</H2>
PropTypeDefaultDescription
iconstring—Font Awesome icon name shown before heading text
Purpose: Explicit paragraph wrapper. Used on FrameMode pages. No props.
<P>Body text content here.</P>
Purpose: Inline code-styled text value.
<CopyText text="livepeer -gateway -orchAddr 0x..." />
PropTypeDefaultDescription
textstring—Text to display as inline code
valuestring—Alias for text
Purpose: Composable title elements with → suffix. No props — content as children.
<CardTitleTextWithArrow>Quick Start</CardTitleTextWithArrow>
<AccordionTitleWithArrow>Show Details</AccordionTitleWithArrow>

​
Cards

Purpose: Standalone content card with title and icon.
<DisplayCard title="Run a Gateway" icon="server">
  Step-by-step instructions.
</DisplayCard>
PropTypeDefaultDescription
titlestring—Card heading
iconstring—Font Awesome icon name
Purpose: Card constrained to a max width and centred.
<WidthCard width="600px">Constrained content.</WidthCard>
PropTypeDefaultDescription
widthstring100%CSS max-width
maxWidthstring—Alias for width
Purpose: Card with an image on the left and content on the right.
<InlineImageCard src="/snippets/assets/logos/Livepeer-Logo-Symbol.svg">
  Description text here.
</InlineImageCard>
PropTypeDefaultDescription
srcstring—Image source URL
Purpose: Card with a heading and freeform children content.
<InteractiveCard title="Configuration">Content here.</InteractiveCard>
PropTypeDefaultDescription
titlestring—Card heading
Purpose: Horizontally scrollable row of cards. No props.
<CardCarousel>
  <Card title="A" />
  <Card title="B" />
</CardCarousel>

​
Callout Banners

Purpose: Styled callout with a custom icon (emoji or character).
<CustomCallout icon="🔧">Manual configuration required.</CustomCallout>
PropTypeDefaultDescription
iconstringℹ️Icon character or emoji
Purpose: Tip callout with a 💡 icon. No props — content as children.
<TipWithArrow>Use the remote signer to skip ETH setup.</TipWithArrow>
Purpose: Status banners indicating a feature is pending, in preview, or under review. No props.
<ComingSoonCallout>Dashboard analytics</ComingSoonCallout>
<PreviewCallout>Python SDK support</PreviewCallout>
<ReviewCallout>Pricing model — subject to change</ReviewCallout>

​
Media

Purpose: Image with optional caption.
<Image src="/snippets/assets/diagrams/gateway-flow.png" alt="Gateway flow" caption="Traffic routing through the gateway layer" />
PropTypeDefaultDescription
srcstring—Image URL
altstring—Alt text
captionstring—Caption displayed below image
Purpose: Clickable image that links to a URL.
<LinkImage src="/snippets/assets/logos/Livepeer-Logo-Symbol.svg" href="https://livepeer.org" alt="Livepeer" />
PropTypeDefaultDescription
srcstring—Image URL
hrefstring#Link target
altstring—Alt text
Purpose: Embedded YouTube player (16:9 aspect ratio).
<YouTubeVideo id="dQw4w9WgXcQ" />
PropTypeDefaultDescription
idstring—YouTube video ID
videoIdstring—Alias for id
Purpose: Video or media block with a heading label.
<TitledVideo title="Gateway Demo">
  <video src="/assets/demo.mp4" controls />
</TitledVideo>
PropTypeDefaultDescription
titlestring—Heading displayed above the media

​
Steps

Purpose: Custom step list with numbered indicators and a connecting line.
<StyledSteps>
  <StyledStep title="Configure your node">Edit the config file.</StyledStep>
  <StyledStep title="Start the service">Run `systemctl start livepeer`.</StyledStep>
</StyledSteps>
StyledStep props:
PropTypeDefaultDescription
titlestring—Step heading
Purpose: Alias for StyledSteps. Same rendering, same props.
<ListSteps>
  <StyledStep title="Step one">Content</StyledStep>
</ListSteps>

​
Grids & Layouts

Purpose: Two-column grid (2×n). No props.
<QuadGrid>
  <Card title="A" />
  <Card title="B" />
</QuadGrid>
Purpose: Flex column wrappers for custom accordion arrangements. No props.
<AccordionLayout>
  <Accordion title="Item">Content</Accordion>
</AccordionLayout>

​
Tables

Purpose: Scrollable table wrapper. No props — pass raw HTML table elements as children.
<DynamicTable>
  <tr><th>Column</th></tr>
</DynamicTable>
Purpose: Filterable table — live text search and category dropdown. Fully interactive in deployed Mintlify (uses useState). Renders as a static mock in the preview: non-functional search bar + category dropdown chrome + full table body. An ⚡ interactive — static in preview badge is shown to set expectations.
<SearchTable searchPlaceholder="Search terms…" categoryLabel="All categories">
  <tr><th>Term</th><th>Definition</th></tr>
  <tr><td>Example</td><td>Description</td></tr>
</SearchTable>
PropTypeDefaultPurpose
searchPlaceholderstringSearch…Placeholder text in the search input
categoryLabelstringAll categoriesLabel for the category dropdown
searchColumnsarray—Columns to include in search (passed to SearchTable.jsx)
SEO note: Custom components render client-side only — table rows are not in the initial HTML. Acceptable trade-off for reference/glossary pages.

​
Hero & Portal Scaffolding

Purpose: Structural wrappers for full-width portal and hero layouts on FrameMode pages. No props on any of these.
<HeroSectionContainer>
  <HeroContentContainer>
    <PortalHeroContent>Hero copy here.</PortalHeroContent>
  </HeroContentContainer>
</HeroSectionContainer>

​
Icons & Indicators

Purpose: Inline Livepeer brand indicator badge. No props.
<LivepeerIcon />
Purpose: Animated icon badge (animation runs in Mintlify; static badge in preview).
<BlinkingIcon icon="terminal" />
PropTypeDefaultDescription
iconstringterminalFont Awesome icon name
Purpose: Inline download link styled as a button.
<DownloadButton href="/assets/config.yaml" label="Download config" />
PropTypeDefaultDescription
hrefstring#Download URL
labelstringDownloadButton label text

​
Embeds & Social

Purpose: Bordered container for embedded markdown content. No props.
<MarkdownEmbed>Embedded content here.</MarkdownEmbed>
Purpose: Framed container for external or imported content with a title header.
<ExternalContent title="API Response">Response body here.</ExternalContent>
PropTypeDefaultDescription
titlestringExternal ContentHeader label

​
Math

Purpose: Mathematical expression display. Rendered as styled <code> in preview (not LaTeX-rendered).
<MathInline expression="E = mc^2" />
<MathBlock expression="\sum_{i=1}^{n} x_i" />
PropTypeDefaultDescription
expressionstring—Mathematical expression string
mathstring—Alias for expression

​
Tier 3 — Placeholder Rendering

Any component not in Tier 1 or Tier 2 renders as: 
┌ - - - - - - - - - - - - - - ┐
  &lt;ComponentName prop="value"&gt;
  [children rendered here]
└ - - - - - - - - - - - - - - ┘
Props are shown truncated to 40 characters. Children render inside so content remains readable. To promote a component from Tier 3 to Tier 2, add a renderer function to lib/component-map.js under the livepeerComponents object.

​
Interactive components

Some Tier 2 components use React hooks (useState, useEffect) and are fully interactive in deployed Mintlify but cannot run in the VS Code webview (Node.js environment, no React runtime). These render as static mocks — they show the correct UI chrome but do not respond to input. Currently affected: SearchTable, SocialLinks, MarkdownEmbed, and OpenAPI. These components display an ⚡ interactive — static in preview badge so authors know to verify their behaviour in a Mintlify dev session, not just the local preview. Data-feed integrators (ShowcaseCards, CoinGeckoExchanges, LumaEvents, DiscordAnnouncements, TwitterTimeline) fall to Tier 3 placeholders for the same reason — they fetch live data and cannot be meaningfully mocked offline.

​
Configuration

SettingTypeDefaultOptionsDescription
livepeer.mdxPreview.themestringautoauto | light | darkPreview colour theme. auto matches VS Code.

​
Architecture

Registers two commands (livepeer.openMdxPreview, livepeer.openMdxPreviewToSide), the Cmd+Shift+V keybinding, and two event listeners (document change → debounced re-render; theme change → full re-render). Manages a Map of open panels keyed by document URI.
Parses raw MDX text into a flat array of typed segments: frontmatter, import, markdown, mermaid, codeblock, jsx, jsx-expression. Regex-based extraction — not a full MDX compiler, for robustness with non-standard MDX.
Functions for the governed Mintlify built-ins used by this repo, including canonical Tree.Folder / Tree.File rendering and descriptive placeholders where full runtime parity is not practical in the preview. Each function signature: (props, childrenHtml) => htmlString.
Livepeer custom component renderers. Merges with Tier 1 into COMPONENT_MAP. Exports renderSegments() which dispatches each segment to its renderer or falls through to renderPlaceholder().
Builds the full webview HTML document including CSP headers, Font Awesome CDN (fa 6.5.1), local CSS/JS vscode-resource: URIs, and the rendered body.
Runs inside the webview. Initialises Mermaid.js with Livepeer theme vars, processes .lpd-md-raw blocks with markdown-it, and handles tab switching interactions.
CSS custom properties for light and dark themes using the governed Livepeer accent variables from style.css. Styles for all Tier 1 and Tier 2 component classes.

​
Future Features

renderSegments() returns { html, hasMermaid }. The webview template conditionally injects <script src="${mermaidUri}"> only when hasMermaid is true. Pages without Mermaid diagrams skip the 2.45 MB bundle entirely.
Any component that falls through to the placeholder renderer can be promoted to Tier 2 by adding a renderer function to lib/component-map.js under livepeerComponents. The function signature is (props, childrenHtml) => htmlString.Priority candidates based on usage frequency in the repo:
  • Snippet (used in composable page patterns)
  • data-feed integrators that could be represented by stable static mocks
  • additional low-use repo components that currently fall through to generic placeholders
Code blocks are currently rendered as plain <pre><code> without syntax colouring. Adding highlight.js (vendored, ~50 KB minified) as a third media asset and calling hljs.highlightAll() in preview.js would add language-aware colouring for all fenced blocks.
Sync the scroll position of the preview panel to the cursor position in the editor. VS Code’s built-in Markdown preview uses editor/scroll messages via the webview messaging API. The same pattern can be applied here: on onDidChangeTextEditorVisibleRanges, post a message to the webview to scroll to the corresponding rendered element.
onDidSaveTextDocument watches for any .jsx save in the workspace and re-renders all open preview panels. Component source changes are reflected immediately without touching the .mdx file.
Multi-line {/* ... */} comment blocks — typically template instructions or reviewer flags — are rendered as collapsed <details> elements instead of leaking into the preview as visible text. Single-line {/* ... */} comments are still silently stripped. The collapsible uses a dashed border and muted palette to distinguish it from content.Parser: lib/mdx-parser.js detects {/* without a same-line */} and collects lines until the closing */}, emitting a jsx-comment segment.Renderer: lib/component-map.js handles jsx-comment as <details class="lpd-comment"> with a 💬 comment summary and pre-formatted body.

​
References

Extension source

Entry point and command registration.

Component map

Tier 2 renderers and dispatch logic.

Authoring tools

Other VS Code tools in this repo.
Last modified on April 7, 2026