Configuration Reference

Every configuration key, its type, default value, and purpose. All keys are optional. Run simple-gal gen-config to generate a complete annotated config file.

Top-level keys

KeyTypeDefaultDescription
content_rootstring"content"Path to the content directory. Only meaningful in the root config.
site_titlestring"Gallery"Site title used in breadcrumbs and the browser tab for the index page.
assets_dirstring"assets"Directory for static assets (favicon, fonts, etc.), relative to content root. Contents are copied verbatim to the output root. Silently skipped if it does not exist.
site_description_filestring"site"Stem of the site description file in the content root. If site.md or site.txt exists, its content is rendered on the index page.
content_root = "content"
site_title = "My Portfolio"
assets_dir = "assets"
site_description_file = "site"

[thumbnails]

Controls how thumbnails are cropped and sized.

KeyTypeDefaultDescription
aspect_ratio[u32, u32][4, 5]Width-to-height ratio for thumbnail crops. [1, 1] for square, [3, 2] for landscape.
sizeu32400Short-edge size in pixels for generated thumbnails.
[thumbnails]
aspect_ratio = [4, 5]
size = 400

Common aspect ratio choices:

RatioEffect
[1, 1]Square thumbnails
[4, 5]Slightly tall portrait (default)
[3, 2]Classic landscape
[2, 3]Tall portrait

[images]

Controls responsive image generation.

KeyTypeDefaultDescription
sizes[u32, ...][800, 1400, 2080]Pixel widths (longer edge) to generate for responsive <picture> elements.
qualityu3290AVIF encoding quality. 0 = smallest file / worst quality, 100 = largest file / best quality.
[images]
sizes = [800, 1400, 2080]
quality = 90

Validation rules:

  • quality must be 0--100.
  • sizes must contain at least one value.

[theme]

Layout spacing values. All values are CSS length strings.

KeyTypeDefaultDescription
thumbnail_gapstring"1rem"Gap between thumbnails in album and image grids.
grid_paddingstring"2rem"Padding around the thumbnail grid container.
[theme]
thumbnail_gap = "1rem"
grid_padding = "2rem"

[theme.mat_x]

Horizontal mat (spacing) around images on photo pages. Rendered as CSS clamp(min, size, max).

KeyTypeDefaultDescription
sizestring"3vw"Preferred/fluid value, typically viewport-relative.
minstring"1rem"Minimum bound.
maxstring"2.5rem"Maximum bound.
[theme.mat_x]
size = "3vw"
min = "1rem"
max = "2.5rem"

[theme.mat_y]

Vertical mat (spacing) around images on photo pages. Same structure as mat_x.

KeyTypeDefaultDescription
sizestring"6vw"Preferred/fluid value.
minstring"2rem"Minimum bound.
maxstring"5rem"Maximum bound.
[theme.mat_y]
size = "6vw"
min = "2rem"
max = "5rem"

[colors.light]

Light mode color scheme. Applied by default and when the user's system is set to light mode.

KeyTypeDefaultDescription
backgroundstring"#ffffff"Page background color.
textstring"#111111"Primary text color.
text_mutedstring"#666666"Secondary text: nav menu, breadcrumbs, captions.
borderstring"#e0e0e0"Border color.
separatorstring"#e0e0e0"Separator color: header underline, nav menu divider.
linkstring"#333333"Link color.
link_hoverstring"#000000"Link hover color.
[colors.light]
background = "#ffffff"
text = "#111111"
text_muted = "#666666"
border = "#e0e0e0"
separator = "#e0e0e0"
link = "#333333"
link_hover = "#000000"

[colors.dark]

Dark mode color scheme. Applied when the user's system prefers dark mode (prefers-color-scheme: dark).

KeyTypeDefaultDescription
backgroundstring"#000000"Page background color.
textstring"#fafafa"Primary text color.
text_mutedstring"#999999"Secondary text.
borderstring"#333333"Border color.
separatorstring"#333333"Separator color.
linkstring"#cccccc"Link color.
link_hoverstring"#ffffff"Link hover color.
[colors.dark]
background = "#000000"
text = "#fafafa"
text_muted = "#999999"
border = "#333333"
separator = "#333333"
link = "#cccccc"
link_hover = "#ffffff"

[font]

Typography settings. By default, fonts are loaded from Google Fonts. Set source to use a local font file instead.

KeyTypeDefaultDescription
fontstring"Space Grotesk"Font family name. Used as the Google Fonts family name, or as the font-family name for local fonts.
weightstring"600"Font weight to load.
font_typestring"sans""sans" or "serif". Determines the CSS fallback font stack.
sourcestring(none)Path to a local font file, relative to the site root. When set, generates @font-face CSS instead of loading from Google Fonts. Supported formats: .woff2, .woff, .ttf, .otf.
# Google Fonts (default behavior)
[font]
font = "Space Grotesk"
weight = "600"
font_type = "sans"

# Local font file
[font]
font = "My Custom Font"
weight = "400"
font_type = "sans"
source = "fonts/MyFont.woff2"

[processing]

Parallel image processing settings.

KeyTypeDefaultDescription
max_processesu32(auto: CPU core count)Maximum number of parallel image processing workers. When omitted, uses all available CPU cores. Values larger than the core count are clamped down.
[processing]
max_processes = 4

CSS custom properties

Config values are compiled into CSS custom properties, injected as inline <style> blocks in every page. The stylesheet references these variables rather than hardcoded values.

Color variables

CSS variableConfig key
--color-bgcolors.{light,dark}.background
--color-textcolors.{light,dark}.text
--color-text-mutedcolors.{light,dark}.text_muted
--color-bordercolors.{light,dark}.border
--color-separatorcolors.{light,dark}.separator
--color-linkcolors.{light,dark}.link
--color-link-hovercolors.{light,dark}.link_hover

Light mode values are set on :root. Dark mode values are set inside @media (prefers-color-scheme: dark).

Theme variables

CSS variableConfig keyGenerated as
--mat-xtheme.mat_x.*clamp(min, size, max)
--mat-ytheme.mat_y.*clamp(min, size, max)
--thumbnail-gaptheme.thumbnail_gapDirect value
--grid-paddingtheme.grid_paddingDirect value

Font variables

CSS variableConfig key
--font-familyfont.font + font.font_type (includes fallback stack)
--font-weightfont.weight