5/20/25 10:00 AM · 1 min read

Beta 4 migration guide

Migration guide for Toucan Beta 4

Here’s a list of the most important changes in this release:

Optional Type File Removal via Pipelines

Toucan now allows pipelines to define their own types. This means you can remove separate type files like api.yml, rss.yml, or or sitemap.yml if:

You add definesType: true to the corresponding pipeline
You move the queries: block from the type file into the pipeline

definesType: true
queries:
  - from: ...

You can continue using separate type files — they are not deprecated. This is an optional simplification that reduces the number of files by allowing fewer type files.

File and Directory Restructuring

To align with the updated conventions in Beta 4, migrate files as follows:

From	To
`src/themes/default/types/`	`src/types/`
`src/themes/default/blocks/`	`src/blocks/`
`src/contents/assets/`	`src/assets/`
`src/contents/site.yml`	`src/site.yml`

Home Content Migration

In Beta 4, the home/ directory is no longer special. To migrate:

Move all content from:
```
src/contents/home/
```
to:
```
src/contents/
```
Delete the slug: "" field from the home page frontmatter.
In the corresponding type file src/types/page.yml, add (if missing):
```
default: true
```
This declares the page type as the default, which Toucan will use for the homepage.

Required Asset Configuration in Pipelines

Asset handling must be explicitly defined in your pipelines if your project uses stylesheets, scripts, or images. The following are standard configuration examples that should be included as needed.

Sample for HTML Pipeline

assets:
  behaviors:
    - id: copy
  properties:
    - action: add
      property: css
      resolvePath: true
      input:
        name: "style"
        ext: "css"
    - action: add
      property: js
      resolvePath: true
      input:
        name: "main"
        ext: "js"
    - action: set
      property: image
      resolvePath: true
      input:
        name: "cover"
        ext: "jpg"

Sample for API Pipeline (if images are used)

assets:
  properties:
    - action: set
      property: image
      resolvePath: true
      input:
        name: "cover"
        ext: "*"

These configurations are examples only. Use or adapt them as needed based on your pipeline’s behavior.

Transformer Update

The url transformer has been renamed to path. Update your pipeline files accordingly:

transformers:
    post:
        run: 
            - name: swiftinit
              path: src/transformers
              arguments: {}
        isMarkdownResult: false