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.

Complete Phrase Formats

Generated phrases that combine configurable or dynamic values use complete named-placeholder formats. This keeps word order and connecting text configurable instead of assembling phrases from fixed fragments.

For example:

{
  "site_labels": {
    "controls": {
      "search_placeholder_format": "Search {creators}, {projects}, {tags}..."
    },
    "pages": {
      "creator_collaboration_projects_title_format": "{projects} with {collaborator}"
    },
    "accessibility": {
      "creator_portrait_description_format": "Portrait of {creator}",
      "project_preview_description_format": "Preview of {project}"
    }
  }
}

Named placeholders may be reordered with their surrounding wording. Positional placeholders, unknown placeholders, repeated placeholders, conversions, and format specifications are rejected.

Available placeholders:

• search_placeholder_format: {creators}, {projects}, and {tags} are required.
• creator_collaboration_projects_title_format: {collaborator} is required and {projects} is optional. This supports wording such as "{projects} with {collaborator}" and "Codirected with {collaborator}".
• site_logo_overview_label_format: {overview} is required.
• creator_thumbnail_description_format and creator_portrait_description_format: {creator} is required.
• project_thumbnail_description_format and project_preview_description_format: {project} is required.
• date_and_place_format: {date} and {place} are required.

Standalone nouns, control names, and count labels remain ordinary labels rather than formats.

Gallery Settings

Overview card gallery layout and media-gallery image sizing 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_rows": 100,
        "image_max_height": 300,
        "creator_page_image_max_height": 300
      }
    }
  }
}

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.

Gallery pagination is configured as a positive maximum number of visual rows per page:

• overview card galleries use page_rows
• creator detail-page project-card galleries use site_rendering.creator_page.project_card_gallery_page_rows
• creator detail-page media galleries use site_rendering.creator_page.media_gallery_page_rows
• project detail-page media galleries use site_rendering.project_page.media_gallery_page_rows

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 anywhere below the creator folder, including project folders.

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.