Parse Documents to Markdown with Node.js
Parse documents in Node.js with BulkParse. Convert files to Markdown, inspect structured output, handle partial results, and integrate hosted Bulkgrid parsing.

BulkParse lets a Node.js application convert supported PDFs, Word documents, spreadsheets, and presentations into Markdown through one local interface. Its native Rust engine returns structured document blocks and extraction diagnostics alongside the readable output.
This guide covers installation, file and buffer conversion, partial-result handling, and the separate Bulkgrid API for hosted processing.
Install the Node.js package
Use Node.js 20 or newer:
npm install @bulkgrid/bulkparseKeep npm optional dependencies enabled so the package can select the supported native addon for your platform. Check the Node.js installation guide if your platform needs a source build or the separate WebAssembly package.
Save the examples below as .mjs files, or use .js files in a project configured with "type": "module".
Convert a document to Markdown
Place report.docx in your working directory, or replace the path with your own supported document:
import { writeFile } from 'node:fs/promises';
import { parseFile } from '@bulkgrid/bulkparse';
try {
const result = await parseFile('report.docx');
await writeFile('report.md', result.markdown, {
encoding: 'utf8',
flag: 'wx',
});
console.log('Status:', result.status);
console.log('Diagnostics:', result.diagnostics);
console.log('Rendering diagnostics:', result.render_diagnostics);
} catch (error) {
console.error(error instanceof Error ? error.message : error);
process.exitCode = 1;
}The wx flag prevents accidental replacement of an existing output file. Choose a new filename when rerunning the example.
parseFile returns a promise. Native conversion runs on Node's shared worker pool. The document is processed locally without a Bulkgrid account or a hosted parsing API.
Convert a buffer you already have
Use parse when your application already has the file bytes:
import { parse } from '@bulkgrid/bulkparse';
const result = await parse(
Buffer.from('# Hello\n\nA small document'),
{ filename: 'hello.md' },
);
console.log(result.markdown);
console.log(result.document.blocks);For a PDF, DOCX, or PPTX file, pass its original binary bytes rather than converting them to a UTF-8 string. Include the filename so the input format can be identified appropriately.
When accepting uploads, check file size before holding the full request body in memory. Retaining many buffers while native jobs wait in a queue can consume substantial memory even when individual files are within parser limits.
Keep status and diagnostics with the content
The returned object includes Markdown, document blocks, status, diagnostics, rendering diagnostics, and coverage. Store the original filename with these fields.
A partial result is not necessarily a failed conversion. It can contain useful text with a reported limitation. Native PDF conversion currently reports partial coverage by design, so decide whether the extracted content is suitable for your use case instead of accepting or rejecting it solely on that flag.
Use strict mode when the workflow should reject partial output:
import { parseFile } from '@bulkgrid/bulkparse';
try {
const result = await parseFile('report.docx', { strict: true });
console.log(result.markdown);
} catch (error) {
const code =
error instanceof Error && 'code' in error
? String(error.code)
: 'unknown';
console.error(code, error instanceof Error ? error.message : error);
process.exitCode = 1;
}Parser errors expose categories such as unsupported, malformed, resource_limit, and incomplete. A complete status still does not establish perfect fidelity: check representative headings, tables, and reading order against the original files.
Write Markdown without returning the whole document to JavaScript
When a job only needs an output file, the native writer avoids returning a full JavaScript document model or Markdown buffer:
import { parseFileToMarkdown } from '@bulkgrid/bulkparse';
const summary = await parseFileToMarkdown('report.docx', 'report-direct.md');
console.log(summary.status);
console.log(summary.diagnostics);
console.log(summary.render_diagnostics);The writer refuses to overwrite an existing destination. It still has input and working-memory requirements; this API is not a promise of constant-memory conversion for every format.
For multiple files, start with a sequential loop or a bounded queue. Avoid launching an unbounded Promise.all over a large collection of documents.
Add OCR only where it is needed
Ordinary native parsing does not recognize text inside scanned image pixels. Inspect a PDF first with inspectPdf if you need page-level OCR recommendations, then use the separately configured OCR path.
The OCR binding documentation describes the reusable native OCR parser and its required models and libraries. Installing @bulkgrid/bulkparse does not automatically provision all OCR resources.
For production uploads, combine parser limits with isolated workers, bounded queues, and operating-system resource limits. Treat extracted text as untrusted input if it will be passed to an AI agent.
Use the hosted Bulkgrid API
For managed parsing, install the separate SDK in a Node.js 22-or-newer backend:
npm install @bulkgrid/sdkSet BULKGRID_API_KEY in your server environment. The key needs parse:write and runs:read scopes.
import { readFile } from 'node:fs/promises';
import { BulkgridClient } from '@bulkgrid/sdk';
const apiKey = process.env.BULKGRID_API_KEY;
if (!apiKey) {
throw new Error('Set BULKGRID_API_KEY before running this example.');
}
const client = new BulkgridClient({
baseUrl: 'https://bulkgrid.com',
apiKey,
});
const document = await client.parse({
data: await readFile('./report.pdf'),
filename: 'report.pdf',
});
console.log(document.markdown);
console.log(document.metadata.pageCount);This helper uploads the file, starts a parse run, waits, and fetches the result. Keep the secret key on your backend. Hosted parsing supports automatic OCR for supported scanned PDFs and images; parsing does not automatically index the document.
For longer-lived application jobs, use startParse, store the returned run ID, and resume waiting with waitForParse. Stopping the client wait does not cancel server-side processing.
Try the Parse playground, read the hosted Parse documentation, or follow the format guides for PDF, Word, and PowerPoint.