# Doc

> Create, import, read, edit, paginate, chart, inspect, export, and visually verify remote Workspace Doc Units.

- Skill: `dream-num/doc` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add dream-num/doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dream-num/doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dream-num (https://skillmd.com/u/dream-num)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/dream-num/doc

---


# Workspace Doc units

Operations that read or edit an existing Doc target one remote draft explicitly by Worktree and Unit ID. Markdown creation allocates the new Unit as described below. `execute` provides `univerAPI`, `api` (an alias of `univerAPI`), and `doc` (the `FDocument` bound to the selected Unit). Do not redeclare them. A Doc unit does not provide `workbook` or `presentation`; if one is undefined, verify the selected unit type.

Use `doc.getParagraphs()` and `doc.getParagraph(paragraphId)` to select paragraphs. Use
`api find` with API-name keywords or identifier fragments to discover API symbols, then use
`api show` with exact symbols for exact signatures, enum values, documentation, and
examples.

## Workspace target

Create an empty Doc Unit or import an existing document into the selected Worktree:

Run `unit create` with type `doc`, a name, and the destination Space in the selected Worktree, or run `import` with the document source and type `doc`. Follow the `core` Skill for source handling.

Both commands return server-owned `unitId`, `resourceId`, and `nodeId`. Use the returned `unitId`
for every content command; never reuse an imported document's internal id as the Workspace address.
For original-file preservation without an editable Doc Unit, read the [Blob Skill](../blob/SKILL.md).
Blob Resources have no `unitId` and cannot use this Skill's commands.

## Modern Docs through Markdown

For new Modern Docs, write Markdown and compile it once into editable native content. Read
the [Markdown authoring](references/markdown.md) reference of the `doc` Skill
for valid directives, assets, and full creation/update examples. The compiler is shared through the
AI SDK; this Skill owns the Workspace target and review workflow.

- Run `compile-markdown` with the Markdown source, apply enabled, and the destination Space in the task Worktree. Follow the `core` Skill for source and map handling. It creates the draft Doc; do not create an empty
  placeholder first. Use the returned server-owned `unit.unitId` for later commands.
- Preserve SDK default typography, line/paragraph spacing, and callout colors. Use plain
  `:::callout{#notice}`. Modern columns use native ColumnGroup with 2–5 columns; do not use
  Traditional section breaks or replace requested columns with layout tables.
- Assign explicit top-level block IDs and save the **execution** source map. Compile-only maps do
  not contain native identities and cannot address later edits.
- Before each partial update, export the selected current native blocks with `export-markdown`,
  including their resources, refreshed source map, and authoritative revision. Edit that fragment,
  retain its root IDs, and apply with the Doc Unit, refreshed source map, and selected block IDs together.
  Save the new execution map after success. Native content is authoritative; old Markdown does not
  include subsequent editor changes.
- On conflicts, read/export again and replan. Unsupported content or diagnostic errors stop the
  conversion; report the exact limitation instead of flattening content or overwriting the Doc.
- Inspect and screenshot the result before the normal Worktree review handoff. Generation should
  finish after compilation and verification; avoid cosmetic Facade patches after conversion.

## Model essentials

- A newly added Doc starts with one empty paragraph. Usually append content with `doc.appendParagraph(text)` or update the first paragraph with `setText`.
- Paragraph editing methods live directly on `doc`, not on `doc.getBody()`: `appendParagraph`, `insertParagraph`, `insertText`, and `deleteRange`.
- `doc.getParagraphs()` returns all paragraphs. `doc.getParagraph(id)` selects by stable paragraph id; indexes drift as the document changes, so use ids across multi-step edits.
- An `FDocumentParagraph` supports `getText`, `setText`, `appendText`, `setStyle`, and `getRange`.
- List and task helpers include `isListItem`, `isTask`, and `setTaskChecked`.
- Native charts use the direct `doc.newChart()`, `doc.insertChart()`, `doc.getCharts()`, and
  `doc.getChart()` methods.
- Colors must use `#RRGGBB`.

## The dataStream model

The body is one `dataStream` string. Paragraphs are separated by `\r`, and the document ends with `\r\n`. `body.paragraphs[i].startIndex` is the index of the `\r` that terminates paragraph `i`; the paragraph text occupies the range from the previous end to that index. An empty Doc therefore has `dataStream === "\r\n"` and one empty paragraph. Offsets passed to `insertText`, `deleteRange`, and text-style operations address this stream.

## Paragraph and text styles

Pass paragraph properties and `textStyle` together to `paragraph.setStyle` when the entire current paragraph should share one style. Important paragraph fields include `horizontalAlign`, `namedStyleType`, `headingId`, `indentStart`, and `indentFirstLine`. Always query `api show` for `IParagraphStyle` instead of guessing enum values.

```js
const paragraph = doc.appendParagraph("Section Title");
const changed = paragraph.setStyle({
  namedStyleType: api.Enum.NamedStyleType?.HEADING_1 ?? "HEADING_1",
  textStyle: { bl: api.Enum.BooleanNumber.TRUE },
});
if (!changed) throw new Error("paragraph style update failed");
```

`textStyle` covers the paragraph's entire current text, excluding the trailing paragraph break. Paragraph and text-style changes are applied through one document command. `ITextStyle` uses the same compact fields as Sheet text styles, including `bl` for bold, `it` for italic, `cl: { rgb }` for text color, and `bg: { rgb }` for background color.

## Native images

Native Doc images work in both Modern and Traditional Docs. In the Node authoring runtime, always
provide both `width` and `height`; omitting either still requires browser intrinsic-size loading.
Set `wrappingStyle` explicitly: use `INLINE` for ordinary content,
`WRAP_SQUARE` or `WRAP_TOP_AND_BOTTOM` when surrounding text should reflow, and reserve
`BEHIND_TEXT` / `IN_FRONT_OF_TEXT` for intentional overlays because they can cover text. Use an
explicit body range rather than the current selection, and await insertion:

```js
const anchor = doc.getParagraphs()[0];
if (!anchor) throw new Error("image anchor missing");
const range = anchor.getRange();
const image = await doc.insertImage({
  source: imageDataUri,
  imageSourceType: api.Enum.ImageSourceType.BASE64,
  width: 320,
  height: 180,
  wrappingStyle: api.Enum.DocsImageWrappingStyle.INLINE,
  textRange: {
    startOffset: range.startOffset,
    endOffset: range.startOffset,
    collapsed: true,
    segmentId: anchor.getSegmentId(),
  },
});
if (!image) throw new Error("image insert failed");
```

Read it back later with `doc.getImages()[0].getImageData()` and `getSourceType()`.

Prefer a valid Base64 data URI for local, reproducible authoring. Never persist a temporary signed
download URL as an image source; signed URLs are for artifact handoff only and expire. Do not install
a global `Image` or Canvas polyfill, write drawing storage directly, or replace a required image with
a table-backed filename placeholder. Verify `doc.getImages()` readback and the final screenshot;
also verify DOCX export when it is part of the request.

## Document flavor and physical pagination

Check `doc.getDocumentFlavor()` or the positive `doc.isTraditional()` guard before page-specific
work. A new empty Doc created by `createDocument` is Modern by default. Modern Docs are pageless:
traditional section and page-setup APIs reject them, so do not simulate physical pages with large
spacers. When the output requires Word-compatible pages, start from a Traditional Doc such as a DOCX
import or the Traditional output of `compile-typst`.

In a Traditional Doc, create a hard page boundary before a top-level paragraph with one atomic
section command:

```js
if (!doc.isTraditional()) throw new Error("Traditional Doc required for physical pagination");
const chapter = doc.findParagraphByText("Chapter 2");
if (!chapter) throw new Error("chapter heading missing");
const section = doc.insertSectionBreak(chapter.getInfo().startOffset, {
  nextSectionType: api.Enum.SectionType.NEXT_PAGE,
});
if (!section) throw new Error("section break insert failed");
```

Use `section.getEffectivePageSetup()` for resolved page geometry and screenshot the result for actual
page count and placement. `keepNext`, `keepLines`, and `widowControl` improve natural pagination but
are not hard page breaks.

## Typst, tables, pagination, and reference fidelity

For a formal document authored from Typst, use a lightweight Typst Source Bundle instead of copying generated Facade JavaScript. The bundle contains a manifest with schema version 1, a compiler target Unit ID, ordered page sources, an optional prelude, and optional assets. Follow the `core` Skill for bundle structure and source handling.

It may also declare `title` and `prelude`. Compile once for review, then apply the same result:

Run `compile-typst` on the Typst bundle in build-only mode for a generated program, diagnostics, and preview PNGs. Then apply the same bundle to the destination Space in the Worktree. Follow the `core` Skill for bundle and output handling.

`targetUnitId` in the manifest is the compiler target used to validate the generated action batch; it
is not the Workspace content address. On apply, the server allocates and returns the actual
`unitId`, `resourceId`, and `nodeId`, while the result reports the manifest value separately as
`compiledTargetUnitId`. Use only the returned server `unitId` in later `execute`, `inspect`,
`screenshot`, `export`, and `browse` operations. Workspace apply requires apply enabled, a Worktree, and a destination Space together, with optional parent Node and idempotency key. Build-only mode opens no mutation session. Follow the `core` Skill for required outputs; unrequested outputs are not generated. Errors block apply; warnings allow it but require review of both the Typst PNG and the
final Workspace screenshot. The compiler loads only the official bundled
`@univerjs-pro/doc-typst-native-binding`; do not install or fall back to a system `typst`.

Put shared definitions in the manifest prelude rather than using `#import` or `#include`. Use PNG, JPEG, GIF, WebP, or SVG assets with explicit dimensions, for example 240pt by 120pt. Follow the `core` Skill for bundle image references. The compiler embeds the asset and inserts a
native Doc image with deterministic dimensions; it does not emit a table placeholder. Review any
warning about mismatched `cover` / `contain` geometry or unavailable alternative-text authoring
against the direct Typst PNG. A fixed left/right layout must pass every cell as an argument of one
grid:

```typst
#grid(
  columns: (1fr, 1fr),
  gutter: 12pt,
  [Left region],
  [Right region],
)
```

Use diagnostics source paths and spans to correct syntax. An evaluator error is not evidence that the whole grid, table, image, or spacing capability is unsupported. Make one minimal page pass first, then expand the manifest page by page.

For reference reconstruction, keep three evidence layers: the reference, Typst-rendered PNG when Typst source exists, and the final Workspace screenshot. Resolve reference-to-Typst source differences before diagnosing Typst-to-Univer Facade differences. Prioritize editable text, tables, physical pagination, headers and footers, and fonts. Typst lowering does not create native chart objects; add requested data-driven charts afterward through the direct `FDocument` chart methods ("Native charts"). Brand marks and illustrations are not the default priority.

Layout-sensitive pages should explicitly declare font family or named face, font size, `leading`, paragraph spacing, heading size and spacing, and `hyphenate`. Build measures Typst's resolved line advance and maps it to exact Doc paragraph spacing; do not add document-specific leading compensation. Preserve fractional sizes such as `9.2pt` and `10.4pt`. Use only normal and bold for generic Word-compatible weights. Select a resolvable named face for Semibold or Black instead of assuming a continuous `100..900` Doc weight API. Literal underscores such as `read_file` require raw text or correct escaping and must be confirmed in the Typst PNG.

For a fixed two-column region or one-row grid in a paginated Doc, prefer a **borderless layout table** instead of switching to a pageless Column Group. Real data tables should define column widths, header rows, merges, and border semantics explicitly. Do not divide uneven content into equal columns by default.

Typst source must express border topology and fill regions explicitly. Use a static table `fill` for uniform backgrounds and `table.cell(fill: ...)[...]` for local row, column, or cell highlights. For booktabs or local rules, use `stroke: none` plus explicit `table.hline(...)` or `table.vline(...)`; use the default full grid only when the reference actually has one. Use `table.header(...)` and static colspan or rowspan for grouped headers, and `table.cell(stroke: ...)[...]` for cell-local borders. Do not rely on Typst defaults or opaque dynamic fill/stroke functions when static semantics can be mapped deterministically.

Pass this code to `execute` for the Unit in its Worktree:

```js
const table = doc.insertTableFromData(
  [["Group", ""], ["Name", "Description"], ["A", "Long description"]],
  { width: 602, columnWidths: [200.667, 401.333], headerRowCount: 2 }
);
if (!table) throw new Error("table insert failed");
table.setColumnWidth(0, 200.667);
table.setColumnWidth(1, 401.333);
table.mergeCells({ startRow: 0, endRow: 0, startColumn: 0, endColumn: 1 });
table.setHeaderRowCount(2);
table.setTableBorder({ preset: api.Enum.DocsTableBorderPreset.None, color: "#FFFFFF", width: 0 });
table.setBorder(
  { startRow: 1, endRow: 1, startColumn: 0, endColumn: 1 },
  { preset: api.Enum.DocsTableBorderPreset.Bottom, color: "#000000", width: 1 }
);
```

For cell-local paragraph styles, constrain the target with `table.getCellContentRange(row, column)` and confirm the target text. Do not search duplicate text globally and broadcast a mutation. Merge base font family, size, line spacing, and paragraph spacing with bold, italic, underline, and color overlays; a later `setStyle` can otherwise replace the base font. Do not use DocModel internals, `tableSource`, body markers, or invisible control characters to force layout.

The public Facade has no verified dynamic current-page field or table-cell padding and
vertical-alignment mutation. Record these as gaps; do not fake them with horizontal rules, page-sized
spacers, or repeated fixed page numbers. Literal headers and footers are supported.

## Native charts

Doc chart support is registered in the runtime. Create detached chart information directly from
`doc`, then insert it to obtain a live `FDocumentChart`. Query exact signatures before authoring:

Use `api show` for `FDocument.newChart`, `FDocument.insertChart`, `FDocument.getCharts`, `FDocument.getChart`, `FDocumentChartBuilderOf`, and `DocsChartInsertAnchorKind`.

Build the chart detached, configure its data, mapping, anchor, and size, then await insertion:

```js
const info = doc
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setTitle({ text: "Quarterly Revenue" })
  .setSource([
    ["Quarter", "Revenue"],
    ["Q1", 12],
    ["Q2", 18],
    ["Q3", 15],
  ])
  .setCategoryField(0)
  .setValueFields([1])
  .setPosition({ kind: univerAPI.Enum.DocsChartInsertAnchorKind.BodyOffset, offset: 0 })
  .setInline()
  .setSize(480, 320)
  .build();
const inserted = await doc.insertChart(info);
return { chartId: inserted.getId(), drawingId: inserted.getDrawingId(), info: inserted.getInfo() };
```

`doc.getCharts()` and `doc.getChart(id)` return live charts. Await
`chart.setDataSource(values)` for data changes. For a complete replacement, use
`chart.toBuilder().build()` and `await chart.update(info)`. Remove it with `await chart.remove()`
and check the boolean. Await every asynchronous mutation before `execute` returns.

Anchor kinds include selection, body offset, paragraph, and text range. Verify each operation in a
fresh read-only `execute` with
`doc.getCharts().map((item) => ({ id: item.getId(), drawingId: item.getDrawingId(), type: item.getType(), info: item.getInfo() }))`.
For an update,
confirm the chart ID, count, type, title, anchor, layout, and data. For a removal, confirm the chart is
absent. Then screenshot the affected page and test DOCX export when export fidelity is part of the
task.

## Inspect and verify

- `inspect` with target `document` for the Doc Unit in its Worktree reports title, mode, paragraph and character counts, structural features, and paragraph previews.
- `inspect` with target `paragraph` and one or more paragraph indexes or IDs for the Doc Unit in its Worktree reports full text, paragraph style, list membership, and text-run summaries. Indexes are zero-based.
- For fine-grained reads, use read-only execute: `return doc.getParagraphs().map((p) => p.getText());`.

Logical inspection cannot reveal actual wrapping or pagination. For layout-sensitive work, render PNGs with `screenshot` before following the core Skill's "Finish the task" steps. Imported DOCX paragraphs may lack persistent paragraph ids, in which case inspect falls back to a zero-based index; paragraphs created or edited in the same session have stable ids.

For visual and exchange verification, use the same explicit remote address:

Run `screenshot` and `export` with format `docx` for the same Doc Unit in its Worktree. Follow the `core` Skill for output handling.

