HTML Block Includes Tutorial - HTML Blocks Tutorial

Creating Reusable HTML Widgets

Learn how to use HTML block includes to build component libraries

Index: tutorial on HTML block includes

Interactive Widget Examples

Welcome to interactive widget examples

Index page information - specific to widgets tutorial

Index: tutorial on HTML block includes

Why Use HTML Blocks and Markdown Together?

HTML blocks provide the structure (widgets, layouts, navigation), while markdown provides the content (documentation, articles, tutorials).

This separation gives you:

🏗️ Reusable Components - Write once, use everywhere
📝 Easy Content Updates - Markdown is simple to edit
🎨 Consistent Design - Widgets ensure UI consistency
🔧 Maintainable Code - Clear separation of concerns

Real-World Example

This very tutorial uses both:

HTML blocks for alerts, cards, and navigation widgets
Markdown for the tutorial content you're reading now
Variables for dynamic values and configuration

Let's explore how to build your own widget library!

Example Widgets

1. Alert Boxes

Create consistent alert components:

2. Card Components

Build reusable card layouts:

Basic Card Widget

This is a simple card component that can be reused across pages.

Learn more →

Featured

Featured Widget

Featured cards stand out with special styling and multiple actions.

3. UI Elements

Common interface components:

How It Works

1. Create a widget in `blocks/`:

<!-- blocks/alert-info.html -->
<div class="alert alert-info">
    <strong>ℹ️ Info:</strong> 💬alert-message
</div>

2. Configure in `ssi-config.toml`:

[[step]]
emoji = "📎"
path = "blocks"
processing = "html"

3. Use anywhere with `📎widget-name`:

<section>
    <h2>Notifications</h2>
    📎alert-info
    📎alert-warning
</section>

Guidelines

📝 Use Semantic HTML

Structure your templates with meaningful HTML5 elements.

🎨 Separate Concerns

Keep content, structure, and presentation in separate files.

🔧 Reuse Components

Create reusable blocks for common UI patterns.

⚡ Optimize Loading

Minimize file sizes and reduce HTTP requests.

♿ Ensure Accessibility

Follow WCAG guidelines for inclusive design.

📱 Mobile First

Design for mobile devices, then enhance for larger screens.