Skip to content

Configuration

Jump to bottom
Andreas Duschl edited this page Jul 28, 2026 · 13 revisions

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: document language, visible fields, gallery layout, media ordering, metadata rendering, expandable prose, overview card display, and detail-page image 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.

Document Language and Expandable Prose

site_rendering.document_language controls the generated document language and defaults to en-US. It is written to the page's <html lang> attribute and lets browsers apply language-aware behavior such as hyphenation.

Creator About text and project Description text collapse only when the rendered text exceeds the configured line count. The desktop and mobile thresholds are configured independently:

{
  "site_labels": {
    "controls": {
      "show_more": "Show more",
      "show_less": "Show less"
    }
  },
  "site_rendering": {
    "document_language": "en-US",
    "creator_page": {
      "about_collapsed_lines": 8,
      "about_collapsed_lines_mobile": 2
    },
    "project_page": {
      "description_collapsed_lines": 8,
      "description_collapsed_lines_mobile": 2
    }
  }
}

show_more and show_less are ordinary control labels, not phrase formats.

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}...",
      "tag_actions_label_format": "Actions for {tag}",
      "find_in_creators_format": "Find in {creators}",
      "find_in_projects_format": "Find in {projects}",
      "find_in_creator_projects_format": "Find in {projects} of {creator}"
    },
    "pages": {
      "creator_collaboration_project_subtitle_format": "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.
  • tag_actions_label_format: {tag} is required. This labels a tag action menu for assistive technology.
  • find_in_creators_format: {creators} is required. This labels the tag-menu entry for filtering the creator overview.
  • find_in_projects_format: {projects} is required. This labels the tag-menu entry for filtering the project overview.
  • find_in_creator_projects_format: {projects} and {creator} are required. This labels the creator-page tag-menu entry for filtering only the current creator's projects.
  • creator_collaboration_project_subtitle_format: {collaborator} is required. This controls the secondary line on collaboration project cards, such as "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": {
      "creator_cards": {
        "display_mode": "image",
        "building_strategy": "aspect",
        "aspect_ratio": "2/3",
        "page_rows": 5,
        "image_max_height": 300
      },
      "project_cards": {
        "building_strategy": "aspect",
        "aspect_ratio": "1/1",
        "page_rows": 100,
        "image_max_height": 300,
        "creator_page_image_max_height": 300
      }
    }
  }
}

creator_cards.display_mode controls the creator overview presentation:

  • image: render portrait image cards with icon badges. Missing creator overview thumbnails use generated defaults.
  • text: render text cards with creator names and non-zero project/media counts, without creator overview thumbnail work.

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 Detail Images

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.

Detail-page image visibility is controlled by page-specific rendering settings:

{
  "site_rendering": {
    "creator_page": {
      "show_profile_image": "show",
      "show_member_profile_images": "show"
    },
    "project_page": {
      "show_cover_image": "show",
      "show_creator_profile_image": "show",
      "show_collaboration_profile_image": "show",
      "show_participant_profile_images": "show"
    }
  }
}

The switches are independent from creator overview card style. For example, you can render text cards on the creator overview while still showing profile images on creator and project detail pages.

Each detail-page image role accepts one of two modes:

  • show: render a source-derived thumbnail when a usable source image exists. If the source image is missing or recoverably unreadable, cr4te omits the image role.
  • hide: omit that image markup and skip thumbnail work for that role.

CLI Overrides

Build and print-config support:

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

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.

cr4te

Clone this wiki locally