# Authorization
Source: https://docs.htmldocs.com/api-reference/authorization



### Getting Started

API requests to htmldocs require an API key which can be obtained from the API tokens section in the [Dashboard](https://htmldocs.com/dashboard).

<Note>
  API keys are scoped to your team. Each API key provides access only to documents and resources owned by that team.
</Note>

### Headers

API keys should be included in the `Authorization` header of your requests using the Bearer token format:

```
Authorization: Bearer YOUR_API_KEY
```

### Content Type

All requests should set the `Content-Type` header to `application/json`.


# Generate Document
Source: https://docs.htmldocs.com/api-reference/generate-document

POST /api/documents/{documentId}
Generates a PDF document from a published document template.

This endpoint is for generating a document based on a template you've published to a team. To publish a document, see the [publish command](a/cli#htmldocs-publish-file).

You can find the ids of your published documents in the [dashboard](https://htmldocs.com/dashboard).


# Generate from HTML
Source: https://docs.htmldocs.com/api-reference/generate-html

POST /api/generate
Generates a PDF document from raw HTML content and/or a URL. If both are provided, the HTML content will be injected into the page at the specified URL.

This endpoint allows you to generate a PDF document directly from HTML content, without needing to publish a template first.

For generating documents from published templates, see the [Generate Document](/api/generate-document) endpoint instead.


# CLI
Source: https://docs.htmldocs.com/cli

After installing the htmldocs package, you can start using the command line interface (CLI).

## `init`

Initializes a new htmldocs project in the current directory.

<CodeGroup>
  ```bash npm theme={null}
  npx htmldocs@latest init
  ```

  ```bash pnpm theme={null}
  pnpx htmldocs@latest init
  ```

  ```bash yarn theme={null}
  yarn dlx htmldocs@latest init
  ```

  ```bash bun theme={null}
  bunx htmldocs@latest init
  ```
</CodeGroup>

## `login`

Authenticates the CLI with the cloud. This allows you to publish your documents to the cloud.

<CodeGroup>
  ```bash npm theme={null}
  npx htmldocs@latest login
  ```

  ```bash pnpm theme={null}
  pnpx htmldocs@latest login
  ```

  ```bash yarn theme={null}
  yarn dlx htmldocs@latest login
  ```

  ```bash bun theme={null}
  bunx htmldocs@latest login
  ```
</CodeGroup>

## `dev`

Starts a local development server that will watch your files and automatically rebuild your document template when you make changes. Login not required.

<CodeGroup>
  ```bash npm theme={null}
  npx htmldocs@latest dev
  ```

  ```bash pnpm theme={null}
  pnpx htmldocs@latest dev
  ```

  ```bash yarn theme={null}
  yarn dlx htmldocs@latest dev
  ```

  ```bash bun theme={null}
  bunx htmldocs@latest dev
  ```
</CodeGroup>

**Options**

<ResponseField name="--dir" type="string">
  Change the directory of your document templates.
</ResponseField>

<ResponseField name="--port" type="string">
  Port to run dev server on
</ResponseField>

## `publish <file>`

Publishes the document to the cloud for API use. Must be [authenticated](/cli#login).

<Warning>Be sure to run this from the root of your project.</Warning>

<CodeGroup>
  ```bash npm theme={null}
  npx htmldocs@latest publish <file>
  ```

  ```bash pnpm theme={null}
  pnpx htmldocs@latest publish <file>
  ```

  ```bash yarn theme={null}
  yarn dlx htmldocs@latest publish <file>
  ```

  ```bash bun theme={null}
  bunx htmldocs@latest publish <file>
  ```
</CodeGroup>

**Options**

<ResponseField name="file" type="string">
  The file path of the document to publish.
</ResponseField>

## `--help`

Shows all available commands and options.

<CodeGroup>
  ```bash npm theme={null}
  npx htmldocs@latest --help
  ```

  ```bash pnpm theme={null}
  pnpx htmldocs@latest --help
  ```

  ```bash yarn theme={null}
  yarn dlx htmldocs@latest --help
  ```

  ```bash bun theme={null}
  bunx htmldocs@latest --help
  ```
</CodeGroup>

**Options**

<ResponseField name="-v, --verbose" type="boolean">
  Enable verbose logging
</ResponseField>

**F.A.Q**

<AccordionGroup>
  <Accordion title="How can I define props specific to the document's preview?">
    You can define preview props for your document by adding a `PreviewProps` property to your default export. For example:

    ```jsx theme={null}
    export default function Document(props) {
      return (
        <div>
          <h1>{props.title}</h1>
          <p>{props.content}</p>
        </div>
      );
    }

    Document.PreviewProps = {
      title: "Preview Title",
      content: "This is preview content",
    };
    ```

    These props will be used when previewing the document in the development server.
  </Accordion>

  <Accordion title="How do I set up authentication for publishing?">
    To publish documents, you need to authenticate with the cloud service. Use the `htmldocs login` command to start the authentication process. This will open a browser window where you can select a team and complete the authentication. Once authenticated, your tokens will be securely stored for future use.
  </Accordion>

  <Accordion title="Where are the built files stored?">
    By default, built files are stored in a `dist` directory in your project root. You can customize this location by setting the `NEXT_PUBLIC_USER_PROJECT_LOCATION` environment variable.
  </Accordion>
</AccordionGroup>


# Comparing htmldocs
Source: https://docs.htmldocs.com/comparison

See how htmldocs compares to other document creation solutions

| Feature              | Traditional Documents<br />(Word, Google Docs) | LaTeX Documents<br />(Overleaf, TeXStudio) | Freeform Documents<br />(Figma, Sketch) | Web Documents<br />(htmldocs) |
| -------------------- | :--------------------------------------------: | :----------------------------------------: | :-------------------------------------: | :---------------------------: |
| Content Structure    |                 Semi-Structured                |              Highly Structured             |                 Freeform                |       Highly Structured       |
| Learning Curve       |                    ✅ Simple                    |                  ❌ Complex                 |                 ✅ Simple                |            ✅ Simple           |
| Template Variables   |                    ❌ Limited                   |                  ❌ Limited                 |                ❌ Limited                |          ✅ Supported          |
| Styling              |                     ✅ Basic                    |                  ❌ Complex                 |                ✅ Advanced               |           ✅ Advanced          |
| Version Control      |                    ❌ Limited                   |                 ✅ Supported                |                ❌ Limited                |          ✅ Supported          |
| Document Consistency |                    ❌ Limited                   |                 ✅ Supported                |               ✅ Supported               |          ✅ Supported          |
| External Libraries   |                    ❌ Limited                   |                 ✅ Supported                |                ❌ Limited                |          ✅ Supported          |
| Automation / API     |                    ❌ Limited                   |                  ❌ Limited                 |                ❌ Limited                |          ✅ Supported          |
| Developer Plugins    |                    ❌ Limited                   |                  ❌ Limited                 |                ❌ Limited                |          ✅ Supported          |
| Live Preview         |                   ✅ Supported                  |                  ❌ Limited                 |               ✅ Supported               |          ✅ Supported          |
| CI/CD Integration    |                    ❌ Limited                   |                 ⚠️ Partial                 |                ❌ Limited                |          ✅ Supported          |
| Type Safety          |                    ❌ Limited                   |                  ❌ Limited                 |                ❌ Limited                |          ✅ Supported          |
| AI Integrations      |                    ❌ Limited                   |                  ❌ Limited                 |                ❌ Limited                |          ✅ Supported          |

## When to Choose htmldocs

htmldocs is the ideal choice when you need:

* **Programmatic Generation**: Create documents dynamically using data and code
* **Consistent Branding**: Maintain uniform styling across all documents through components
* **Modern Development**: Leverage React, TypeScript, and the npm ecosystem
* **CI/CD**: Push new document versions with CI/CD pipelines
* **Version Control**: Track changes and collaborate using Git
* **Developer-First**: Use familiar tools and workflows in a code-first environment
* **Integrated AI Workflow**: Generate document content seamlessly with AI tools like Cursor/Copilot
* **Structured Documents**: Create structured documents with precise typesetting and predictable layouts

While traditional tools like Word or LaTeX have their place, htmldocs brings document creation into the modern web development ecosystem, offering powerful features for teams that need more than just basic word processing.


# Document
Source: https://docs.htmldocs.com/components/document

A component for creating document layouts

The `Document` component is used to create a layout for document pages. It provides a structured way to set the size, orientation, and margin of the document.

## Usage

<CodeGroup>
  ```jsx Document Example theme={null}
  import Document from './Document';

  const MyDocument = () => (
    <Document size="A4" orientation="portrait" margin="0.39in">
      <h1>My Document Content</h1>
      <p>This is the content of my document.</p>
    </Document>
  );
  ```
</CodeGroup>

## Props

<ResponseField name="size" type="string">
  The size of the document. Must be one of: "A3", "A4", "A5", "letter", or "legal".
</ResponseField>

<ResponseField name="orientation" type="string">
  The orientation of the document. Must be either "portrait" or "landscape".
</ResponseField>

<ResponseField name="margin" type="string | React.CSSProperties['margin']">
  The margin of the document. Can be a string (e.g., "0.39in") or a valid CSS margin value.
</ResponseField>

<ResponseField name="children" type="React.ReactNode">
  The content of the document.
</ResponseField>

## Examples

### A4 Portrait Document

<CodeGroup>
  ```jsx A4 Portrait theme={null}
  import Document from './Document';

  const A4Portrait = () => (
    <Document size="A4" orientation="portrait" margin="1in">
      <h1>A4 Portrait Document</h1>
      <p>This is an A4 portrait document with 1 inch margins.</p>
    </Document>
  );
  ```
</CodeGroup>

### Legal Landscape Document

<CodeGroup>
  ```jsx Legal Landscape theme={null}
  import Document from './Document';

  const LegalLandscape = () => (
    <Document size="legal" orientation="landscape" margin="0.5in">
      <h1>Legal Landscape Document</h1>
      <p>This is a legal size landscape document with 0.5 inch margins.</p>
    </Document>
  );
  ```
</CodeGroup>


# Footer
Source: https://docs.htmldocs.com/components/footer

Add page numbers and custom footers to your documents

The `Footer` component provides an easy way to add page numbers and custom footers to your documents. It's built on top of the [MarginBox](/components/margin-box) component with additional features for page numbering.

## Usage

<CodeGroup>
  ```jsx Basic Example theme={null}
  import { Footer } from "@htmldocs/react";

  export default function Document() {
    return (
      <Footer />  {/* Renders "Page X of Y" by default */}
    );
  }
  ```
</CodeGroup>

## Props

<ResponseField name="children" type="Function | React.ReactNode">
  Content to render in the footer. Can be either:

  * A function that receives `{ currentPage, totalPages }` elements
  * A React node for static content
  * Omitted to use the default page numbering template
</ResponseField>

<ResponseField name="position" type="MarginBoxPosition">
  Footer position. Inherits all position options from MarginBox component.
</ResponseField>

<ResponseField name="pageType" type="'all' | 'even' | 'odd' | 'blank'">
  Controls which pages the footer appears on.
</ResponseField>

<ResponseField name="className" type="string">
  Custom CSS classes to apply to the footer.
</ResponseField>

<ResponseField name="style" type="React.CSSProperties">
  Custom inline styles for the footer content.
</ResponseField>

<ResponseField name="marginBoxStyles" type="React.CSSProperties">
  Custom styles applied to the MarginBox wrapper.
</ResponseField>

## Examples

### Default Page Numbers

The default template shows "Page X of Y":

<CodeGroup>
  ```jsx Default theme={null}
  <Footer />
  ```
</CodeGroup>

### Custom Page Number Format

Use the function-as-children pattern to customize the page number display:

<CodeGroup>
  ```jsx Custom Format theme={null}
  <Footer>
    {({ currentPage, totalPages }) => (
      <div style={{ fontFamily: 'monospace' }}>
        [{currentPage} / {totalPages}]
      </div>
    )}
  </Footer>
  ```
</CodeGroup>

### Static Footer Content

Provide static content instead of page numbers:

<CodeGroup>
  ```jsx Static Content theme={null}
  <Footer>
    <div style={{ 
      display: 'flex', 
      justifyContent: 'space-between' 
    }}>
      <span>© 2024 Company Name</span>
      <span>Confidential</span>
    </div>
  </Footer>
  ```
</CodeGroup>


# Head
Source: https://docs.htmldocs.com/components/head

Add metadata and external resources to your document

The `Head` component allows you to add metadata and external resources to your document. It can be used to import fonts and icon libraries. It works similarly to Next.js's `Head` component, which hoists the contents to the top of the HTML document.

## Usage

Place the `Head` component inside your document, typically near the top. You can include various HTML elements that you want to be added to the `<head>` section of your page.

<CodeGroup>
  ```jsx Example theme={null}
  import Document from "@htmldocs/core";
  import Head from "@htmldocs/core";

  export default function MyDocument() {
    return (
      <Document>
        <Head>
          <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet" />
        </Head>
        {/* Rest of your document content */}
      </Document>
    );
  }
  ```
</CodeGroup>

<Note>
  The `Head` component doesn't render any visible content.

  It only affects the document's `<head>` section.
</Note>

## Examples

### Adding a Custom Font

<CodeGroup>
  ```jsx Font Example theme={null}
  <Head>
    <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;700&display=swap" rel="stylesheet" />
  </Head>
  ```
</CodeGroup>

### Including an External Script

<CodeGroup>
  ```jsx Script Example theme={null}
  <Head>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
  </Head>
  ```
</CodeGroup>


# MarginBox
Source: https://docs.htmldocs.com/components/margin-box

Position content in page margins for print layouts

The `MarginBox` component allows you to position content in the margins of printed pages. It's particularly useful for adding headers, watermarks, and other content that needs to appear in the margin areas of your printed documents.

<Note>
  For page numbers and footers, we recommend using the [Footer](/components/footer) component which provides built-in page numbering functionality.
</Note>

## Usage

The `MarginBox` component uses CSS Paged Media specifications to position content in specific margin boxes around your page.

<CodeGroup>
  ```jsx Example theme={null}
  import { MarginBox } from "@htmldocs/react";

  export default function Document() {
    return (
      <MarginBox 
        position="top-right" 
        runningName="document-title"
      >
        Quarterly Report
      </MarginBox>
    );
  }
  ```
</CodeGroup>

## Props

<ResponseField name="position" type="string">
  Specifies where the content should appear in the page margins. See [Position Options](#position-options) below for valid values.
</ResponseField>

<ResponseField name="runningName" type="string">
  A unique identifier for this margin box content. Must be unique across your document.
</ResponseField>

<ResponseField name="children" type="React.ReactNode">
  The content to display in the margin box.
</ResponseField>

<ResponseField name="pageType" type="'all' | 'even' | 'odd' | 'blank'">
  Controls which pages the margin box appears on:

  * `'all'`: Appears on all pages
  * `'even'`: Only appears on even-numbered pages
  * `'odd'`: Only appears on odd-numbered pages
  * `'blank'`: Only appears on blank pages
</ResponseField>

<ResponseField name="className" type="string">
  Additional CSS classes to apply to the margin box.
</ResponseField>

<ResponseField name="style" type="React.CSSProperties">
  Custom React CSS styles for the margin box content.
</ResponseField>

<ResponseField name="marginBoxStyles" type="React.CSSProperties">
  CSS styles specifically for the margin box container.
</ResponseField>

## Position Options

The `position` prop accepts the following values:

<CodeGroup>
  ```text Position Values theme={null}
  Top Positions:
  - 'top-left-corner'     // Top left corner of the page
  - 'top-left'           // Top left margin
  - 'top-center'         // Top center margin
  - 'top-right'          // Top right margin
  - 'top-right-corner'   // Top right corner of the page

  Left/Right Positions:
  - 'left-top'           // Left margin, top aligned
  - 'left-middle'        // Left margin, middle aligned
  - 'left-bottom'        // Left margin, bottom aligned
  - 'right-top'          // Right margin, top aligned
  - 'right-middle'       // Right margin, middle aligned
  - 'right-bottom'       // Right margin, bottom aligned

  Bottom Positions:
  - 'bottom-left-corner' // Bottom left corner of the page
  - 'bottom-left'        // Bottom left margin
  - 'bottom-center'      // Bottom center margin
  - 'bottom-right'       // Bottom right margin
  - 'bottom-right-corner'// Bottom right corner of the page
  ```
</CodeGroup>

## Examples

### Document Title Header

<CodeGroup>
  ```jsx Header theme={null}
  <MarginBox 
    position="top-right"
    runningName="document-title"
    pageType="even"
    style={{ 
      fontStyle: 'italic',
      color: '#666'
    }}
  >
    {documentTitle}
  </MarginBox>
  ```
</CodeGroup>

### Watermark

<CodeGroup>
  ```jsx Watermark theme={null}
  <MarginBox 
    position="left-middle"
    runningName="watermark"
    style={{
      fontFamily: 'Arial, sans-serif',
      color: 'rgba(0, 0, 0, 0.1)',
      fontSize: '24px',
      transform: 'rotate(-90deg)'
    }}
  >
    <div>CONFIDENTIAL</div>
  </MarginBox>
  ```
</CodeGroup>


# Page
Source: https://docs.htmldocs.com/components/page

A component for creating page breaks within a document

The `Page` component is used to separate content into distinct pages within a document. It creates a page break after each page.

## Usage

<CodeGroup>
  ```jsx Page Example theme={null}
  import Document from './Document';
  import Page from './Page';

  const MyDocument = () => (
    <Document size="A4" orientation="portrait">
      <Page>
        <h1>My Document Title</h1>
        <p>This is the content of my first page.</p>
      </Page>
      <Page>
        <h2>Second Page</h2>
        <p>This is the content of my second page.</p>
      </Page>
    </Document>
  );
  ```
</CodeGroup>

## Props

<ResponseField name="children" type="React.ReactNode">
  The content to be rendered within the page.
</ResponseField>

<ResponseField name="className" type="string">
  Additional CSS classes to apply to the page.
</ResponseField>

<ResponseField name="style" type="React.CSSProperties">
  Additional inline styles to apply to the page.
</ResponseField>


# Spacer
Source: https://docs.htmldocs.com/components/spacer

Add flexible spacing between elements

The `Spacer` component allows you to add customizable vertical or horizontal space between elements in your document.

<Spacer />

## Usage

Use the `Spacer` component to create gaps between content. You can specify either `height` or `width`.

<CodeGroup>
  ```jsx Vertical Spacer theme={null}
  <Spacer height={50} />
  ```

  ```jsx Horizontal Spacer theme={null}
  <Spacer width={100} />
  ```
</CodeGroup>

<CodeGroup>
  ```jsx Full Example theme={null}
  import Document from './Document';
  import Page from './Page';
  import Head from './Head';
  import Spacer from './Spacer';

  const MyDocument = () => (
    <Document>
      <Head>
        <title>My Document</title>
      </Head>
      <Page>
        <h1>Welcome to My Document</h1>
        <Spacer height={20} />
        <p>This is the first paragraph of my document.</p>
        <Spacer height={30} />
        <h2>Section 1</h2>
        <Spacer height={15} />
        <p>Content for section 1 goes here.</p>
        <Spacer height={50} />
        <h2>Section 2</h2>
        <Spacer height={15} />
        <p>Content for section 2 goes here.</p>
      </Page>
    </Document>
  );

  export default MyDocument;
  ```
</CodeGroup>

## Props

<ResponseField name="height" type="number | string | boolean">
  Vertical space the spacer takes up. Use a number for pixels, a string for other units, or `true` for 100%.
</ResponseField>

<ResponseField name="width" type="number | string | boolean">
  Horizontal space the spacer takes up. Use a number for pixels, a string for other units, or `true` for 100%.
</ResponseField>

<ResponseField name="display" type="string">
  CSS display property of the spacer.
</ResponseField>

## Comparison to LaTeX

The `Spacer` component serves a similar purpose to LaTeX's vertical and horizontal spacing commands:

* `Spacer` with `height` is similar to LaTeX's `\vspace{}`
* `Spacer` with `width` is similar to LaTeX's `\hspace{}`

However, `Spacer` offers more flexibility:

1. **Units**: While LaTeX typically uses pt, em, or ex, `Spacer` can use any CSS unit.
2. **Responsiveness**: `Spacer` can adapt to different screen sizes more easily.
3. **Simplicity**: `Spacer` uses a single component for both vertical and horizontal spacing.

<CodeGroup>
  ```jsx Spacer Example theme={null}
  <Spacer height={20} />
  ```

  ```latex LaTeX Equivalent theme={null}
  \vspace{20pt}
  ```
</CodeGroup>


# Getting Started
Source: https://docs.htmldocs.com/getting-started

Add htmldocs to any React/TypeScript project in minutes.

## Automatic Setup

The easiest way to setup htmldocs is to use our automatic setup script.

1. Run the following command in your terminal:

<CodeGroup>
  ```bash npm theme={null}
  npx htmldocs@latest init
  ```

  ```bash pnpm theme={null}
  pnpx htmldocs@latest init
  ```

  ```bash yarn theme={null}
  yarn dlx htmldocs@latest init
  ```

  ```bash bun theme={null}
  bunx htmldocs@latest init
  ```
</CodeGroup>

This will prompt you for your project name and create a new folder in your current directory.

3. After switching to the folder, you can start the development server by running:

<CodeGroup>
  ```bash npm theme={null}
  npm run dev
  ```

  ```bash pnpm theme={null}
  pnpm dev
  ```

  ```bash yarn theme={null}
  yarn dev
  ```

  ```bash bun theme={null}
  bun dev
  ```
</CodeGroup>

This will start a live preview of your documents in your browser.

<img alt="Dev server preview" />

## Manual Setup

If you prefer to set up htmldocs manually, follow these steps:

1. Install htmldocs in your project:

<CodeGroup>
  ```bash npm theme={null}
  npm install htmldocs @htmldocs/react @htmldocs/render
  ```

  ```bash pnpm theme={null}
  pnpm add htmldocs @htmldocs/react @htmldocs/render
  ```

  ```bash yarn theme={null}
  yarn add htmldocs @htmldocs/react @htmldocs/render
  ```

  ```bash bun theme={null}
  bun add htmldocs @htmldocs/react @htmldocs/render
  ```
</CodeGroup>

2. Add the following script to your `package.json`:

```json theme={null}
{
    "scripts": {
        "dev": "npx htmldocs@latest dev",
    }
}
```

3. Create document template

Create a new folder called `documents` in your project. Then, create a new file called `Book.tsx` in the `documents` folder and include the following code:

```tsx theme={null}
import { Document, Footer } from "@htmldocs/react"
import MarkdownIt from 'markdown-it'

import "~/index.css"

const MARKDOWN_CONTENT = `
# The Art of Programming

## Chapter 1: Fundamentals

Programming is both a science and an art. It requires logical thinking and creative problem-solving. In this book, we will explore the principles that make software development a fascinating discipline.

### 1.1 The Programming Mindset

To become an effective programmer, one must develop a particular way of thinking. This includes:

- Breaking down complex problems into manageable parts
- Thinking algorithmically about solutions
- Understanding data structures and their applications
- Embracing continuous learning and adaptation

The journey of a programmer is one of constant growth and discovery.
`

const md = new MarkdownIt({ html: true })

function Book() {
  const html = md.render(MARKDOWN_CONTENT)
  
  return (
    <Document size="6in 9in" orientation="portrait" margin="0.75in">
      <article className="prose max-w-none font-serif">
        <div dangerouslySetInnerHTML={{ __html: html }} />
      </article>

      <Footer 
        position="bottom-center"
        className="font-serif text-sm"
        children={({ currentPage }) => currentPage}
        marginBoxStyles={{
          marginBottom: '0.25in',
        }}
      />
    </Document>
  )
}

Book.documentId = "book"

export default Book
```

4. Run the development server by running:

<CodeGroup>
  ```bash npm theme={null}
  npm run dev
  ```

  ```bash pnpm theme={null}
  pnpm dev
  ```

  ```bash yarn theme={null}
  yarn dev
  ```

  ```bash bun theme={null}
  bun dev
  ```
</CodeGroup>

This will start a live preview of your documents in your browser.


# Resend
Source: https://docs.htmldocs.com/integrations/resend

Learn how to generate and send invoice PDFs as email attachments using Resend

## Overview

Learn to generate a simple invoice and send it as an email attachment using [Resend](https://resend.com).

## Prerequisites

1. [Publish the invoice template](/usage/publishing-to-the-cloud) to htmldocs.

2. Install the required dependencies:

<CodeGroup>
  ```bash npm theme={null}
  npm install resend
  ```

  ```bash pnpm theme={null}
  pnpm install resend
  ```

  ```bash yarn theme={null}
  yarn install resend
  ```

  ```bash bun theme={null}
  bun install resend
  ```
</CodeGroup>

3. Set up your Resend API key in your environment:

```bash theme={null}
RESEND_API_KEY=your_resend_api_key
```

## Implementation

```typescript theme={null}
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

interface BilledTo {
  name: string;
  address: string;
  city: string;
  state: string;
  zip: string;
  phone: string;
}

interface YourCompany {
  name: string;
  address: string;
  city: string;
  state: string;
  zip: string;
  taxId: string;
  phone: string;
  email: string;
}

interface Service {
  name: string;
  description?: string;
  quantity: number;
  rate: number;
}

async function sendInvoiceEmail() {
  try {
    // 1. Generate the invoice using htmldocs API
    const response = await fetch('https://api.htmldocs.com/api/documents/invoice', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HTMLDOCS_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        format: 'pdf',
        props: {
          billedTo: {
            name: "Acme Corp",
            address: "123 Business Ave",
            city: "San Francisco",
            state: "CA",
            zip: "94107",
            phone: "555-0123"
          },
          yourCompany: {
            name: "Your Company",
            address: "456 Banana Rd.",
            city: "San Francisco",
            state: "CA",
            zip: "94107",
            taxId: "00XXXXX1234X0XX",
            phone: "123-456-7890",
            email: "hello@email.com"
          },
          services: [
            {
              name: "Premium License",
              description: "Annual subscription",
              quantity: 1,
              rate: 999.00
            }
          ]
        }
      })
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => null);
      throw new Error(
        `Failed to generate invoice: ${response.status} ${response.statusText}${
          errorData ? ` - ${JSON.stringify(errorData)}` : ''
        }`
      );
    }

    const documentBuffer = await response.arrayBuffer();

    // 2. Send email with the generated invoice
    const data = await resend.emails.send({
      from: 'you@yourdomain.com',
      to: 'recipient@example.com',
      subject: 'Invoice for Your Recent Services',
      attachments: [
        {
          content: Buffer.from(documentBuffer),
          filename: 'invoice.pdf',
        },
      ],
      html: `
        <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
          <h2 style="color: #1a1a1a;">Your Invoice</h2>
          
          <p style="color: #4a4a4a; font-size: 16px; line-height: 1.5;">
            Thank you for your business. Please find your invoice attached to this email.
          </p>
          
          <p style="color: #4a4a4a; font-size: 16px; line-height: 1.5;">
            Payment is due within 15 days from the invoice date. For your convenience, 
            payment instructions are included in the invoice.
          </p>
          
          <p style="color: #4a4a4a; font-size: 16px; line-height: 1.5;">
            If you have any questions about this invoice, please contact our billing department 
            using the contact information provided in the invoice.
          </p>
          
          <hr style="border: none; border-top: 1px solid #e1e1e1; margin: 30px 0;" />
          
          <p style="color: #898989; font-size: 14px;">
            This is an automated message. Please do not reply to this email.
          </p>
        </div>
      `,
    });

    console.log('Email sent successfully:', data);
  } catch (error) {
    if (error instanceof Error) {
      console.error('Error:', error.message);
    } else {
      console.error('Unknown error:', error);
    }
    throw error; // Re-throw to handle it in the calling code
  }
}
```

For more information about document generation, see our [API Reference](/api-reference/generate-document).


# Introduction
Source: https://docs.htmldocs.com/introduction



<img alt="htmldocs editor" />

PDF document creation is stuck in the past, from clunky Word docs to complex LaTeX to outdated tools. htmldocs brings document generation into 2025 with a modern developer experience using **React**, **TypeScript**, and **Tailwind**.

## Key Features

* 📌 Support for the latest CSS features like margin boxes and flexbox
* 🧩 Collection of unstyled components for document layout
* 📄 JSX templating system for building dynamic documents
* 🔗 Full TypeScript support for type safety
* ⚡ Dynamic data integration through props and APIs
* 📊 Real-time preview server with hot reloading

## Example

To see htmldocs in action, here's a simple example of a dynamic invoice template:

![Invoice template with htmldocs](https://github.com/user-attachments/assets/40e4ec91-e5eb-483a-ba28-14c6fd57ad8b)

Creating multiple invoices is as simple as passing different customer information through props. Here's how you can generate a new invoice by updating the customer details:

```tsx theme={null}
<Invoice 
  customer={{
    name: "John Doe",
    address: "456 Main St",
    city: "Anytown",
    state: "CA",
    zip: "12345",
    phone: "123-456-7890",
  }}
  items={[
    {
      name: "Website Development",
      description: "Frontend implementation with React",
      price: 2000.00,
      quantity: 1
    },
    {
      name: "UI/UX Design",
      description: "Custom design system creation",
      price: 1500.00,
      quantity: 1
    }
  ]}
/>
```

<CardGroup>
  <Card title="Automatic Installation" icon="rocket" href="/getting-started#automatic-setup">
    Use the CLI tool to quickly set up htmldocs in your project with minimal configuration.
  </Card>

  <Card title="Manual Installation" icon="screwdriver-wrench" href="/getting-started#manual-setup">
    Integrate htmldocs step-by-step into your existing TypeScript project.
  </Card>
</CardGroup>

## Components

htmldocs comes with a set of standardized components that makes it easy to build documents.

<CardGroup>
  <Card title="Document" icon="file-lines" href="/components/document">
    The root wrapper component representing a document.
  </Card>

  <Card title="Page" icon="file" href="/components/page">
    A single page within a document.
  </Card>

  <Card title="Head" icon="head-side" href="/components/head">
    Add custom content to the top of your document pages.
  </Card>

  <Card title="Spacer" icon="table" href="/components/spacer">
    Add vertical space between document pages.
  </Card>

  <Card title="MarginBox" icon="border-all" href="/components/margin-box">
    Position content in the margins of printed pages.
  </Card>

  <Card title="Footer" icon="shoe-prints" href="/components/footer">
    Add page numbers and custom footers to your documents.
  </Card>
</CardGroup>


# Custom Fonts
Source: https://docs.htmldocs.com/usage/custom-fonts



## Using Google Fonts

To use [Google Fonts](https://fonts.google.com/) in your documents, import them in your document's `<Head>` component:

```tsx theme={null}
import { Document, Head } from "@htmldocs/react"

function MyDocument() {
  return (
    <Document>
      <Head>
        <link
          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
          rel="stylesheet"
        />
      </Head>
      <div style={{ fontFamily: 'Inter, sans-serif' }}>
        Text using Google Font (Inter)
      </div>
    </Document>
  )
}
```

## Using Local Fonts

For local fonts, place your font files in the `/documents/static` directory and use `@font-face` to define them:

<Note>
  All font files must be placed in the `/documents/static` directory of your project. This is the required location for serving static assets in your document templates.
</Note>

```tsx theme={null}
import { Document, Head } from "@htmldocs/react"

function MyDocument() {
  return (
    <Document>
      <Head>
        <style>
          {`
            @font-face {
              font-family: 'CustomFont';
              src: url('/static/fonts/CustomFont.woff2') format('woff2'),
                   url('/static/fonts/CustomFont.woff') format('woff');
              font-weight: normal;
              font-style: normal;
              font-display: swap;
            }
          `}
        </style>
      </Head>
      <div style={{ fontFamily: 'CustomFont' }}>
        Text using local custom font
      </div>
    </Document>
  )
}
```


# Publishing to the Cloud
Source: https://docs.htmldocs.com/usage/publishing-to-the-cloud

Publish and generate documents from your document templates using the API

## Prerequisites

This command installs or updates the CLI globally on your system.

If you haven't already, run the following command to create a new htmldocs project:

```bash theme={null}
npx htmldocs@latest init
```

## Authentication

Before publishing, you'll need to authenticate with the htmldocs cloud platform:

```bash theme={null}
npx htmldocs@latest login
```

This command will open a browser window where you can:

1. Select your team
2. Complete the authentication process
3. Store your credentials securely for future use

## Publishing Templates

Once authenticated, you can publish your document templates using the `publish` command:

<Warning>Be sure to run this from the root of your project.</Warning>

```bash theme={null}
npx htmldocs@latest publish ./documents/templates/Invoice.tsx
```

<Note>
  Make sure your template has a unique `documentId` defined before publishing:

  ```tsx theme={null}
  Invoice.documentId = "invoice";
  export default Invoice;
  ```
</Note>

## Generating Documents via API

After publishing, you can generate documents using the REST API. First, obtain an API key from the [Dashboard](https://htmldocs.com/dashboard).

### API Authentication

Include your API key in requests using the Bearer token format:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Note>
  API keys are scoped to your team and provide access only to documents owned by that team.
</Note>

### Making API Requests

To generate a document, send a POST request to the generation endpoint with your document variables:

```bash theme={null}
curl -X POST https://api.htmldocs.com/api/documents/invoice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "props": {
      "billedTo": {
        "name": "Josiah Zhang",
        "address": "123 Elm Street",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345",
        "phone": "123-456-7890"
      },
      "yourCompany": {
        "name": "Your Company",
        "address": "456 Banana Rd.",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "taxId": "00XXXXX1234X0XX",
        "phone": "123-456-7890",
        "email": "hello@email.com"
      },
      "services": [
        {
          "name": "Design",
          "description": "Website redesign and branding",
          "quantity": 1,
          "rate": 1000
        },
        {
          "name": "Consulting",
          "description": "Technical architecture review",
          "quantity": 2,
          "rate": 1200
        }
      ]
    }
  }'
```

## Managing Published Templates

You can view and manage your published templates in the [Dashboard](https://htmldocs.com/dashboard), where you can:

* View all published templates
* Get document IDs
* Manage API keys
* Monitor usage
* View generation history


# Static Content
Source: https://docs.htmldocs.com/usage/static-content

Learn how to use static content and custom fonts in your document templates

<Note>
  All static files must be placed in the `/documents/static` directory of your project. This is the required location for serving static assets in your document templates.
</Note>

## Client-Side Usage

Inside HTML/React components, static files are served directly from the `/documents/static` directory. Access them using the absolute path:

```tsx theme={null}
// Access static content on the client-side
<img src="/static/logo.png" />
```

## Server-Side Usage

When reading files server-side (like in document templates), use `process.env.DOCUMENTS_STATIC_PATH` to access files in your static directory:

<Warning>
  Server-side files only work in local development and are not supported yet using the API. <br />
  If you'd like to see this feature, please leave a comment on the <b>#feature-requests</b> channel in Slack.
</Warning>

```tsx theme={null}
import fs from 'node:fs'
import path from 'path'

// Read static content in server-side components
const content = fs.readFileSync(
  path.join(process.env.DOCUMENTS_STATIC_PATH ?? '', 'content.md'),
  'utf-8'
)
```

## Example: Local Fonts

Place your font files anywhere in the `/static` directory and load them using `@font-face`:

```tsx theme={null}
import { Document, Head } from "@htmldocs/react"

function MyDocument() {
  return (
    <Document>
      <Head>
        <style>
          {`
            @font-face {
              font-family: 'CustomFont';
              src: url('/static/fonts/CustomFont.woff2') format('woff2'),
                  url('/static/fonts/CustomFont.woff') format('woff');
              font-weight: normal;
              font-style: normal;
            }
          `}
        </style>
      </Head>
      <div style={{ fontFamily: 'CustomFont' }}>
        Text using custom font
      </div>
    </Document>
  )
}
```

## Example: Loading Markdown Content

Here's a complete example of loading and rendering markdown content in a document:

```tsx theme={null}
import { Document } from "@htmldocs/react"
import MarkdownIt from 'markdown-it'
import fs from 'node:fs'
import path from "path"

const content = fs.readFileSync(
  path.join(process.env.DOCUMENTS_STATIC_PATH ?? '', 'content.md'),
  'utf-8'
)

const md = new MarkdownIt({ html: true })

function MyDocument() {
  const html = md.render(content)
  
  return (
    <Document>
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </Document>
  )
}
```


# Using Tailwind CSS
Source: https://docs.htmldocs.com/usage/tailwind

Learn how to use Tailwind CSS in your htmldocs documents

htmldocs comes with Tailwind CSS v3.4.3 bundled by default. The `@tailwindcss/typography` plugin (v0.5.9) is included by default. The default examples use Tailwind classes.

## Customizing Tailwind

Your project includes a `tailwind.config.js` file that you can customize. The default configuration is optimized for document generation:

```js theme={null}
module.exports = {
  content: ["./documents/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: {
      fontFamily: {
        serif: ['Palatino', 'Palatino Linotype', 'serif'],
      },
      typography: {
        DEFAULT: {
          css: {
            fontSize: '12pt',
            lineHeight: 1.5,
            color: '#000000',
          }
        }
      }
    }
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
};
```

## Usage

Use Tailwind classes in your document templates.

```tsx theme={null}
import { Document, Page } from 'htmldocs';

export default function Resume() {
  return (
    <Document>
      <Page className="bg-white p-8">
        <div className="prose">
          <h1>John Doe</h1>
          <p>Professional software engineer</p>
        </div>
      </Page>
    </Document>
  );
}
```

The `prose` class from `@tailwindcss/typography` is recommended for content-heavy sections.


# Template Variables
Source: https://docs.htmldocs.com/usage/template-variables

Learn how to use template variables and preview props in your document templates

## Overview

Template variables allow you to create dynamic documents by passing data to your templates. This guide shows you how to define and use template variables in your JSX templates.

## Using Template Variables

Create a template component that accepts props for dynamic content:

```tsx theme={null}
import { Document } from "@htmldocs/react";

interface InvoiceProps {
  customerName: string;
  items: {
    name: string;
    quantity: number;
    price: number;
  }[];
}

function Invoice({ customerName, items }: InvoiceProps) {
  return (
    <Document>
      <h1>Invoice for {customerName}</h1>
      <div className="items">
        {items.map((item, index) => (
          <div key={index} className="item">
            <span>{item.name}</span>
            <span>{item.quantity}</span>
            <span>${item.price}</span>
          </div>
        ))}
      </div>
    </Document>
  );
}

export default Invoice;
```

## Preview Props

Define preview data for development and testing using `PreviewProps`:

```tsx theme={null}
Invoice.PreviewProps = {
  customerName: "Acme Corporation",
  items: [
    {
      name: "Premium License",
      quantity: 1,
      price: 999.00
    },
    {
      name: "Support Package",
      quantity: 2,
      price: 299.00
    }
  ]
};
```

## Complex Objects

You can use nested objects and arrays for more complex templates:

```tsx theme={null}
interface CompanyInfo {
  name: string;
  address: {
    street: string;
    city: string;
    state: string;
    zip: string;
  };
  contact: {
    email: string;
    phone: string;
  };
}

interface ReceiptProps {
  orderNumber: string;
  date: string;
  company: CompanyInfo;
  items: {
    name: string;
    quantity: number;
    price: number;
  }[];
}

Receipt.PreviewProps = {
  orderNumber: "ORD-123456",
  date: new Date().toLocaleDateString(),
  company: {
    name: "Acme Corp",
    address: {
      street: "123 Business Ave",
      city: "San Francisco",
      state: "CA",
      zip: "94105"
    },
    contact: {
      email: "info@acme.com",
      phone: "(555) 123-4567"
    }
  },
  items: [
    {
      name: "Product A",
      quantity: 1,
      price: 99.99
    }
  ]
};
```

## Dynamic Values

You can use JavaScript expressions and functions in your preview props:

```tsx theme={null}
Document.PreviewProps = {
  orderNumber: `ORD-${Math.random().toString(36).substr(2, 9).toUpperCase()}`,
  date: new Date().toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  }),
  total: calculateTotal(items)
};
```