Vanilla Breeze

markdown-viewer

Render markdown with progressive enhancement. Supports external files, inline content, pluggable parsers, and VB theme integration.

Overview

A platform-native markdown viewer custom element. Renders markdown into light DOM so VB's CSS cascade, themes, and component styles apply automatically. Progressive enhancement via the <pre> slot ensures content is readable without JavaScript.

Content Slots

The component resolves content using this priority chain:

<pre>

Raw markdown is visible as readable text if JS is disabled. Hidden after render.

<script>

If a <script> has an unknown MIME type the browser does not execute or render it. Here we use text/markdown to create a markdown block to render. Like the next approach using <template>, there is no fallback without JavaScript support.

<template>

Inert DOM node can be consulted as long as you put the data-md attribute on it, framework-friendly. No fallback without JS.

src

Fetch external markdown using the JS fetch() API. CORS rules apply.

Theme Propagation

Set data-theme on the viewer or let it inherit from the nearest ancestor with [data-theme]. The theme propagates to the .md-content container.

Custom Parser

The default parser is marked with GFM enabled. Override it with any function that accepts a markdown string and returns an HTML string:

Syntax Highlighting

Add the highlight attribute to fire markdown-viewer:highlight events for each code block. Bring your own highlighter:

Mermaid Diagrams

Listen for markdown-viewer:rendered and lazy-load Mermaid only when needed:

Callout Extension

Register the optional callout extension with marked for :::type blocks (warning, info, tip, danger, note):

Attributes

AttributeValuesDefaultDescription
srcstring—URL of external markdown file
loading"eager", "lazy"eagerDefer fetch until element enters viewport (Phase 3)
highlightboolean—Fire per-block markdown-viewer:highlight events after render
pingstring—URL to ping with render metadata via sendBeacon
data-themestring—Theme name propagated to .md-content container

Events

EventDetailDescription
markdown-viewer:fetch{ src }Fired when external fetch begins
markdown-viewer:rendered{ src, node }Fired after parse and render complete
markdown-viewer:highlight{ node, language }Fired per code block when highlight attribute is set
markdown-viewer:error{ error }Fired on fetch or parse failure

JavaScript API

Property / MethodDescription
.parserGet/set custom parser function (md → html string). Overrides the default marked parser.
.render()Force a re-render from the current content source. Returns a Promise.
.reload()Re-fetch the src URL and re-render. Returns a Promise.

Progressive Enhancement

The <pre> slot provides the best progressive enhancement:

SlotJS disabledCrawlableRecommended for
srcNothing visibleNoExternal files
<script>Nothing visibleNoBuild-time content
<template>Nothing visibleNoFramework content
<pre>Raw text visibleYesProgressive enhancement
↑