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

# Blocks and citations

`extractDocx` lays out the document once and gives you blocks: headings, paragraphs, list items, tables and figures. Each block has its page, its box and its text.

```ts theme={null}
import { extractDocx } from "@reductoai/docx/node";

const { pages, blocks } = await extractDocx("input.docx");
for (const block of blocks) console.log(block.page, block.type, block.content);
```

| Field | Notes |
| - | - |
| `page` | 1-based page number |
| `bbox` | `{ x, y, w, h }` on the page, in hmm (1/100 mm) |
| `bodyIndex` | The paragraph or table in the body, counting from 0. A paragraph that goes onto the next page gives one block for each page, with the same `bodyIndex` |
| `content` | The text as laid. A list block starts with its number (`marker`) |
| `spans` | `content` split where the formatting changes, with `marks` (bold, link, `ins`, `del`, ...) |

The CLI writes the same JSON: `npx docx blocks input.docx -o blocks.json`.

## Find the page of a citation

A citation that points into the text as `(bodyIndex, textOffset)` needs `spanOffsets`. Each span of a body paragraph then has `textOffset` and `textLength`: where its text is in the paragraph.

```ts theme={null}
const { blocks } = await extractDocx("input.docx", { spanOffsets: true });

function locate(bodyIndex: number, textOffset: number) {
  for (const block of blocks) {
    if (block.bodyIndex !== bodyIndex) continue;
    for (const span of block.spans ?? []) {
      const end = span.textOffset! + span.textLength!;
      if (span.textOffset! <= textOffset && textOffset < end) return { page: block.page, bbox: block.bbox };
    }
  }
}
```

The offsets count the paragraph's text in the final view. This is the same text that `Paragraph.text` gives in the [Office.js API](https://docs.reducto.ai/office/docx/js-api/concepts.md), and that an editor `Position` counts:

* Deleted text takes no room. A deleted span has `textLength: 0`.
* A list number is not paragraph text. A `marker` span has no offsets.
* A span's `text` can be longer or shorter than its range. A tab paints as spaces, and `"\n"` between two lines stands for the space where the line wraps.
* The space where a paragraph goes onto the next page is in neither block.

A table cell, a header, a footer and a text box have no offsets yet.

## Same pages in Node and in the browser

`extractDocx`, `docx pdf` and the editor use one layout engine. With the same bytes, the same fonts and the same view, they break the pages at the same places:

| Editor | `extractDocx` and the CLI |
| - | - |
| No Markup or Simple Markup | `trackedChanges: "final"` (default) |
| All Markup, review margin closed | `trackedChanges: "inline"` |
| All Markup, review margin open | `trackedChanges: "balloons"` |

"The same fonts" means the same font files. Give the server the faces that the browser loads: the portable fonts, or one font mirror for both (see [Fonts](https://docs.reducto.ai/office/docx/getting-started/fonts.md)). If a font is missing on one side, its metrics change and the line breaks can move.
