Overview

The MarkdownContent component provides consistent typography styling for markdown content across your application. It applies the design system’s typography tokens, text rendering optimizations, and maintains proper visual hierarchy for all content elements.

API Reference

Props

Usage

<script>
import MarkdownContent from '$lib/content/components/markdown/MarkdownContent.svelte';
</script>

<MarkdownContent>
  {#snippet children()}
    <h1>Your Content Here</h1>
    <p>Markdown-formatted content with proper typography.</p>
  {/snippet}
</MarkdownContent>

Typography System

Heading Hierarchy

The component maps HTML heading elements to our typography tokens:

Text Elements

• Paragraphs: Use --typography-body-* tokens for optimal readability
• Strong text: Uses --typography-heading-color with subheading weight
• Emphasis: Italic styling with proper font synthesis disabled
• Links: Styled with --secondary (sky blue) color

Code Examples

Inline code like const x = true uses jasper color on dark background.

JavaScript

// Typography token usage example
const typography = {
	display: "var(--typography-display-size)",
	heading: "var(--typography-heading-size)",
	body: "var(--typography-body-size)",
	caption: "var(--typography-caption-size)",
};

// Text rendering optimizations
element.style.webkitFontSmoothing = "antialiased";
element.style.fontFeatureSettings = '"kern" 1, "liga" 1';

CSS

/* Typography hierarchy */
.markdown-content h1 {
	font-size: var(--typography-heading-size);
	color: var(--typography-heading-color);
	font-weight: var(--typography-heading-weight);
}

/* Code blocks - always dark */
pre {
	background: var(--neutral-200);
	color: var(--neutral-950);
}

Typography Tokens Table

Text Rendering Optimizations

The component inherits these optimizations from the global styles:

Font Rendering

• Antialiasing: -webkit-font-smoothing: antialiased for sharper text
• Grayscale: -moz-osx-font-smoothing: grayscale on Firefox
• Legibility: text-rendering: optimizeLegibility for better kerning

Typography Features

• Kerning: Professional letter spacing ("kern" 1)
• Ligatures: Standard ligatures enabled ("liga" 1)
• Contextual alternates: Smart character substitutions ("calt" 1)
• Font synthesis: Disabled to prevent fake bold/italic
• Numeric spacing: Proportional numbers for better data display

Styling Details

Lists

• Unordered and ordered lists with consistent spacing
• Nested list support with proper indentation
• Line height matches body text for readability

Blockquotes

• Secondary text color with italic styling
• Left border using primary color accent
• Proper padding and margins

Tables

• Header cells with --surface-secondary background
• Subheading weight for headers
• Hover states on rows
• Consistent borders and padding

Horizontal Rules

• Clean separation with --border color
• Generous margin spacing (--space-8)

Color Modes

The component automatically adapts to light and dark modes:

Light Mode

• Background: --neutral-950 (baby powder)
• Text: Typography color tokens (various grays)
• Code blocks: Dark background with light text

Dark Mode

• Background: --neutral-200 (night)
• Text: Inverted typography colors
• Code blocks: Maintain dark background for consistency

Best Practices

Do’s

• ✅ Use for all markdown-formatted content
• ✅ Wrap MDsveX content with this component
• ✅ Apply additional classes when needed
• ✅ Let the component handle typography

Don’ts

• ❌ Don’t override typography tokens inline
• ❌ Don’t nest multiple MarkdownContent components
• ❌ Don’t apply conflicting text styles
• ❌ Don’t use for non-markdown content

Integration with MDsveX

The component is designed to work with MDsveX layouts:

// mdsvex.config.js
export default {
	layout: {
		docs: "./src/lib/content/components/layouts/DocsLayout.svelte",
	},
};

The DocsLayout wraps content in MarkdownContent automatically.

Performance

• Lightweight: Minimal JavaScript, CSS-only styling
• Optimized: Text rendering optimizations improve performance
• Responsive: Adapts font sizes for mobile devices
• Accessible: Maintains proper heading hierarchy

Related Components

• Spacer: For adding vertical space between sections
• Card: Can contain MarkdownContent for styled text blocks
• DocsLayout: Wraps documentation pages with MarkdownContent

Migration from Prose

If migrating from the Tailwind Prose component:

<!-- Before: Using Prose -->
<Prose>
  {@render children()}
</Prose>

<!-- After: Using MarkdownContent -->
<MarkdownContent>
  {#snippet children()}
    <!-- Your content -->
  {/snippet}
</MarkdownContent>

TypeScript Support

interface Props {
	children: Snippet;
	class?: string;
}

The component is fully typed with Svelte 5’s Snippet type for content projection.