Configuration¶
Settings let a folder of documents carry its own page size, theme, fonts and layout thresholds, so every export of it uses the same settings without repeating flags.
The tables on this page are generated from the package when the site is built. Types and allowed values come from platefold/schemas/settings.schema.json, and defaults come from the code that applies them. If the two disagree, the documentation build fails.
Where settings come from¶
Plate|Fold looks for one settings file beside the input: at the root of a folder export, or next to a single file. It recognises these names:
platefold.ymlplatefold.yamlplatefold.json
If there's more than one, the export stops and asks you to pick with --config. --config PATH also loads a file from anywhere.
YAML and JSON are two spellings of the same settings: the same sections and keys, checked against the same schema. TOML is not read. A leftover export.toml stops the export with conversion steps; see moving from export.toml.
Values combine in this order, each overriding the one before:
- Built-in defaults
- The preset, if the file or
--presetnames one - The settings file
- Command-line flags or explicit desktop overrides
--theme source is an explicit per-document selection and therefore overrides a settings file's theme.base when DOCX or XLSX ingestion finds a usable source theme. A converted DOC, ODT or RTF can expose its temporary DOCX theme through that same path, although conversion may change or lose the original details. The configured base remains the visible fallback for a missing or incomplete source theme and applies normally to Markdown/CSV/TSV in a mixed folder. An explicit named --theme NAME uses the named theme instead of importing source colours.
A complete example¶
page:
preset: a4
margin: 18
layout:
inline_fit: 0.8
plate_fit: 0.85
max_custom_width: 600
typography:
font_set: sora
body_size_pt: 10.5
behaviour:
soft_breaks: true
sheets: [Summary, "Quarter 2"]
toc_min_headings: 6
image_dpi: 200
theme:
base: bristol
link: "#8B2545"
The same settings in JSON use the same sections and keys. Add "$schema" pointing at the settings schema if your editor validates JSON against it.
An unknown section, an unknown key or a value outside its allowed range is an error that names the problem.
Presets¶
Paper presets are starting points. Automatic uses Letter body pages for Online and suggests Letter or A4 from your device locale for Print and Tiled print. You can also choose Letter, Legal, Tabloid, A5 through A0, or ANSI C through E. uniform-letter is the legacy option that disables larger pages. See printing and placement for the output modes.
The command-line --locale option and HTTP locale_hint are paper-default hints only. They do not select the interface language or set the source document's language. --ui-locale controls command-line interface messages; source-document language and PDF semantics remain independent.
Advanced layout¶
Open Advanced layout in the desktop to override sheet dimensions, exact margins, diagram fit thresholds, custom plate width, caption space, tile overlap, text sizes and raster DPI. The section starts collapsed and its fields start empty. Empty fields preserve document settings and preset defaults. An entered value stays in place when you change the paper preset; Reset advanced overrides clears those entries and returns to the document settings and selected preset. It does not edit the settings file. These desktop entries last for the current app session; use a settings file for a reusable setup.
page.width and page.height override the preset's dimensions before orientation is applied. For example, 230 × 340 mm with Landscape selected produces a 340 × 230 mm sheet. In Print and Tiled print, every page uses that size. Online uses it for body pages and can still add larger plates.
page.margin_edges sets exact margins in top, right, bottom, left order, in millimetres. It overrides the Full, None or Bottom/right margin selection on every page, including Online plates and custom pages. Running headers and footers are omitted with exact margins. The four numbers must be nonnegative and leave usable space for content and captions.
page:
preset: letter
output_mode: tiled
width: 230
height: 340
margin_edges: [0, 8, 12, 0]
typography:
body_size_pt: 11
behaviour:
image_dpi: 240
mermaid_font_px: 18
mermaid_wrap_px: 300
The same custom sheet and margins on the command line:
platefold diagram.md -o pdfs --output-mode tiled --preset letter \
--page-width 230 --page-height 340 --margin-edges 0 8 12 0
inline_fit and plate_fit are minimum acceptable scales between 0 and 1, excluding zero. They decide when a whole figure moves onto a larger page; they do not enlarge figures. Plate fit and the custom plate width cap apply to Online only. Tiled print keeps figures at their rendered size, so the fit thresholds are disabled there. tile_overlap applies only to Tiled print; see printing and assembling tiles. Changing Mermaid text size or wrap width changes the rendered diagram and its tile count. DPI controls raster downsampling, not vector quality.
The HTTP settings object accepts the corresponding flat names: page_width, page_height, margin_edges, inline_fit, plate_fit, max_custom_width, caption_px, tile_overlap, body_size_pt, mermaid_font_px, mermaid_wrap_px and image_dpi. Omit optional fields to use preset defaults. The HTTP image DPI range remains 36-600, with a default of 150; local exports default to 300. Server resource limits remain operator-owned. Export reports record the effective dimensions, margins and advanced layout values, and the tile count of each tiled figure.
page¶
| Key | Type | Default | Meaning |
|---|---|---|---|
preset |
auto | letter | legal | tabloid | a5 | a4 | a3 | a2 | a1 | a0 | ansi-c | ansi-d | ansi-e | uniform-letter |
auto |
Page-size ladder preset. |
width |
number > 0 | 215.9 mm |
Sheet width in millimetres before orientation is applied; overrides the paper preset. |
height |
number > 0 | 279.4 mm |
Sheet height in millimetres before orientation is applied; overrides the paper preset. |
margin |
number ≥ 0 | 15 mm |
Top and side margins in millimetres. |
margin_bottom |
number ≥ 0 | 18 mm |
Bottom margin in millimetres. |
output_mode |
online | print | tiled |
online |
Online keeps flexible pages; print keeps whole figures on fixed paper; tiled preserves figure scale across sheets. |
margin_mode |
full | none | bottom-right |
full |
Blank margins on all edges, no edges, or only bottom and right. |
orientation |
portrait | landscape |
portrait |
Orientation of the selected body or print sheet. |
locale |
string | device locale |
Locale region used for automatic print paper selection; unknown regions use A4. |
margin_edges |
array | inherited from base |
Exact top, right, bottom and left margins in mm on every page. Overrides the margin preset; omits running headers and footers. |
layout¶
These are the thresholds for the page ladder.
| Key | Type | Default | Meaning |
|---|---|---|---|
inline_fit |
number > 0, ≤ 1 | 0.8 |
Minimum inline scale, at most one. |
plate_fit |
number > 0, ≤ 1 | 0.85 |
Minimum plate scale, at most one. |
max_custom_width |
number 0 or > 24 | 900 mm |
Maximum bespoke width in millimetres; greater than 24 for margins, or zero to disable. |
caption_px |
number ≥ 0 | 52 CSS px |
Vertical caption reservation in CSS pixels. |
tile_overlap |
number ≥ 0, ≤ 50 | 10 mm |
Tiled print: millimetres of the figure repeated on both sheets where they meet; zero butts sheets edge to edge. |
typography¶
| Key | Type | Default | Meaning |
|---|---|---|---|
font_set |
string | sora |
Named font set, using bundled or installed fonts. |
body_size_pt |
number > 0 | 10.2 pt |
Body font size in points. |
The font sets are listed in fonts and pagination.
behaviour¶
sheets is an optional list of exact XLSX sheet names or one-based workbook indexes. An empty list exports every visible worksheet. Prefix an index with # when a workbook also has a numeric sheet name. Hidden and chart sheets cannot be selected.
| Key | Type | Default | Meaning |
|---|---|---|---|
soft_breaks |
boolean | true |
Keep single newlines. |
document_language |
string | `` | Source document BCP 47 language override; empty uses source metadata. Independent of interface locale. |
csv_header |
boolean | true |
Treat the first CSV or TSV row as a repeating table header. |
sheets |
array | () |
XLSX sheets selected by exact name or one-based workbook index; empty means every visible worksheet. |
toc |
boolean | true |
Generate a contents page when enough headings exist. |
bookmarks |
boolean | true |
Add PDF outline bookmarks. |
toc_min_headings |
integer ≥ 0 | 9 |
Minimum headings for a contents page. |
image_dpi |
integer ≥ 1 | 300 DPI |
Placed raster resolution in dots per inch. |
mermaid_font_px |
integer ≥ 1 | 16 CSS px |
Diagram label size in CSS pixels. |
mermaid_wrap_px |
integer ≥ 1 | 260 CSS px |
Diagram label wrapping width in CSS pixels. |
theme¶
base picks a theme by name, or a path to a theme file relative to the settings file. Any colour token set here overrides that theme for this export only. See themes.
| Key | Type | Default | Meaning |
|---|---|---|---|
base |
string | default |
Theme name or path relative to this settings file. |
page |
hex colour | inherited from base |
the paper itself — body background |
accent |
hex colour | inherited from base |
h1 rule, document header rule, code block spine |
accent_soft |
hex colour | inherited from base |
secondary borders drawn from the accent hue |
ink |
hex colour | inherited from base |
body text |
ink_strong |
hex colour | inherited from base |
bold text, table headers |
title |
hex colour | inherited from base |
document title and h1 |
heading |
hex colour | inherited from base |
h2/h3/h4 |
ink_soft |
hex colour | inherited from base |
captions, metadata labels, running header/footer |
rule |
hex colour | inherited from base |
hairlines and table cell borders |
surface |
hex colour | inherited from base |
table header fill, inline code chip |
surface_alt |
hex colour | inherited from base |
zebra striping, code block background |
link |
hex colour | inherited from base |
hyperlink text and string literals in code blocks |
diagram_fill |
hex colour | inherited from base |
Mermaid node fill |
diagram_stroke |
hex colour | inherited from base |
Mermaid node borders and edges |
diagram_text |
hex colour | inherited from base |
Mermaid labels, including edge labels on the page |
diagram_alt_fill |
hex colour | inherited from base |
Mermaid cluster and secondary fill |
diagram_note_fill |
hex colour | inherited from base |
Mermaid note fill |
diagram_note_stroke |
hex colour | inherited from base |
Mermaid note border |
limits¶
Resource ceilings for a single export. Lowering them reduces how much a hostile document can consume; raise one deliberately for an unusually large document.
| Key | Type | Default | Meaning |
|---|---|---|---|
max_markdown_bytes |
integer ≥ 1 | 67108864 (64 MiB) |
Largest Markdown file, in bytes, read as one document. |
max_html_tag_search_bytes |
integer ≥ 1 | 16777216 (16 MiB) |
Most bytes, in total, that reading a Markdown file's raw HTML may search for the '>' that ends each tag. A '<' followed by a letter starts a tag, and one that never closes makes the HTML reader search the rest of the document, so repeated searches can have work proportional to the square of the document's size. The default is 16 MiB of search work; elapsed time depends on the document and machine. |
max_paragraph_rebuild_bytes |
integer ≥ 1 | 2147483648 (2048 MiB) |
Most bytes the Markdown reader may copy while replacing the links, code spans, HTML tags and emphasis of one paragraph. It copies the whole paragraph once per element, so the time grows with the number of elements times the paragraph's length. The default is 2 GiB of cumulative copying work; it is not a document-size limit or an elapsed-time guarantee. |
max_csv_bytes |
integer ≥ 1 | 67108864 (64 MiB) |
Largest CSV or TSV file, in bytes, read as one document. |
max_csv_rows |
integer ≥ 1 | 100000 |
Most logical rows in one CSV or TSV table. A quoted field that spans lines is one row. |
max_csv_columns |
integer ≥ 1 | 512 |
Most columns in any row of one CSV or TSV table. |
max_csv_cells |
integer ≥ 1 | 1000000 |
Most cells in one CSV or TSV table, counted across all rows. |
max_csv_field_characters |
integer ≥ 1 | 1048576 (1 MiB) |
Most characters in a single CSV or TSV field. |
max_archive_entries |
integer ≥ 1 | 4096 |
Most files inside one DOCX or XLSX package, which is a ZIP archive. The temporary-file allowance for a legacy-format converter scales with it. |
max_archive_expanded_bytes |
integer ≥ 1 | 536870912 (512 MiB) |
Most bytes one DOCX or XLSX package may hold, both as the ZIP file on disk and once decompressed. Also caps the DOCX a legacy-format converter may produce. |
max_docx_xml_nodes |
integer ≥ 1 | 1000000 |
Most XML elements plus attributes parsed from one DOCX package, counted across all its parts as they stream in. |
max_xlsx_xml_nodes |
integer ≥ 1 | 6000000 |
Most XML elements plus attributes parsed from one XLSX package, counted across all its parts as they stream in. |
max_sheet_cells |
integer ≥ 1 | 1000000 |
Largest used range, in cells, read from one XLSX worksheet. |
max_sheet_count |
integer ≥ 1 | 128 |
Most sheets one XLSX workbook may declare, and the most entries behaviour.sheets may list. |
max_workbook_cells |
integer ≥ 1 | 1000000 |
Largest combined used range, in cells, read across all the selected worksheets of one XLSX workbook. |
max_document_cells |
integer ≥ 1 | 1000000 |
Most table cells in one document of any format, counted after it is converted to HTML. Limits total table cells; max_cells_per_pass controls the size of each rendering part. These cell limits do not guarantee a maximum export time or memory use. |
max_cells_per_pass |
integer ≥ 1 | 25000 |
Table cells the browser lays out at once. A document with more is printed in parts and joined into one PDF with the pages a single pass would print. Content that cannot be split, such as rows joined by cells that span rows, prints in one pass of up to four times this value; a document with more such content stops with an error. Peak memory grows with this value, about 30 KB per cell. |
max_image_bytes |
integer ≥ 1 | 134217728 (128 MiB) |
Largest single image, in bytes, whether it is a linked file, an inline data URI or an image embedded in DOCX or XLSX. |
max_image_pixels |
integer ≥ 1 | 64000000 |
Most pixels (width times height) in one decoded image. |
max_gif_frames |
integer ≥ 1 | 500 |
Most frames in one animated image. |
max_embedded_bytes |
integer ≥ 1 | 536870912 (512 MiB) |
Total bytes of images and diagrams embedded into one document before it is printed to PDF. |
max_mermaid_source_bytes |
integer ≥ 1 | 8388608 (8 MiB) |
Largest Mermaid diagram source, in bytes. |
max_mermaid_svg_bytes |
integer ≥ 1 | 67108864 (64 MiB) |
Largest SVG, in bytes, that rendering one Mermaid diagram may produce. |
max_pdf_bytes |
integer ≥ 1 | 1073741824 (1024 MiB) |
Largest PDF, in bytes, written for one document. |
max_export_seconds |
number > 0 | 3600 seconds |
Wall-clock time allowed for the whole export, in seconds, including any legacy-format conversion. |
Settings and theme files themselves have a fixed 1 MiB ceiling, because a file can't safely raise the limit used to read it. Security describes what these limits cover and what they don't.
Command-line equivalents¶
| Flag | Settings key |
|---|---|
--preset |
page.preset |
--theme |
theme.base |
--font |
typography.font_set |
--dpi |
behaviour.image_dpi |
--no-soft-breaks |
behaviour.soft_breaks: false |
--no-toc |
behaviour.toc: false |
--no-bookmarks |
behaviour.bookmarks: false |
The full flag list is in the command-line reference.
Moving from export.toml¶
Builds before 1.0.0 read settings from a TOML file named export.toml. Plate|Fold no longer reads TOML. When it finds an export.toml beside the input, or is given a .toml file with --config, the export stops and the message explains how to convert it. It stops instead of carrying on because exporting with the default paper, theme and resource limits, when the file asked for others, would produce PDFs that look finished but are wrong.
The sections and keys did not change, so the conversion is mechanical:
- Write each
[section]line assection:. - Indent each
key = valueline under its section askey: value, keeping the value exactly as written. TOML strings, numbers,trueandfalse, and[...]lists are already valid YAML, and quoted hex colours stay quoted. - Save the result as
platefold.ymlin the same folder, then deleteexport.toml.
For example, this export.toml:
[page]
preset = "a4"
margin_edges = [0, 8, 12, 0]
[theme]
base = "mono"
accent = "#2f5d8c" # comments carry over
[behaviour]
sheets = ["Summary", "#2"]
image_dpi = 150
becomes this platefold.yml:
page:
preset: "a4"
margin_edges: [0, 8, 12, 0]
theme:
base: "mono"
accent: "#2f5d8c" # comments carry over
behaviour:
sheets: ["Summary", "#2"]
image_dpi: 150
If Python 3.11 or later is installed, this command writes the same settings as platefold.json without comments:
python -c "import json, tomllib; json.dump(tomllib.load(open('export.toml', 'rb')), open('platefold.json', 'w'), indent=2)"
If platefold.yml or platefold.json already sits beside an export.toml, the message asks you to copy anything the TOML file still has and delete it.