Configuration

cr4te ships with defaults and can load partial JSON config files. CLI options can then override selected behavior.

Print a Config

To inspect the resolved default config:

cr4te print-config

To print a domain-specific config:

cr4te print-config --domain music

Save it if you want a self-contained starting point:

cr4te print-config --domain music > cr4te.config.json

Then build with it:

cr4te build -i path/to/Musicians -o path/to/site --config cr4te.config.json

Config Sections

The top-level sections are:

• site_labels: generated page labels, control labels, metadata labels, and project facet labels.
• site_rendering: visible fields, gallery layout, media ordering, metadata rendering, and portrait visibility.
• media_rules: scan rules, image sampling, naming rules, portrait discovery, and creator/project discovery behavior.

Unknown top-level sections and unknown nested keys are rejected.

Partial Configs

Config files can be partial. Nested sections under site_labels and site_rendering merge recursively into defaults. media_rules merges at the section level.

Example:

{
  "site_labels": {
    "entity": {
      "creator": "Artist",
      "creators": "Artists"
    },
    "counts": {
      "project": "work",
      "projects": "works"
    }
  }
}

site_labels.entity.project and projects are capitalized labels for headings and navigation. site_labels.counts.project and projects are sentence-style labels used in count phrases and creator-card badge tooltips.

Gallery Settings

Overview card galleries and media galleries are configured under site_rendering.galleries.

Gallery strategies:

• aspect: fixed aspect-ratio grid.
• justified: row-based justified image layout.

Example:

{
  "site_rendering": {
    "galleries": {
      "project_cards": {
        "building_strategy": "aspect",
        "aspect_ratio": "1/1",
        "page_size": 100,
        "image_max_height": 350,
        "creator_page_image_max_height": 450
      }
    }
  }
}

aspect_ratio uses two positive integers in width/height order, separated by /. For example, "3/2" produces a landscape card and "2/3" produces a portrait card. Whitespace is accepted and the resolved configuration normalizes the value to canonical width/height form.

Project Metadata Rendering

Project facet rendering is configured under site_rendering.project_metadata.

{
  "site_rendering": {
    "project_metadata": {
      "defaults": {
        "separator": ", ",
        "searchable": false,
        "clickable": false,
        "tags": false
      },
      "fields": {
        "genres": {
          "searchable": true,
          "clickable": true,
          "tags": true
        }
      }
    }
  }
}

Meanings:

• searchable: values are added to overview search text.
• clickable: values render as links to a filtered project overview.
• tags: values appear on tag pages and tag lists.
• separator: controls how multiple values render.

Metadata Presentation

Birth, death, and founding are semantic visible fields. Each visible event combines its underlying date and place when both have content. Their word order and connecting text are configured as generated wording under site_labels.metadata:

Use birth and death in visible_creator_fields, and founding in visible_collaboration_fields. Their labels use the matching keys under site_labels.metadata.

{
  "site_labels": {
    "metadata": {
      "date_and_place_format": "{date} in {place}"
    }
  }
}

Both {date} and {place} must occur exactly once. They may be reordered, for example "{place}, {date}". When only the date or place has a value, cr4te renders that value without applying the combined format.

Media Rules

Important defaults:

• max_search_depth: 5
• image_gallery_sample_max: 20
• image_gallery_sample_strategy: spread
• global_exclude_prefix: _
• metadata_folder_name: meta
• collaboration_separators: ["&", ","]
• portrait_discovery: named
• portrait_basename: portrait
• cover_basename: cover

Portrait Discovery and Visibility

Portrait discovery is a media rule:

{
  "media_rules": {
    "portrait_discovery": "named",
    "portrait_basename": "portrait"
  }
}

Discovery values:

• named: use only an image matching the configured basename, preferring direct matches before nested matches.
• auto: use named matches first, then a portrait-oriented image.

Portrait visibility is a rendering setting:

{
  "site_rendering": {
    "portraits": {
      "visibility": "all"
    }
  }
}

Visibility values:

• disabled: discover and classify portraits normally, but skip portrait thumbnail generation and rendering.
• details: show discovered portraits on creator and project detail pages, but use text cards on the creator overview. Missing portraits are omitted.
• all: show portraits on detail pages and portrait image cards on the creator overview. Missing portraits use generated defaults.

CLI Overrides

Build and print-config support:

• --domain
• --image-sample-strategy
• --portrait-discovery
• --portrait-visibility

When a CLI domain override is applied, it replaces the active project facet field set rather than merging with the existing field set.

Custom Theme Folder

The custom theme folder is deliberately not stored in the JSON configuration because it is an external, potentially machine-specific path. Select it explicitly for a build:

cr4te build -i path/to/Creators -o path/to/site --config cr4te.config.json --themes-dir path/to/themes

See Custom Themes for details.