yoshida yoshida DEV
Open the editor

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:

  1. Every entry in the manifest's sets array is a set.
  2. Every *.cards.json file not already listed names its own design ("design": "designs/x.design.json") and becomes a set, named after the file (monster.cards.json becomes monster; the name is the file name up to the first dot).
  3. A *.cards.csv file must be listed in the manifest, because CSV cannot name its design. An unlisted CSV file is warning 1102.
  4. 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" }
  ]
}
FieldRequiredMeaning
formatyes1
namenoDisplay name of the project
notenoComment
setsnoArray of sets, below
discovernotrue (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_offsetnoHours from UTC for render.date and render.time: a number from -14 to 14, fractions allowed. Default 0. See Time zone
Set fieldRequiredMeaning
designyesPath to the design file
cardsnoPath to a .cards.json or .cards.csv file. Without it the set renders one card with defaults
namenoSet name, used for the output folder and --set. Default: set1, set2, ... by position
canvasnoReplaces 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
paramsnoReplaces param defaults of the design for this set only: an object of param name to value. See Set overrides
groupnoHeading 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. width and height must be more than 0; dpi and bleed 0 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/Berlin are not supported. For a zone with summer time, change the number when the clocks change (for example 2 in summer and 1 in 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 HOURS replaces 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.

↑↓ to moveEnter to openEsc to close