Getting Started with Taildown

From zero to beautiful documents in 5 minutes

Installation

# Global installation
npm install -g taildown

# Or use npx
npx taildown compile document.td

# Clone the repository
git clone https://github.com/vincitamore/taildown.git
cd taildown

# Install dependencies
pnpm install

# Build all packages
pnpm build

Download the latest release from GitHub
Extract to your preferred location
Run pnpm install in the extracted directory
Run pnpm buildto compile packages

Your First Document

Create a file named my-first-document.td:

# Hello World {huge-bold center primary}

Welcome to Taildown! {large muted center}

:::card {light-glass slide-up}
## Your First Card {medium-bold}

This is a card with glassmorphism and a slide-up animation!

- :icon[check]{success} Beautiful by default
- :icon[check]{success} No configuration needed
- :icon[check]{success} Dark mode included

[Learn More](#){button primary}
:::

Compile Your Document

Basic Compilation

pnpm taildown compile my-first-document.td

This creates:

my-first-document.html - Self-contained HTML with embedded CSS and JavaScript

Separate CSS File

pnpm taildown compile my-first-document.td --separate

This creates:

my-first-document.html - HTML file
my-first-document.css - Separate CSS file

Custom Output

pnpm taildown compile my-first-document.td -o output/index.html --css output/styles.css

Understanding the Output

HTML Output

Semantic HTML5 structure
Proper heading hierarchy
Accessible ARIA attributes
Mobile-responsive viewport
Dark mode support

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <style>/* CSS here */</style>
</head>
<body>
  <!-- Your content -->
  <script>/* JS here */</script>
</body>
</html>

CSS Output

Tailwind-inspired utilities
CSS custom properties for themes
Dark mode with .dark class
Glassmorphism effects
Scroll animations
Component styles

:root {
  --primary: #3b82f6;
  --background: #ffffff;
}

.dark {
  --background: #030712;
}

Basic Syntax Overview

Use natural language for styling:

# Large Bold Primary Heading {huge-bold primary center}

This paragraph has muted text and relaxed line spacing. {large muted relaxed-lines}

[Click Me](#){button primary large hover-lift}

Common shorthands:

Sizes: xs, small, large, xl, 2xl, huge, massive
Colors: primary, secondary, accent, success, warning, error, muted
Weights: thin, light, normal, semibold, bold
Effects: rounded, shadow, elevated, glass

Use the :icon[] syntax for Lucide icons:

:icon[heart]{primary} Love this feature
:icon[check-circle]{success large} Completed
:icon[arrow-right] Next step

Popular icons:

Navigation: home, menu, search, settings, user
Actions: check, x, plus, edit, trash
Social: github, twitter, linkedin
UI: heart, star, bookmark, share

Use :::component syntax for component blocks:

:::card {elevated hover-lift}
## Card Title {large-bold}

Card content with automatic styling.

[Button Text](#){button primary}
:::

Built-in components:

Containers: card, container, grid
Interactive: tabs, accordion, carousel, modal, tooltip
UI: alert, button, badge, avatar

Add frosted glass effects:

:::card {subtle-glass}
Light frosted glass (90% transparency)
:::

:::card {light-glass}
Medium frosted glass (75% transparency)
:::

:::card {heavy-glass}
Heavy frosted glass (60% transparency)
:::

All glass effects include:

Backdrop blur
Gradient borders
Subtle shadows
Smooth transitions

Dark Mode Guide

Dark Mode is Automatic

Every Taildown document includes dark mode by default:

Features:

Auto-detection of system preference
Floating toggle button (bottom-right)
LocalStorage persistence
Smooth 300ms transitions
CSS variables for colors
Zero configuration required

How it works:

First Visit: Detects system dark mode preference (prefers-color-scheme)
Toggle: Click the moon/sun button to switch themes
Persistence: Your choice is saved to localStorage
Consistency: Same theme on all future visits

CSS Variables:

:root {
  --background: #ffffff;
  --foreground: #111827;
  --primary: #3b82f6;
}

.dark {
  --background: #030712;
  --foreground: #f9fafb;
  --primary: #3b82f6;
}

All components automatically adapt to dark mode!

Next Steps

Syntax Guide

Deep dive into Taildown syntax and capabilities.

Read Guide

Plain English

Complete reference of all styling shorthands.

View Reference

Components

Explore all 18+ built-in components.

Browse Components

You're ready to start! Create your first document and see the magic happen. Remember, dark mode works automatically - just try clicking the toggle button!

Back to Home