A utility to render Markdown directly into formatted PDFs using jsPDF.
- Rich markdown support (headings, lists, tables, images, code, blockquotes, links)
- Page geometry derived from margins — no manual content-area arithmetic
- Overridable block renderers, so you can draw any block yourself
- A render result reporting anything that could not be drawn
- Configurable typography, spacing, and block styling
- Header/footer and page-number support
- Safe inline layout and long-token wrapping
- Optional security enforcement for untrusted markdown
jspdf, jspdf-autotable and marked are peer dependencies — the renderer
draws into a jsPDF document you construct, so it uses the copy your project
already has rather than bundling a second one.
npm install jspdf-md-renderer jspdf jspdf-autotable marked| Peer | Supported |
|---|---|
jspdf |
^2 || ^3 || ^4 |
jspdf-autotable |
^3 || ^4 || ^5 |
marked |
^18 |
marked's range is deliberately narrow: its tokenizer output is this library's
layout input, and earlier majors emit different blank-line tokens that move
content vertically on the page.
import { jsPDF } from 'jspdf'
import { MdTextRender } from 'jspdf-md-renderer'
const doc = new jsPDF({ unit: 'mm', format: 'a4' })
const result = await MdTextRender(doc, '# Report\n\nWith **formatted** markdown.', {
page: { margin: { top: 20, right: 20, bottom: 20, left: 20 } },
font: { regular: { name: 'helvetica', style: 'normal' } },
})
if (result.warnings.length) {
console.warn('Some content could not be rendered:', result.warnings)
}
doc.save('report.pdf')The content area is derived from the document's own page size, so it stays correct across formats and orientations. Everything else has a default.
Full configuration, with explicit geometry
import { jsPDF } from 'jspdf'
import { MdTextRender } from 'jspdf-md-renderer'
const markdown = `
# Project Report
This report includes **formatted markdown** content.
- Item 1
- Item 2
`
const doc = new jsPDF({ unit: 'mm', format: 'a4', orientation: 'portrait' })
await MdTextRender(doc, markdown, {
cursor: { x: 10, y: 10 },
page: {
format: 'a4',
unit: 'mm',
orientation: 'portrait',
maxContentWidth: 190,
maxContentHeight: 277,
lineSpace: 1.5,
defaultLineHeightFactor: 1.2,
defaultFontSize: 12,
defaultTitleFontSize: 14,
topmargin: 10,
xpading: 10,
xmargin: 10,
indent: 10,
},
font: {
bold: { name: 'helvetica', style: 'bold' },
regular: { name: 'helvetica', style: 'normal' },
light: { name: 'helvetica', style: 'light' },
},
endCursorYHandler: (y) => {
console.log('Final Y:', y)
},
})
doc.save('report.pdf')MdTextRender resolves to a summary of what it drew — and what it could not.
const { endY, startPage, pageCount, warnings, droppedNodes, violations } =
await MdTextRender(doc, markdown, options)| Field | Meaning |
|---|---|
endY |
Y position of the cursor when rendering finished |
startPage |
Page the render began on |
pageCount |
Pages this render produced |
warnings |
Everything that could not be drawn, with a code and context |
droppedNodes |
How much content that cost |
violations |
Security violations raised during the render |
Failures were previously silent — an image that failed to load, an unsupported
element, or a subtree past the nesting limit produced a PDF that looked
successful and was not. Check warnings if a document must be complete.
// React to warnings as they happen, and keep the console quiet
await MdTextRender(doc, markdown, {
...options,
silent: true,
onWarning: (w) => logger.warn(w.code, w.message, w.context),
})Full guide, including every warning code: Render Result.
Replace or decorate any block renderer. ctx.next() runs the built-in, so an
override can wrap it rather than reimplement it.
await MdTextRender(doc, markdown, {
...options,
components: {
heading: (ctx) => {
if (ctx.element.depth === 1) {
ctx.doc.setFillColor('#1A365D')
ctx.doc.rect(ctx.x, ctx.y, ctx.maxWidth, 10, 'F')
}
ctx.next()
},
code: (ctx) => myHighlighter(ctx),
},
})Overridable: heading, paragraph, list, listItem, blockquote, code,
table, image, hr.
The context carries doc, element, indentLevel, indent, x, y,
maxWidth, store and options, plus next() and
render(element, indentLevel?) for laying out children. An override that throws
is reported as a warning and falls back to the built-in renderer, so a mistake
degrades to default output rather than losing the block.
Full guide, with worked recipes: Component Overrides.
registerFont handles the addFileToVFS/addFont wiring and returns the
font config that selects the result.
import { registerFont } from 'jspdf-md-renderer'
const inter = registerFont(doc, {
family: 'Inter',
variants: { normal: regularBase64, bold: boldBase64, italic: italicBase64 },
})
await MdTextRender(doc, markdown, { ...options, font: inter.font })Styles with no data registered fall back to the normal face, so text stays in the intended family instead of silently reverting to a core font.
Full guide: Custom Fonts.
import { jsPDF } from 'jspdf'
import 'jspdf-autotable'
import { MdTextRender } from 'jspdf-md-renderer'<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jspdf@latest/dist/jspdf.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jspdf-autotable@latest/dist/jspdf.plugin.autotable.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jspdf-md-renderer@latest/dist/index.umd.js"></script>
<script>
const { jsPDF } = window.jspdf;
const { MdTextRender } = window.JspdfMdRenderer;
</script>- Headings (
#to######) - Paragraphs
- Ordered/unordered/task lists
- Links
- Images (with optional
{width,height,align}attributes) - Tables
- Code blocks and inline code
- Blockquotes
- Horizontal rules
- Inline styles (bold/italic)
const options = {
heading: {
bold: true,
h1: 26,
h2: 22,
h3: 18,
bottomSpacing: 3,
},
list: {
bulletChar: '\u2022 ',
indentSize: 8,
itemSpacing: 0,
},
paragraph: {
bottomSpacing: 3,
color: '#111827',
},
blockquote: {
barColor: '#4A90D9',
barWidth: 2,
paddingLeft: 6,
backgroundColor: '#F8FAFC',
},
codeBlock: {
backgroundColor: '#F6F8FA',
borderColor: '#E1E4E8',
borderRadius: 3,
padding: 5,
showLanguageLabel: true,
textColor: '#111827',
},
spacing: {
afterHeading: 2,
afterParagraph: 4,
afterCodeBlock: 4,
afterBlockquote: 3,
afterImage: 2,
afterHR: 2,
betweenListItems: 0,
afterList: 3,
afterTable: 3,
// 'collapse' makes the values above the only source of inter-block gaps.
// Default 'preserve' also adds a line per blank line in the source.
blankLines: 'preserve',
},
// true (default): a single newline is a hard line break.
// false: a single newline is a space, per CommonMark.
breaks: true,
header: {
text: 'My Report',
align: 'center',
color: '#6b7280',
fontSize: 9,
},
footer: {
showPageNumbers: true,
align: 'right',
},
}Behavior notes:
- Heading size fallback:
heading.hN->page.defaultTitleFontSize heading.bolddefaults totrue- List spacing precedence:
spacing.betweenListItems>list.itemSpacing - Table width follows
page.maxContentWidthfor consistent block layout
Two options control behaviour that is scheduled to change. Both default to the behaviour of 4.1.x, so upgrading does not move anything on an existing page. Setting them explicitly makes the next major upgrade a no-op too.
| Option | Current default | Next major | What collapse / false does |
|---|---|---|---|
spacing.blankLines |
'preserve' |
'collapse' |
Blank lines in the source stop adding vertical space, so the spacing.* options alone decide the gap between blocks |
breaks |
true |
false |
A single newline inside a paragraph renders as a space rather than a hard line break, per CommonMark |
// Opt in to the corrected behaviour today
const options = {
// ...other options
spacing: { blankLines: 'collapse' },
breaks: false,
}- Inline emphasis inside table cells is flattened to plain text.
jspdf-autotabledraws cell content itself and has no notion of mixed inline runs. - Inline HTML tags (
<strong>,<em>) render their text without applying the style.<br>is supported. cursor.xapplies to the first line only; each block then starts at the left edge of the content column.- Long runs of CJK text wrap character by character, without kinsoku rules.
Security is disabled by default for backward compatibility.
Always-on baseline limits (cannot be disabled): Regardless of the
security.enabledsetting,MdTextParser(and by extensionMdTextRender) enforces two unconditional hard limits to prevent the underlying Markdown parser from crashing the host process:
- Absolute length ceiling: Inputs larger than 2 MB (2,000,000 characters) are rejected with a
MarkdownParsingLimitErrorbefore parsing begins.- Structural nesting ceiling: Blockquote or list structures nested more than 300 levels deep are rejected with a
MarkdownParsingLimitError.These limits exist because deeply nested or oversized Markdown can cause stack exhaustion or memory exhaustion in the parser regardless of any security settings.
MarkdownParsingLimitErroris exported fromjspdf-md-rendererand can be caught and handled by callers.
const options = {
// ...other options
security: {
enabled: true,
violationMode: 'skip', // 'skip' | 'throw' | 'placeholder'
placeholderText: '[blocked]',
placeholderImageText: '[blocked image]',
// Link controls
allowedLinkProtocols: ['https:', 'http:', 'mailto:', 'tel:'],
disablePdfLinks: false,
// Image controls
allowRemoteImages: true,
allowedImageProtocols: ['https:', 'http:'],
allowedImageDomains: ['cdn.example.com'],
allowDataUrls: true,
allowSvgImages: true,
// SSRF controls
blockLocalhost: true,
blockPrivateIPs: true,
blockLinkLocalIPs: true,
blockMetadataIPs: true,
// Limits
maxMarkdownLength: 500000,
maxImageCount: 200,
maxImageSizeBytes: 10 * 1024 * 1024,
maxNestedDepth: 20, // counts structural nesting (lists, quotes, tables)
renderTimeoutMs: 30000,
imageFetchTimeoutMs: 10000, // per remote image request; 0 disables
// Hooks
validateUrl: async (url, type) => true,
onSecurityViolation: (violation) => console.warn(violation),
},
}- URL classes:
- explicit scheme (
https://...) -> full protocol/domain/IP checks - protocol-relative (
//host/path) -> treated as external absolute URL - relative path (
/a,./a,?q=1,#id) -> allowed by default unless custom validator rejects
- explicit scheme (
allowedImageDomainssemantics:undefined-> allow all domains[]-> deny all domains
maxImageSizeBytesuses decoded bytes for data URLs; a remote image is abandoned as soon as it passes the limitimageFetchTimeoutMscovers reading the body as well as the headersblockLocalhostcovers all of127.0.0.0/8,0.0.0.0/8,::1and::, and IPv6 addresses that embed an IPv4 address are held to the IPv4 rules- Image hosts are resolved and checked; links are only checked against an address written into the URL itself
SecurityViolationErroris exported for throw-mode handling- Redirects on remote image fetches are followed manually, and every hop is revalidated against the same policy (bounded to 5 hops)
maxNestedDepthcounts structural containers (lists, list items, blockquotes, tables), not every AST level
Browser caveat:
- IP-level SSRF checks are best-effort in browser runtime due to DNS API limitations.
- For strict SSRF policy, fetch remote images through a trusted server-side proxy.
DNS caveat:
- An image host is resolved for the checks and again by
fetchto connect, so a DNS server that answers differently the second time can redirect the request. UseallowedImageDomainsor a server-side proxy where that matters.
Use jsPDF 4.2.1 or later when rendering markdown you do not control: earlier versions have published denial-of-service advisories in the image decoders that markdown images reach.
MdTextRender— renders markdown, resolves to aRenderResultMdTextParserregisterFontvalidateOptionsSecurityViolationErrorMarkdownParsingLimitError- Types:
RenderOption,RenderResult,RenderWarning,PageMargin,ComponentContext,ComponentOverrides,RegisteredFont,RenderSecurityOptions,SecurityViolation,ViolationMode, and others
All types are exported from the package root:
import type { RenderOption } from 'jspdf-md-renderer'- Docs site: https://jeelgajera.github.io/jspdf-md-renderer/
- Page geometry guide: https://jeelgajera.github.io/jspdf-md-renderer/guide/page-geometry
- Render result guide: https://jeelgajera.github.io/jspdf-md-renderer/guide/render-result
- Component overrides guide: https://jeelgajera.github.io/jspdf-md-renderer/guide/component-overrides
- Custom fonts guide: https://jeelgajera.github.io/jspdf-md-renderer/examples/custom-fonts
- Resume example: https://jeelgajera.github.io/jspdf-md-renderer/examples/resume
- Invoice example: https://jeelgajera.github.io/jspdf-md-renderer/examples/invoice
- Technical report example: https://jeelgajera.github.io/jspdf-md-renderer/examples/report
This repository uses Vitest for regression testing and coverage reporting.
npm test # Run tests with coverage
npm run test:watch
npm run test:uiCoverage policy:
- Security/rendering behavior changes should include focused regression tests.
Contributions are welcome. Please read CONTRIBUTING.md.
MIT. See LICENSE.