> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nemu.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The declarative Doc API: pages of content blocks that compile to the low level Document

A `Doc` is a list of pages, and each page is a list of content blocks. You describe what the
document contains, set role styles once, and call `build`. Pagination, headers, footers, and
font loading are handled for you.

Under the hood `Doc` compiles its block tree down to the low level `Document` and `Page`
element API and then renders. It adds no separate engine, so anything `Doc` produces could
also be built by hand with `Document`.

## Constructor

```ts theme={null}
new Doc(options?: DocOptions)
```

`DocOptions` extends `DocumentOptions` and adds a few document level fields:

```ts theme={null}
interface DocOptions extends DocumentOptions {
  padding?: number | MarginValues;
  header?: HeaderFooter;
  footer?: HeaderFooter;
  auto_paginate?: boolean;
}
```

<ParamField path="padding" type="number | MarginValues">
  Inner inset added on top of `margin`. Margin and padding are summed into the page content
  inset.
</ParamField>

<ParamField path="header" type="HeaderFooter">
  A document wide header. See [Headers and footers](/packages/pdf/doc/headers).
</ParamField>

<ParamField path="footer" type="HeaderFooter">
  A document wide footer. See [Headers and footers](/packages/pdf/doc/headers).
</ParamField>

<ParamField path="auto_paginate" type="boolean" default="true">
  Flow content across pages automatically. Set it to `false` to keep each page literal.
</ParamField>

<Note>
  Markdown parsing on plain string text is on by default in `Doc`. Plain strings honor
  `**bold**`, `*italic*`, `~~strike~~`, and `$inline math$`. Structured inline nodes always
  format regardless of that flag. See [Inline content](/packages/pdf/doc/inline).
</Note>

## Methods

```ts theme={null}
doc.set_style(styles: RoleStyles): this
doc.set_header(header: HeaderFooter): this
doc.set_footer(footer: HeaderFooter): this
doc.load_font(name: string, path: string, variable?: boolean): this
doc.load_image(name: string, path: string): this
doc.page(config?: PageConfig): DocPage
await doc.build(file_path: string): Promise<void>

page.content(...items: Array<Block | Block[]>): this
```

<ParamField path="set_style(styles)" type="RoleStyles">
  Assigns a default style per role. Block level `style` merges on top. See
  [Styling](/packages/pdf/doc/styling).
</ParamField>

<ParamField path="set_header(header)" type="HeaderFooter">
  Sets the document wide header.
</ParamField>

<ParamField path="set_footer(footer)" type="HeaderFooter">
  Sets the document wide footer.
</ParamField>

<ParamField path="load_font(name, path, variable?)" type="string, string, boolean">
  Registers a custom font by name for use in `font_family`. Pass `variable: true` to enable
  weight instancing. See [Fonts and weights](/packages/pdf/doc/fonts).
</ParamField>

<ParamField path="load_image(name, path)" type="string, string">
  Registers an image by name so a block can reference it by name instead of a path.
</ParamField>

<ParamField path="page(config?)" type="PageConfig">
  Adds a page and returns a `DocPage`. The optional config sets a per page header and footer.

  ```ts theme={null}
  interface PageConfig {
    header?: HeaderFooter;
    footer?: HeaderFooter;
  }
  ```
</ParamField>

<ParamField path="build(file_path)" type="string">
  Renders the document and writes it to disk. Always awaited.
</ParamField>

### DocPage.content

```ts theme={null}
page.content(...items: Array<Block | Block[]>): this
```

`content` flattens arrays, so a component that returns `Block[]` can be spread inline. This
makes reusable blocks composable without wrapping them in a group.

## A complete example

```ts theme={null}
import { Doc } from "@nemu-ai/pdf";

const doc = new Doc({ page_size: "A4", margin: 54, padding: 10 });

doc.set_style({
  heading: { font_family: "inter", color: "#111827" },
  paragraph: { font_family: "source-serif-4", font_size: 11.5, line_height: 1.6 },
  link: { color: "#2563eb" },
});

doc.page().content(
  { type: "heading", text: "Quarterly Report", level: 1 },
  { type: "paragraph", text: "Revenue grew across every region this quarter." },
  { type: "note", variant: "info", title: "Note", text: "Figures are unaudited." },
);

await doc.build("report.pdf");
```

## Next

<CardGroup cols={2}>
  <Card title="Blocks" icon="cube" href="/packages/pdf/doc/blocks">
    Every block type, from headings and paragraphs to tables, charts, and groups.
  </Card>

  <Card title="Styling" icon="palette" href="/packages/pdf/doc/styling">
    Role styles, block level overrides, and the style properties that matter for documents.
  </Card>

  <Card title="Headers and footers" icon="window-maximize" href="/packages/pdf/doc/headers-footers">
    Static, dynamic, and raw draw headers and footers, document wide or per page.
  </Card>

  <Card title="Inline content" icon="text-width" href="/packages/pdf/doc/inline">
    Strong, em, strike, links, inline code, and inline formulas, with markdown shortcuts.
  </Card>
</CardGroup>