DARE Engine Documentation

Welcome to the official documentation for the DARE Engine, an AI-native, token-efficient markup language explicitly designed for generating pixel-perfect PDF documents.

Deep Introduction

DARE (Document Assembly and Rendering Engine) was born out of the need to bridge the gap between AI generation and precise document rendering. Traditional tools like HTML/CSS or LaTeX are often too verbose, unpredictable, or difficult for AI models to reliably construct into perfect PDFs without running into token limits or layout hallucinations.

DARE introduces a minimalistic, token-efficient syntax that Large Language Models (LLMs) can easily write, paired with a robust rendering engine built on top of

pdfmake

. The engine compiles DARE markup directly into high-quality PDFs, ensuring that the visual output matches the AI's structural intent.

Why DARE?

Token-Efficient: Minimalist syntax heavily reduces the token footprint, making it cheaper and faster for AI to generate complex documents.
AI-Native: Designed specifically for LLMs. The syntax avoids deeply nested tags or complex layout calculations, which often trip up models.
Pixel-Perfect PDF Rendering: 100% native PDF generation. What you declare is exactly what gets rendered. No HTML intermediary, ensuring consistent styling.
Data Binding: Built-in support for injecting external JSON data directly into the document.
Developer Friendly: Easily embeddable as a Node.js library, a CLI tool, or a REST API.

Architecture

The DARE Engine architecture consists of three main stages:

Parser: The
```
src/parser.js
```
module reads the
```
.dare
```
file, resolves external data (if provided), and constructs an Abstract Syntax Tree (AST) representing the document's structure and styling.
Compiler: The AST is transformed into a robust internal schema compatible with the underlying PDF generation library.
Renderer: The
```
src/renderers/pdf.js
```
module takes the compiled schema and generates the final binary PDF output buffer.

Anatomy of a DARE File

A standard DARE file is divided into three distinct sections, separated by

decorators. This separation of concerns allows for clean, readable, and maintainable documents.

@setup

The

@setup

block defines global document settings and styling parameters. This includes page size, margins, default fonts, and global color variables.

@setup
page_size: A4
margin: 40
font_family: Helvetica
primary_color: #FF5733

@data

The

@data

block is used to declare inline JSON data or map external data variables. This is incredibly useful for templating, allowing you to reuse the same

.dare

file for different datasets.

@data
{
  "user": {
    "name": "Jane Doe",
    "role": "Software Engineer"
  },
  "company": "TechCorp"
}

@doc

The

@doc

block is where the actual document content and structure are declared. It uses a token-efficient markup syntax to define layout elements like containers, text blocks, images, tables, and loops, referencing the data defined in the

@data

block.

@doc
container[width: 100%, background: primary_color]:
  text[size: 24, bold: true]: "Invoice for {{user.name}}"
  text[size: 14]: "Company: {{company}}"
  
  table[columns: 2]:
    row:
      cell: "Item"
      cell: "Price"
    row:
      cell: "DARE Engine License"
      cell: "$0.00"

DARE Components Reference

This document provides a highly comprehensive overview of all supported DARE components, including containers, text elements, media, and shapes.

Containers

Containers wrap other components and dictate their layout.

page

Defines a page break or a specific page context. You can style the background of a page or its margins.

Props:
```
bg
```
,
```
p
```
,
```
px
```
,
```
py
```
(for first page padding overrides).

box

A versatile block container. Can be used for backgrounds, borders, or stacking content.

Props:
```
bg
```
,
```
border
```
,
```
borderColor
```
,
```
p
```
,
```
px
```
,
```
py
```
,
```
w
```
,
```
h
```
,
```
unbreakable
```
(prevents page breaks inside the box).

cols

A flex-like row container used to place elements side-by-side.

Props:
```
gap
```
(spacing between columns),
```
n
```
(number of equal-width columns),
```
between
```
(space-between layout),
```
w
```
(column widths).
Usage: Automatically evenly distributes children or respects
```
w
```
property of children.
```
cols(n=3)
```
creates 3 equal columns.

hdr

ftr

Page header and footer components. Can be placed inside a

page

for page-specific headers/footers, or at the root level for global headers/footers.

each

Loops over an array in the data context.

Usage:
```
each(item in items) { txt(item.name) }
```

if

Conditionally renders its content based on a truthy value in the data context.

Usage:
```
if(showDetails) { txt("Details...") }
```

Text Elements

Elements designed for text rendering and formatting.

txt

Standard text block.

Props:
```
size
```
(or
```
fs
```
),
```
color
```
,
```
bold
```
,
```
italic
```
,
```
uppercase
```
,
```
ta
```
(text-align),
```
lh
```
(line-height).

tbl

Creates a table. Data is provided as semicolon-separated rows, with comma-separated cells.

Props:
```
cols
```
(e.g.,
```
cols="2fr 1fr"
```
for column widths),
```
unbreakable
```
.

Usage:

tbl(cols="1fr 1fr") { Header1, Header2; Row1Col1, Row1Col2 }

list

Creates an unordered or ordered list.

Props:
```
type="ol"
```
or
```
type="ordered"
```
for numbered lists,
```
size
```
,
```
color
```
.

badge

A small inline badge with a background color.

Props:
```
bg
```
,
```
color
```
,
```
size
```
.

link

A hyperlinked text element.

Props:
```
url
```
,
```
color
```
,
```
size
```
.

Media Elements

Elements for rendering images, charts, and codes.

img

Renders an image from a URL or local file path.

Props:
```
src
```
,
```
w
```
,
```
h
```
,
```
center
```
,
```
right
```
,
```
left
```
.

bar

pie

line

Renders charts using the QuickChart API.

Props:
```
labels
```
(comma-separated),
```
data
```
(comma-separated numbers),
```
data2
```
,
```
title
```
,
```
color
```
,
```
bg
```
.
Specifics:
```
type="donut"
```
for pie charts.

qr

Generates a QR code.

Props:
```
data
```
,
```
w
```
,
```
h
```
,
```
center
```
.

Shapes & Dividers

shape

Draws a geometric shape.

Props:
```
type
```
(
```
rect
```
,
```
triangle
```
,
```
circle
```
),
```
w
```
,
```
h
```
,
```
bg
```
,
```
color
```
,
```
border
```
.

hr

line

Draws a horizontal rule/line.

Props:
```
h
```
(thickness),
```
color
```
.

sp

Spacer element to add vertical space.

Props:
```
h
```
(height).

DARE Styling Reference

This document covers all styling properties, shorthand mappings, typography, and layout flags supported by DARE.

Shorthand CSS Mappings

DARE provides an extensive set of shorthand attributes for quick and token-efficient styling.

Dimensions

```
w
```
: width
```
h
```
: height
```
minw
```
,
```
minh
```
: min-width, min-height
```
maxw
```
,
```
maxh
```
: max-width, max-height

Padding & Margin

```
p
```
: padding (all sides)
```
pt
```
,
```
pb
```
,
```
pl
```
,
```
pr
```
: padding top, bottom, left, right
```
px
```
: padding horizontal (left/right)
```
py
```
: padding vertical (top/bottom)
```
m
```
: margin (all sides)
```
mt
```
,
```
mb
```
,
```
ml
```
,
```
mr
```
: margin top, bottom, left, right
```
mx
```
: margin horizontal
```
my
```
: margin vertical

Colors & Backgrounds

```
bg
```
: background color
```
color
```
: text color
```
borderColor
```
: border color

Borders

```
border
```
: border width/style
```
r
```
or
```
rounded
```
: border-radius

Typography Shorthands

```
size
```
or
```
fs
```
: font-size (automatically mapped to
```
pt
```
)
```
font
```
or
```
ff
```
: font-family
```
line
```
or
```
lh
```
: line-height
```
ta
```
: text-align
```
td
```
: text-decoration
```
tt
```
: text-transform
```
ls
```
: letter-spacing
```
ws
```
: white-space
```
fw
```
: font-weight

Typography Flags

Boolean flags can be used directly on elements to apply typography styles instantly:

```
bold
```
: Applies bold font-weight.
```
italic
```
: Applies italic font-style.
```
underline
```
: Applies underline text-decoration.
```
strikethrough
```
: Applies line-through text-decoration.
```
uppercase
```
: Transforms text to uppercase.
```
lowercase
```
: Transforms text to lowercase.
```
capitalize
```
: Capitalizes the first letter of each word.

Layout Flags

These boolean flags control how elements are arranged and displayed:

```
center
```
: Centers the element or its text. For boxes, it centers the box in its parent.
```
left
```
,
```
right
```
: Aligns content or the container itself to the left or right.
```
row
```
: Forces a flex row layout (children side-by-side).
```
col
```
: Forces a flex column layout (stack).
```
between
```
: Applies
```
space-between
```
alignment for rows/columns.
```
around
```
: Applies
```
space-around
```
alignment.
```
evenly
```
: Applies
```
space-evenly
```
alignment.
```
wrap
```
,
```
nowrap
```
: Controls flex wrapping.
```
stretch
```
,
```
start
```
,
```
end
```
: Controls cross-axis alignment.
```
unbreakable
```
or
```
nobreak
```
: Prevents page breaks from occurring inside the component (highly useful for
```
box
```
and
```
tbl
```
).

Unit Auto-Completion

By default, numeric values for dimensions (like

w="50"

) are automatically appended with

mm

in the CSS renderer, or accurately converted to points (

pt

) in the PDF renderer. Certain properties (like

opacity

z-index

line-height

flex

) are unitless.

DARE Engine Usage

The DARE Engine is highly flexible and can be integrated into your workflow in three primary ways: as a Command Line Interface (CLI), as a Node.js Library, or as a standalone REST API.

1. CLI Usage

The Command Line Interface is the easiest way to compile

.dare

files into PDFs directly from your terminal.

Basic Compilation

You can run the engine using

npx

(if installed globally or via package scripts) or directly via Node:

# Using npx (if configured)
npx dare compile input.dare -o output.pdf

# Or directly using the CLI script
node cli.js input.dare output.pdf

Passing JSON Data

DARE supports data binding. You can pass an external JSON file to populate variables within your

.dare

document using the

--data

flag.

node cli.js input.dare output.pdf --data data.json

Options:

```
--help, -h
```
: Show help message and usage examples.
```
--version, -v
```
: Show the current version of the DARE Engine.

2. Node.js Library

You can embed the DARE Engine directly into your Node.js applications to generate PDFs programmatically. The engine exposes two main functions:

convertFile

and

convertString

Installation

Make sure to require the library in your project:

const { convertFile, convertString } = require('dare-engine');

convertFile(inputPath, outputPath, dataPath)

Reads a

.dare

file from disk and saves the resulting PDF.

const path = require('path');
const { convertFile } = require('dare-engine');

async function generateInvoice() {
    const input = path.join(__dirname, 'invoice.dare');
    const output = path.join(__dirname, 'invoice.pdf');
    const data = path.join(__dirname, 'customer.json'); // Optional

    try {
        const resultPath = await convertFile(input, output, data);
        console.log(`PDF successfully generated at: ${resultPath}`);
    } catch (error) {
        console.error('Error generating PDF:', error);
    }
}

generateInvoice();

convertString(dareCode, options)

Compiles a DARE markup string directly into a PDF buffer, useful for on-the-fly generation without touching the filesystem.

const { convertString } = require('dare-engine');
const fs = require('fs').promises;

async function compileString() {
    const code = `
    @setup
    page_size: A4
    @doc
    text[size: 20]: "Hello {{name}}!"
    `;

    const options = {
        data: { name: "World" }
    };

    try {
        const pdfBuffer = await convertString(code, options);
        await fs.writeFile('hello.pdf', pdfBuffer);
        console.log('PDF saved!');
    } catch (error) {
        console.error(error);
    }
}

compileString();

3. REST API

The DARE Engine includes an Express-based REST API for rendering documents over HTTP. This is ideal for microservice architectures or remote rendering.

Starting the Server

Start the server locally using npm or by running the script directly:

npm start
# or
node server.js

The server will start on port

(or

process.env.PORT

Endpoints

POST /api/render

Generates a PDF from DARE code.

Payload Format 1 (JSON): Send a JSON payload containing the

code

and optional

data

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "code": "@setup\npage_size: A4\n@doc\ntext: \"Hello {{name}}\"",
    "data": { "name": "API User" }
  }' \
  --output result.pdf

Payload Format 2 (Plain Text): Send the DARE code directly as raw text.

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: text/plain" \
  -d '@setup
page_size: A4
@doc
text: "Hello World"' \
  --output result.pdf

POST /api/preview

(Legacy) This endpoint previously returned an HTML preview. In DARE v2.0, this is deprecated as the engine is now 100% native PDF. It will return a

410 Gone

status indicating you should use

/api/render

GET /health

Returns a health check status to ensure the API is running.

Deployment on Render.com

The DARE Engine is fully configured for deployment on Render.com. The repository includes a

render.yaml

configuration file for a one-click Web Service deployment.

render.yaml

spec:

Type:
```
web
```
Environment:
```
node
```
Build Command:
```
npm install
```
Start Command:
```
node server.js
```
Port:
```
10000
```
(Customizable via environment variables)
Health Check:
```
/health
```

Simply connect your repository to Render, and it will automatically deploy the API server using this configuration.

DARE Documentation

DARE Engine Documentation

Deep Introduction

Why DARE?

Architecture

Anatomy of a DARE File

1. @setup

2. @data

3. @doc

DARE Components Reference

Containers

page

box

cols

hdr & ftr

each

if

Text Elements

txt

tbl

list

badge

link

Media Elements

img

bar & pie & line

qr

Shapes & Dividers

shape

hr & line

sp

DARE Styling Reference

Shorthand CSS Mappings

Dimensions

Padding & Margin

Colors & Backgrounds

Borders

Typography Shorthands

Typography Flags

Layout Flags

Unit Auto-Completion

DARE Engine Usage

1. CLI Usage

Basic Compilation

Passing JSON Data

2. Node.js Library

Installation

convertFile(inputPath, outputPath, dataPath)

convertString(dareCode, options)

3. REST API

Starting the Server

Endpoints

POST /api/render

POST /api/preview

GET /health

Deployment on Render.com

1.
`@setup`

2.
`@data`

3.
`@doc`

`page`

`box`

`cols`

`hdr`
&
`ftr`

`each`

`if`

`txt`

`tbl`

`list`

`badge`

`link`

`img`

`bar`
&
`pie`
&
`line`

`qr`

`shape`

`hr`
&
`line`

`sp`

`convertFile(inputPath, outputPath, dataPath)`

`convertString(dareCode, options)`

`POST /api/render`

`POST /api/preview`

`GET /health`