Docs Format
Project Layout and Manifest
On this page
A project is a folder. All paths inside project files are relative to the project root, use / as separator and must not escape the root (a .. that climbs above the root is error 1203).
my-cards/
yoshida.json project manifest (optional)
designs/<name>.design.json designs
cards/<name>.cards.json card data (JSON)
cards/<name>.cards.csv card data (CSV)
assets/... images and fonts, any structure
.yoshida/ caches, never committed
The tool finds files by their endings (.design.json, .cards.json, .cards.csv), wherever they are in the project, so the designs/ and cards/ folders are a convention, not a requirement. The editor creates and uses them.
Folders named .git, .yoshida, node_modules or out are skipped at any depth when a project is read, by the command line and by the editor (opening a folder, a .yoshida file or a .zip). Files in them are not listed, so designs and card files there are not found by their endings, and cards rendered to the default out/ folder are not read back. The editor leaves these files out of the project entirely. The command line still reads a file there when yoshida.json or a design names its path, so keep fonts, images and set files out of these folders. The command line also skips zig-out and .zig-cache.
All files are UTF-8 without a byte-order mark. JSON follows RFC 8259: no comments and no trailing commas. Use the note field (any object accepts one) for comments.
Every JSON file has "format": 1. Missing is error 1104, an unsupported version is 1105. A "$schema" key is allowed at the top of a file and ignored (see Formatting and Schemas).
Sets
A set is one card file rendered with one design. Output files are written to <out>/<set name>/<card id>.png.
How sets are found:
- Every entry in the manifest's
setsarray is a set. - Every
*.cards.jsonfile not already listed names its own design ("design": "designs/x.design.json") and becomes a set, named after the file (monster.cards.jsonbecomesmonster; the name is the file name up to the first dot). - A
*.cards.csvfile must be listed in the manifest, because CSV cannot name its design. An unlisted CSV file is warning 1102. - A design that no set uses becomes a set with no card data: it renders one card with all defaults. That is how the hello-world project in Getting Started works.
The manifest yoshida.json
Optional. Needed for CSV card data and for naming sets explicitly.
{
"format": 1,
"name": "My Cards",
"sets": [
{ "name": "core", "design": "designs/monster.design.json", "cards": "cards/core.cards.csv" }
]
}| Field | Required | Meaning |
|---|---|---|
format | yes | 1 |
name | no | Display name of the project |
note | no | Comment |
sets | no | Array of sets, below |
discover | no | true (default) finds sets by file ending, as listed under Sets. false uses only the sets listed in sets: a card file or design that is not listed is not a set |
utc_offset | no | Hours from UTC for render.date and render.time: a number from -14 to 14, fractions allowed. Default 0. See Time zone |
| Set field | Required | Meaning |
|---|---|---|
design | yes | Path to the design file |
cards | no | Path to a .cards.json or .cards.csv file. Without it the set renders one card with defaults |
name | no | Set name, used for the output folder and --set. Default: set1, set2, ... by position |
canvas | no | Replaces canvas fields of the design for this set only: any of width, height, dpi, bleed (plain numbers) and background (a color string). See Set overrides |
params | no | Replaces param defaults of the design for this set only: an object of param name to value. See Set overrides |
group | no | Heading of the set in the editor's Design picker. Default: the design's name, so the sets of one design sit together. Has no effect on rendering or output |
With "discover": false rules 2 and 4 above are off, so a project with a manifest can keep spare designs and card files that are not rendered. A discover that is not true or false is error 1103.
Unknown manifest fields are error 1101 with a "did you mean" hint. A path that leaves the project is 1203; a missing file is 1201.
Set overrides
Two sets can use one design with small differences, for example the same card layout in two sizes or with another default title. A set's canvas and params replace those parts of the design for that set only; the design file is not changed and other sets of it keep their own values.
{
"format": 1,
"sets": [
{ "name": "standard", "design": "designs/monster.design.json", "cards": "cards/monsters.cards.json" },
{
"name": "mini",
"design": "designs/monster.design.json",
"cards": "cards/monsters.cards.json",
"canvas": { "width": 375, "height": 525 },
"params": { "frame": "#B08D57" }
}
]
}
- Canvas values are plain numbers (and a color string for
background), not expressions.widthandheightmust be more than 0;dpiandbleed0 or more. Other canvas fields keep the design's value, which may be an expression of the params. - A param value is checked like a value in card data (type,
min,max,max_length, enum options): a wrong one is error 2006 or 2002. A name that is not a param of the design is error 1101. A card still replaces the default with its own value. - An override makes the set load its own copy of the design, so layer sizes that depend on the canvas follow it.
Time zone
utc_offset sets the project's time zone for the expressions render.date and render.time, as a fixed offset in hours from UTC. render.now is not affected: it is always UTC.
{
"format": 1,
"utc_offset": 5.5
}
- The default is
0, UTC. A value outside -14 to 14 is error 1103 when the project loads. - A fixed offset does not follow daylight saving time, and named zones such as
Europe/Berlinare not supported. For a zone with summer time, change the number when the clocks change (for example2in summer and1in winter for Central European Time). - In the editor, the project settings show the offset with a use my browser's offset button, which fills in the offset of the browser's time zone. Previews use the current time, and an export uses the time it started.
- On the command line,
--utc-offset HOURSreplaces the value for one run. See Command Line.
The functions that use the date and time are on Dates and times.
Assets
Images and fonts can live anywhere. Reference them by project path, for example "src": "assets/images/art.png" or "fonts": { "body": "assets/fonts/Body.ttf" }. Paths in image fields can also be templates ("src": "assets/{card_type}.png") or https:// URLs. See Layer: image and Designs.
Several designs in one project
Put each design in designs/, give each its own card file, and the project has one set per pair. The editor's New design… command (in the project menu, or at the end of the Design picker in the toolbar) creates a blank design together with its card file. The Design picker switches between them.
The project menu's Add set… adds a card file for a design and lists it in yoshida.json under its own name. New project… starts with a manifest that lists its one set.
.yoshida/
Reserved for caches. Do not commit it.