Project partials

Retype can compose a project configuration from multiple .yml files. This helps keep your main retype.yml file small while sharing common settings across several projects or separating local development settings from production build settings.

Project partials support three layering techniques, each applied at a different point in the merge order:

1. Build and start files such as retype.build.yml and retype.start.yml
2. Explicit extends references from a config file
3. Automatic project fragments such as retype.theme.yml

All partial files can contain only the settings they need to change. A shared theme file, for example, does not need to include required project settings such as input, output, or url.

In general, later files override earlier files. The main retype.yml file is merged first, then files referenced by extends, automatic fragments, and build or start files are merged over it.

Build and start files

Retype automatically detects retype.start.yml and retype.build.yml when they are placed beside the main retype.yml project configuration file.

These files are applied only for the matching command and are merged after the main project configuration, explicit extends, and automatic fragments. This makes them useful for keeping local preview settings and production build settings separate.

retype.start.yml

The retype.start.yml file is applied only when running retype start.

Use this file for local development settings, such as whether Retype should open a browser, how the local server should watch files, or preview-only options that should not be part of production builds.

branding:
  label: DRAFT

When retype start runs, Retype automatically detects retype.start.yml beside retype.yml and applies it last for that start process.

retype.build.yml

The retype.build.yml file is applied only when running retype build.

Use this file for production build settings, such as the final output folder, published URL, or other settings that should only apply to generated build artifacts.

lastUpdated:
  date:
    enabled: true

When retype build runs, Retype automatically detects retype.build.yml beside retype.yml and applies it last for that build process.

extends

Use extends in retype.yml to merge one or more additional config files into your project configuration.

extends:
  - ./config/retype.base.yml
  - ./config/theme.company.yml

url: docs.example.com
branding:
  label: Product Docs

A single extended file can also be configured as a string:

extends: ./config/theme.yml

url: docs.example.com

Extended files are resolved relative to the config file that declares them. Remote extension paths are not supported.

The current config file is merged first, then each extended file is merged over it. This means the files listed in extends can override values from the local retype.yml file:

branding:
  title: Shared Docs
  logo: ./logo.svg

search:
  hotkeys:
    - /

extends: ./config/base.yml

branding:
  title: API Docs
  label: Product Docs

The final configuration is equivalent to:

branding:
  title: Shared Docs
  label: Product Docs
  logo: ./logo.svg

search:
  hotkeys:
    - /

Automatic fragments

Retype automatically discovers project fragments placed beside the main project config file. Automatic fragments use the following file name pattern:

retype.<id>.yml

For example:

retype.yml
retype.theme.yml
retype.theme.blue.yml
retype.company.yml

Automatic fragments are useful for shared themes, branding, links, search settings, labels, or other reusable project-level configuration blocks.

theme:
  base:
    primary: "#1e66f5"
    success: "#40a02b"

branding:
  label: Docs

Fragment naming rules

The <id> part must be non-empty and may contain letters, digits, ., -, and _.

The following file names are valid automatic fragments:

retype.theme.yml
retype.theme.blue.yml
retype.theme.company-brand.yml
retype.theme.company_brand.yml
retype.companyx.yml

The following file names are not treated as automatic fragments:

retype.yml
retype.start.yml
retype.build.yml
retype._theme.yml
_retype.theme.yml

Automatic fragments are sorted by their <id>, with parent ids before child ids. For example, retype.theme.yml is applied before retype.theme.blue.yml.

Only one automatic fragment can use a given <id>.

Fragments with extends

Automatic fragments can also use extends:

extends: ./config/theme.base.yml

theme:
  base:
    primary: "#1e66f5"

The fragment is merged first, then its extended file is merged over it. The resolved fragment is then merged after the main retype.yml file, so automatic fragments can override values from the main project configuration.

Merge order

Retype applies project configuration files in the following order:

1. The main retype.yml file
2. Files referenced by extends from retype.yml
3. Automatic project fragments, such as retype.theme.yml
4. Build or start files, such as retype.build.yml or retype.start.yml
5. CLI overrides, such as --override

Later files win over earlier files.

If an automatic fragment or build/start file also uses extends, that fragment or build/start file is merged first, then the files it extends are merged over it. The resolved fragment or build/start file is then merged at its normal position in the order above.

Merge behavior

All layers use the same merge behavior:

For example, arrays are replaced instead of appended:

links:
  - text: Base
    link: /base

extends: ./config/base.yml

links:
  - text: Home
    link: /

The final links value contains only the Base link.