Skip to content
Edit on GitHub

Server-side conversion

Convert documents on a server with the npm packages in Node, the native gotipe-convert binary, or GoTipe Cloud export jobs.

@gotipe/export@gotipe/export-wasm@gotipe/sdkMIT

There are three ways to convert documents without a browser. All of them use the same PDF and DOCX renderer as the browser, so a PDF made on the server matches one made on the client.

Path Use it when PDF and DOCX options
@gotipe/export in Node You run Node and want every option All, including resolveImage
gotipe-convert binary You run another language, or a batch job without Node Defaults only
GoTipe Cloud export jobs Documents live in GoTipe Cloud Defaults only

Node

Create a headless editor, load the document JSON and call the export functions. The editor needs no DOM and no WASM engine; @gotipe/export-wasm loads its binary from the package folder.

convert.ts
import { readFile, writeFile } from "node:fs/promises";
import { createHeadlessEditor } from "@gotipe/core/server";
import { exportToDocx, exportToMarkdown, exportToPdf } from "@gotipe/export";

const editor = await createHeadlessEditor({ extensions: [] });
try {
  editor.setContent(JSON.parse(await readFile("document.json", "utf8")));
  await writeFile("document.md", exportToMarkdown(editor));
  await writeFile(
    "document.pdf",
    await exportToPdf(editor, {
      pageSize: "letter",
      footerTemplate: "Internal",
      resolveImage: async (source) => new Uint8Array(await readFile(new URL(source))),
    }),
  );
  await writeFile("document.docx", await exportToDocx(editor, { title: "Report" }));
} finally {
  editor.destroy();
}

The resolveImage above reads file: URLs; return bytes from wherever your images live. renderToHtml, renderToMarkdown and renderToText from @gotipe/core/server convert a document object without creating an editor yourself; parse JSON with JSON.parse first, a string rejects with a TypeError. See Import and export.

gotipe-convert

gotipe-convert is the native Rust converter that GoTipe Cloud runs. It reads one input from stdin and writes the result to stdout. It is not published as a download; build it from the repository with a stable Rust toolchain:

Terminal
cargo build --locked --release -p gotipe-export --features pdf,docx,cli --bin gotipe-convert
# or: pnpm build:converter

The binary is target/release/gotipe-convert, with the export fonts compiled in.

Terminal
gotipe-convert pdf < document.json > document.pdf
gotipe-convert markdown < document.json > document.md
gotipe-convert parse-markdown < README.md > document.json
Command Input Output
html Document JSON HTML fragment, the same as serializeHtml and getHTML()
markdown Document JSON Markdown
plaintext Document JSON Plain text
json Document JSON The same document, normalized and pretty-printed
pdf Document JSON PDF: A4, 12 pt, 72 pt margins, no header or footer
docx Document JSON DOCX without title, author or description
parse-markdown Markdown Document JSON, parsed with the default block schema
project-crdt { "document": baseline, "updates": [envelopes] } Document JSON after applying the collaboration updates

Document JSON is the public format ({ "version": 1, "blocks": [...] }). Input is limited to 64 MiB. On failure the binary prints the error to stderr, writes nothing to stdout and exits with status 1.

For pdf and docx, images must already be embedded as data: URLs: the binary has no resolveImage, and a URL image fails. The html command writes the same HTML as the serializeHtml function of @gotipe/core; markdown writes text, formulas and embeds as @gotipe/markdown does and lays out blocks as it does without a snapshot. Errors name the same causes as the ExportError codes.

Cloud export jobs

GoTipe Cloud converts stored documents in background workers that run gotipe-convert. A job is asynchronous: create it, poll it, then download the file from a signed URL.

export-job.ts
import { GoTipeClient } from "@gotipe/sdk";

const client = new GoTipeClient({ baseUrl: "https://api.example.com", token: process.env.GOTIPE_TOKEN });
const documentId = "6f1c2b8e-0d1a-4f5e-9a63-2a7d1e0b9c44";

let job = await client.createExportJob(documentId, "pdf");
while (job.status === "pending" || job.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  job = await client.getExportJob(documentId, job.id);
}
if (job.status === "failed" || !job.url) throw new Error(job.error ?? "Export failed");
const pdf = new Uint8Array(await (await fetch(job.url)).arrayBuffer());

The same with HTTP:

Terminal
curl -X POST https://api.example.com/v1/exports \
  -H "Authorization: Bearer $GOTIPE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-6f1c2b8e-pdf-1" \
  -d '{"document_id": "6f1c2b8e-0d1a-4f5e-9a63-2a7d1e0b9c44", "format": "pdf"}'

curl https://api.example.com/v1/exports/JOB_ID -H "Authorization: Bearer $GOTIPE_TOKEN"
  • Formats: html, markdown, plaintext, json, pdf, docx. The request has only document_id and format; PDF and DOCX use the defaults in the table above.
  • Access: the export:use scope and at least viewer access to the document. The job exports the current content, including collaboration updates not yet saved as a baseline.
  • Statuses: pending, processing, completed (with url) or failed (with error). A conversion error is recorded, not retried.
  • Downloads: url is a presigned object-storage URL valid for one hour; ask for the job again to get a fresh one. Completed artifacts are deleted 24 hours after completion, failed jobs after 7 days; after that the job returns 404.
  • Quotas: each request counts against the monthly export limit of the account's plan (10 on the free plan). See REST API.

The worker pool is configured on the server: EXPORT_WORKERS (default 4, at most 16), EXPORT_POLL_INTERVAL (default 1s) and EXPORT_MAX_DOCUMENT_SIZE (default 10 MiB). One conversion may run for 2 minutes and one job for 5 minutes; a worker that dies leaves its job to be claimed again after 10 minutes, at most 5 times.

Note:

Cloud jobs cannot set page size, margins, headers, footers or DOCX metadata, and they cannot fetch images: a stored document must embed its images as data: URLs to export to PDF or DOCX. For those options, run @gotipe/export in Node. There is no import endpoint.