MD-Juice

Overview

A drop-in CSS theme for rendered Markdown HTML.
Works with any framework, any renderer, or plain HTML. Two layers of customization let you theme quickly, fine-tune individual elements, or simply keep the default GitHub-like look.

Table of Contents

• Why md-juice?
• Installation
• Basic Usage
• Theming
• Transitions
• Tailwind Compatibility
• Syntax Highlighting

Why MD-Juice?

Quickly style Markdown HTML with conflict-free, framework-agnostic CSS.

Use cases: Docs, blogs, wikis, notes apps, README previews, static sites
Key benefits: Fast theming, framework-agnostic, conflict-free styling
Features: GitHub-like default style, zero JS, built-in light/dark themes

Getting Started

Installation

To get started, install MD-Juice:

npm install @aruidev/md-juice

Basic setup

Import Styles

Import the MD-Juice CSS to your global styles.

@import '@aruidev/md-juice';

Basic usage

Quick example

These high-level tokens control the overall look and feel:

.md-juice {
  --juice-color-bg: #fefefe;
  --juice-color-text: #2d2a3e;
}

Dark Mode Support

Add dark mode variants in the same CSS file:

.md-juice[data-theme="dark"] {
  --juice-color-bg: #1a1625;
  --juice-color-text: #e4e2f0;
}

Theming

Layer 1 – Fast tokens (--juice-*)

These high-level tokens control the overall look and feel.
Set these to theme quickly.

| Token | Light default | Dark default | Role | |-------|---------------|--------------|------| | --juice-color-bg | #ffffff | #0d1117 | Base background | | --juice-color-bg-alt | #f6f8fa | #010409 | Secondary surface (tables, panels) | | --juice-color-text | #1f2328 | #c9d1d9 | Primary text | | --juice-color-text-secondary | #59636e | #8b949e | Muted text | | --juice-color-border | #d1d9e0 | rgba(110,118,129,0.40) | Borders / rules | | --juice-color-interactive | #0969da | #58a6ff | Links & accent base | | --juice-color-accent | var(--juice-color-interactive) | var(--juice-color-interactive) | Focus / accent alias | | --juice-color-surface-code | var(--juice-color-bg-alt) | var(--juice-color-bg-alt) | Code blocks & inline code |

Typography & layout primitives

| Token | Default | Maps to granular | Purpose | |------|---------|------------------|---------| | --juice-font-family-base | system stack | --mdj-font-family | Base text font stack | | --juice-font-family-monospace | monospace stack | --mdj-monospace | Code / monospace font stack | | --juice-font-size-base | 16px | --mdj-font-size | Root font size (affects rem) | | --juice-line-height-base | 1.5 | --mdj-line-height | Global line height | | --juice-radius-base | 6px | --mdj-radius | Shared corner radius (code, kbd, etc.) | | --juice-transition | 150ms | --mdj-transition | Theme transition duration | | --juice-transition-timing | cubic-bezier(0.4, 0, 0.2, 1) | --mdj-transition-timing | Theme transition timing |

Layer 2 – Granular tokens (--mdj-*)

Override only when a specific surface must differ from the fast mapping.

| Token | Default (maps from fast layer) | Description | |-------|--------------------------------|-------------| | --mdj-background-color | --juice-color-bg | Page / main background | | --mdj-background-secondary-color | --juice-color-bg-alt | Alt surface | | --mdj-text-primary-color | --juice-color-text | Main text | | --mdj-text-secondary-color | --juice-color-text-secondary | Muted text | | --mdj-border-color | --juice-color-border | Borders & dividers | | --mdj-link-color | --juice-color-interactive | Links | | --mdj-accent-color | --juice-color-accent | Accent & focus | | --mdj-code-bg | --juice-color-surface-code | Code block / inline background | | --mdj-kbd-bg | --juice-color-surface-code | <kbd> background | | --mdj-kbd-border | --juice-color-border | <kbd> border | | --mdj-mark-bg | --juice-color-bg-alt | <mark> highlight | | --mdj-table-th-bg | --juice-color-bg-alt | Table header | | --mdj-table-tr-bg | --juice-color-bg | Table rows | | --mdj-font-family | system stack | Base font | | --mdj-monospace | monospace stack | Code font | | --mdj-font-size | 16px | Root font size | | --mdj-line-height | 1.5 | Base line height | | --mdj-radius | 6px | Radius (pre/code/kbd) | | --mdj-hr-height | 1px | Rule thickness | | --mdj-focus-outline | 2px solid var(--mdj-accent-color) | Focus style | | --mdj-muted-bg | transparent | Reserved token | | --mdj-transition | 150ms | Theme transition speed | | --mdj-syntax-* | fixed colors | Minimal syntax hues |

Transitions

By default MD-Juice uses Tailwind's default transition values (150ms + cubic-bezier(0.4,0,0.2,1)) so it visually blends into projects already using Tailwind.

If the rest of your app (e.g. layout, buttons) uses a different speed/easing and you notice a mismatch, just override after loading the stylesheet.

Set --juice-transition and --juice-transition-timing to match your app:

.md-juice { --juice-transition: 200ms; }
.md-juice { --juice-transition-timing: ease-in-out; }

Disable transitions:

You can also disable transitions completely:

.md-juice { --juice-transition: 0ms; }

Tailwind compatibility

• Works side-by-side with Tailwind.
• MD-Juice styles only the markdown body inside a .md-juice scope.
• Load it after Tailwind if you want MD-Juice to take precedence for Markdown.

Syntax highlighting

• MD-Juice provides only minimal syntax tokens.
• For full dynamic language highlighting, use a syntax highlighter alongside MD-Juice.
• You can still override individual --mdj-syntax-* for custom hues.

Enjoy rapid theming. Issues & PRs welcome.