Built-in components
There are fourteen built-in components, plus InlineCode, which only lives inside runs. To see the full props definitions:
document-render catalog # list componentsdocument-render catalog --json # JSON Schema of every component's props| Component | Purpose | Container | Parts |
|---|---|---|---|
| Document | Root container; also for grouping | yes | — |
| Heading | Heading, levels 1–6 | no | — |
| Text | A paragraph | no | — |
| Code | A code block | no | — |
| List | List, can nest | no | level1…level9 marker item |
| Table | Table | no | see Tables |
| Image | Image | no | caption |
| PageBreak | Page break | no | — |
| Divider | Horizontal line (next release) | no | — |
| Quote | Quotation (next release) | no | — |
| Callout | Callout box (next release) | no | — |
| TableOfContents | Table of contents (next release) | no | title entry |
| Section | Section | yes | — |
| Slide | One slide | yes | title body |
Each component’s built-in default style is listed below. To change it, see Styles.
Document
Section titled “Document”The root container; lays out its children in order. No props.
"doc": { "type": "Document", "children": ["title", "intro"] }Document can be nested: put a few paragraphs in one, style it, and text fields flow down to each child. Custom component templates often use it as their root.
Heading
Section titled “Heading”| Prop | Type | Required | Meaning |
|---|---|---|---|
level |
integer 1–6 | yes | Heading level |
text |
string or runs | yes | Heading text |
"title": { "type": "Heading", "props": { "level": 1, "text": "Quarterly report" } }- Defaults: bold,
keepWithNext, 12pt before, 6pt after, line height 1.25. Sizes: level 1 20pt (18pt before), 2 16pt, 3 14pt, 4 12pt, 5 and 6 11pt. - Style a single level with the component keys
Heading.1…Heading.6. - In docx, headings also get Word’s “Heading 1–6” styles, so the navigation pane and TOC work.
| Prop | Type | Required | Meaning |
|---|---|---|---|
text |
string or runs | yes | Paragraph text; runs are explained in Document structure |
"intro": { "type": "Text", "props": { "text": ["Run ", { "type": "InlineCode", "text": "document-render check" }, " to validate."] } }- Default: 6pt after.
- An empty string
""still takes up one line, in all three formats.
InlineCode
Section titled “InlineCode”Inline code. Not an element on its own; it only appears in runs:
{ "type": "InlineCode", "text": "document-render render doc.json -o out.pdf" }Default: monospace (Menlo, Consolas, DejaVu Sans Mono) on #F0F1F3. Change it with the InlineCode component style.
A code block; spaces and line breaks are kept.
| Prop | Type | Required | Meaning |
|---|---|---|---|
code |
string | yes | The code; use \n for new lines |
language |
string | no | Language name. Only a label: html writes class="language-xxx"; no syntax highlighting |
lineNumbers |
boolean | no | Show line numbers, default false |
"sample": { "type": "Code", "props": { "language": "json", "code": "{\n \"type\": \"Text\"\n}", "lineNumbers": true }}Defaults: monospace, 9pt, line height 1.4, background #F6F8FA, padding 8pt, 8pt after, keepTogether.
docx paragraphs only use padding when they have a border, so code blocks get no padding in docx and you’ll see one warning. For padding, add a border in the background color.
| Prop | Type | Required | Meaning |
|---|---|---|---|
items |
array | yes | List items |
ordered |
boolean | no | Numbered, default false |
Each item can be:
- a string:
"Write JSON" - a runs array:
[{ "text": "document-render render", "type": "InlineCode" }, " to get files"] - an object with a sub-list:
{ "text": …, "items": [...], "ordered": true }. Withoutorderedit follows the parent level.
"list": { "type": "List", "props": { "ordered": true, "items": [ "Prepare data", { "text": "Pick a style set", "items": ["report", "slides"] }, "Render" ] }, "style": { "listStyleType": "upper-roman", "listMarkerFormat": "%1." }, "parts": { "level2": { "listStyleType": "decimal", "listMarkerFormat": "%1.%2" } }}- Defaults: 6pt after,
listIndent2em,listHanging2em. - Without a type, levels rotate: ordered
decimal→lower-alpha→lower-roman; unordereddisc→circle→square. - Parts:
level1…level9for a level,markerfor the number or bullet,itemfor each item’s text. - Numbering and indent fields: List style.
| Prop | Type | Required | Meaning |
|---|---|---|---|
columns |
array of cells | no | Header row; if present it is the first row |
rows |
2-D array of cells | yes | Data rows |
widths |
array | no | Column widths: ratio, fixed length or "auto" |
rowHeights |
array | no | Row heights |
look |
object | no | Which parts are active |
"price": { "type": "Table", "props": { "columns": ["Item", "Price"], "widths": [3, 1], "rows": [["Apple", "3.50"], ["Pear", "4.00"]] }, "parts": { "header": { "background": "#1A73E8", "color": "#FFFFFF" } }}Defaults: 0.5pt solid #999999 borders, cellPadding 4pt, repeatHeader on, 8pt after; header bold on #F3F3F3.
Merged cells, per-cell styles, row heights and parts are in Tables.
| Prop | Type | Required | Meaning |
|---|---|---|---|
src |
string | yes | Local path or URL. Relative paths resolve from the document’s directory |
alt |
string | no | Alt text, shown when the image can’t be embedded |
width |
number (pt) | no | Width |
height |
number (pt) | no | Height. Give one and the other keeps the aspect ratio |
caption |
string | no | Caption shown below the image |
"logo": { "type": "Image", "props": { "src": "logo.png", "alt": "document-render", "width": 90, "caption": "Figure 1. Logo" } }Defaults: 6pt after; caption 9pt #666666 (part caption). Format support and positioning: Images.
PageBreak
Section titled “PageBreak”Starts a new page. No props.
"break": { "type": "PageBreak" }Plain html shows no page breaks; they appear when printing or with --paged.
Divider
Section titled “Divider”A horizontal line. No props; its look comes entirely from style, and the line is the paragraph’s bottom border.
"line": { "type": "Divider" },"dashed": { "type": "Divider", "style": { "borderBottom": "1pt dashed #999999" } }Default style: bottom border 0.5pt solid #D0D7DE, exact line height 1pt, 6pt before, 12pt after.
A quotation: a paragraph with a bar on the left.
| prop | type | required | description |
|---|---|---|---|
text |
string or runs | yes | The quoted text, written like Text |
"quote": { "type": "Quote", "props": { "text": [{ "text": "Word and PDF finally match, " }, { "text": "saving us a whole day.", "bold": true }] }}Default style: left border 3pt solid #D0D7DE, 10pt left padding, color #57606A, 8pt after.
In docx the padding and line width are added to the left indent, so the bar and text sit in the same place in all three formats.
Callout
Section titled “Callout”A callout: a paragraph with a background and a thin border, optionally led by an icon.
| prop | type | required | description |
|---|---|---|---|
text |
string or runs | yes | The callout text |
icon |
string | no | Character placed first, usually an emoji such as "💡". A space follows it automatically |
"warn": { "type": "Callout", "props": { "icon": "⚠️", "text": "Month 3 figures are not audited yet and may change." }, "style": { "background": "#FFF8E1", "border": "0.5pt solid #F0C36D" }}Default style: background #F6F8FA, border 0.5pt solid #E1E4E8, 8pt padding, 8pt after.
- The icon uses the same text style as the body. How an emoji looks depends on the font, so it may differ between formats.
- For rounded corners add
radius; docx has no rounded corners and warns once.
TableOfContents
Section titled “TableOfContents”A table of contents listing the document’s headings in order.
| prop | type | required | description |
|---|---|---|---|
title |
string | no | Heading shown above the list; omitted if not set |
levels |
1 to 6 | no | Deepest heading level to include, default 3 |
"toc": { "type": "TableOfContents", "props": { "title": "Contents", "levels": 2 } }- Parts:
titlestyles the heading (default 14pt bold, 6pt after);entrystyles each item (default 2pt after). - Each deeper level is indented by
listIndent(set onentry, default1.5em). - Only Heading elements are listed, not Slide titles.
Page numbers come from different places in each format:
| Page numbers | |
|---|---|
| Computed after layout; entries are clickable | |
| docx | A Word TOC field. The file holds the entry text without page numbers; update the field in Word (right-click the TOC → Update Field) to get them |
| html | Plain links when opened directly; with --paged, Paged.js fills in page numbers |
When Word updates the field it re-lays the entries with the “TOC 1” to “TOC 6” styles. document-render defines those styles from the entry style of the first TOC in the document, so it looks the same before and after the update.
Section
Section titled “Section”A section. Each one starts on a new page and can set its own paper size, orientation, margins, columns, headers and footers, and page-number start. Sections can only sit directly under the root.
"body": { "type": "Section", "props": { "landscape": true, "pageNumberStart": 1, "footer": "ftr" }, "children": ["h1", "p1"]}Props and usage: Sections, headers and footers.
One 16:9 slide; children are laid out inside.
| Prop | Type | Required | Meaning |
|---|---|---|---|
title |
string | no | Slide title |
"cover": { "type": "Slide", "props": { "title": "Cover" }, "children": ["cover-text"] }- Parts:
title(default 20pt bold) andbody. - In html and pdf each slide takes one page.
- In docx a slide becomes a level-2 heading plus its content, followed by a page break; the
bodypart has no effect there. - Real pptx output comes in version 2.
- Styles: where styles go and how they combine.
- Tables, Images, Sections, headers and footers.
