Configuration

Guss is configured by a single guss.yaml file in the project root.

Minimal example

site:
  title: "My Site"
  description: "A site built with Guss"
  url: "https://example.com"
  language: "en"

source:
  type: rest_api
  base_url: "https://cms.example.com"

output:
  output_dir: "dist"
  copy_assets: true

collections:
  posts:
    item_template: "post.html"
    archive_template: "index.html"
    permalink: "/{year}/{month}/{slug}/"
    paginate: 10
    context_key: "post"

site

source

Set type: rest_api for REST CMS sources or type: markdown for local Markdown files.

Markdown source

source:
  type: markdown
  recursive: true
  collection_paths:
    posts: "content/posts"
    pages: "content/pages"

Each key in collection_paths maps a collection name to a directory. All .md files in that directory become items in that collection.

REST API source

source:
  type: rest_api
  base_url: "https://cms.example.com/api/v2"
  timeout_ms: 30000
  auth:
    type: api_key
    header: "X-API-Key"
    key: "your-key-here"
  endpoints:
    posts:
      path: "/posts"
      response_key: "posts"
      params:
        include: "tags,authors"
    tags:
      path: "/tags"
      response_key: "tags"

Auth types

field_maps

Rename or project fields before enrichment. Works for both Markdown and REST adapters.

source:
  field_maps:
    posts:
      body: "html"                  # rename source field "html" → "body"
      author_name: "authors.0.name" # project nested value into new field
      tag_slugs: "tags.slug"        # project array field across all elements

Entries are target_field: "source.dot.path". Numeric path segments index into arrays; array-of-object segments project a sub-field across every element.

cross_references

Inject related items across collections, or synthesize a taxonomy collection from data embedded in another collection (e.g. build a tags collection from the tags embedded in each post):

source:
  cross_references:
    tags:
      from: "posts"       # source collection
      via: "tags.slug"    # dot-path to the linking field on each source item
      match_key: "slug"   # field within each linked element to match against

With this config, each post item gets its tags array resolved to full tag objects. If tags has no files of its own, Guss synthesizes the collection from the embedded data.

output

collections

Each key must match a collection name in your source config.

Archive pages are only generated when both item_template and archive_template are set.

Permalink tokens are plain field lookups on the item's Value:

Example: permalink: "/{year}/{month}/{slug}/" + slug: hello-world, year: 2024, month: 01 → writes to dist/2024/01/hello-world/index.html.

Pagination strategies

When using a REST API source, Guss supports eight pagination strategies evaluated in priority order. Set the field(s) that match your CMS's API:

Configure globally or override per endpoint:

source:
  pagination:
    page_param: "page"
    limit_param: "limit"
    limit: 15
    json_next: "meta.pagination.next"
  endpoints:
    posts:
      path: "/posts"
      response_key: "posts"
      pagination:                      # overrides global for this endpoint only
        total_pages_header: "X-Pages"

Additional pagination fields:

parallel_workers

parallel_workers: 0   # 0 = auto-detect (all CPU cores via OpenMP)

log_level

log_level: "info"   # debug | info | warn | error