Public API

The public API consists of all exported functions, macros, and types that are intended for end users. These APIs are stable and follow semantic versioning - breaking changes will only occur in major version updates. The public API includes the core @render macro, component definition utilities like @component and @deftag, security features like SafeString, and all the HTML element macros available through HypertextTemplates.Elements. These are the building blocks you'll use to create templates and components in your applications.

HypertextTemplates.HypertextTemplates — Module

HypertextTemplates

A hypertext templating DSL for Julia that allows writing HTML using native Julia syntax.

HypertextTemplates provides a macro-based DSL where all HTML elements are exposed as macros (e.g., @div, @p). It uses a special {} syntax for attributes that mimics NamedTuples, allowing natural integration of Julia control flow directly in templates.

Key Features

Zero-allocation rendering: Direct IO streaming without intermediate DOM
Component system: Reusable components with props and slots
Auto-escaping: Automatic HTML escaping for security (bypass with SafeString)
Streaming support: Efficient chunked rendering for large documents
Markdown integration: Render Markdown files as components (requires CommonMark.jl)

Basic Usage

using HypertextTemplates, HypertextTemplates.Elements

# Simple rendering
@render @div {class = "greeting"} "Hello, World!"

# Components with slots
@component function card(; title)
    @div {class = "card"} begin
        @h2 $title
        @div {class = "body"} @__slot__
    end
end

Main Exports

@render: Render templates to strings or IO
@component: Define reusable components
@deftag: Create macro shortcuts for components
SafeString: Mark content as pre-escaped HTML
StreamingRender: Iterator for chunked rendering
@<: Dynamic component/element rendering

See the documentation for detailed examples and advanced features.

source

HypertextTemplates.SafeString — Type

SafeString(str::String)

A string wrapper that bypasses automatic HTML escaping.

By default, all string content is HTML-escaped to prevent XSS attacks. SafeString marks content as pre-escaped or trusted HTML that should be rendered as-is.

Security Risk

Only use SafeString with content you trust completely. Never wrap user input directly with SafeString without proper sanitization. This can lead to XSS vulnerabilities.

Arguments

str::String: The HTML string to mark as safe

Examples

julia> using HypertextTemplates, HypertextTemplates.Elements

julia> # Normal strings are escaped
       @render @div "<b>Bold</b>"
"<div>&lt;b&gt;Bold&lt;/b&gt;</div>"

julia> # SafeString content is not escaped
       @render @div $(SafeString("<b>Bold</b>"))
"<div><b>Bold</b></div>"

julia> # Common use case: pre-rendered markdown
       markdown_html = "<p>Already <em>escaped</em> content</p>";

julia> @render @article $(SafeString(markdown_html))
"<article><p>Already <em>escaped</em> content</p></article>"

Security best practices

# GOOD: Content from trusted sources
html = markdown_to_html(user_content)  # Markdown processor escapes content
@render @div SafeString(html)

# GOOD: Your own HTML generation
safe_html = "<span class="highlight">Important</span>"
@render @div SafeString(safe_html)

# BAD: Never do this with user input!
user_input = get_user_input()
@render @div SafeString(user_input)  # DANGER: XSS vulnerability!

See also: @render, escape_html, @esc_str

source

HypertextTemplates.StreamingRender — Type

StreamingRender(func; kwargs...)
StreamingRender(; kwargs...) do io
    # render content
end

Create an iterator for streaming template rendering.

StreamingRender enables efficient rendering of large templates by yielding chunks of output as they become available. This is particularly useful for:

HTTP streaming responses
Large documents that would consume too much memory if rendered at once
Progressive rendering where content appears as it's generated

The function uses intelligent micro-batching: large writes (≥64 bytes) are sent immediately for low latency, while smaller writes are batched for efficiency.

Arguments

func: Function that takes an io argument to pass to @render

Keywords

buffer_size::Int=32: Number of chunks the channel can buffer before blocking
chunk_size::Int=4096: Legacy parameter (kept for compatibility, no longer used)
immediate_threshold::Int=64: Bytes above which writes bypass buffering for low latency

Examples

julia> using HypertextTemplates, HypertextTemplates.Elements

julia> # Collect all chunks (for demonstration)
       chunks = String[];

julia> for chunk in StreamingRender() do io
           @render io @div begin
               @h1 "Header"
               @p "Content"
           end
       end
           push!(chunks, String(chunk))
       end

julia> join(chunks)
"<div><h1>Header</h1><p>Content</p></div>"

HTTP streaming example

using HTTP
using HypertextTemplates, HypertextTemplates.Elements

function handle_request(req)
    HTTP.Response(200, ["Content-Type" => "text/html"]) do io
        for chunk in StreamingRender() do render_io
            @render render_io @html begin
                @head @title "Streaming Page"
                @body begin
                    @h1 "Live Data"
                    for i in 1:1000
                        @div "Item $i"
                    end
                end
            end
        end
            write(io, chunk)
        end
    end
end

Progressive rendering

# Stream data as it becomes available
for chunk in StreamingRender() do io
    @render io @div begin
        @h1 "Results"
        for result in fetch_results_lazily()
            @article begin
                @h2 result.title
                @p result.content
            end
        end
    end
end
    # Send chunk to client immediately
    write(client_connection, chunk)
    flush(client_connection)
end