Basics

Toucan is a modern static site generator, written in Swift, that converts Markdown files into HTML files using a theme.

Prerequisites

Before you start this guide, you must install the Toucan binary by following the provided installation guide.

Familiarity with using the command line is highly recommended, as many of the steps in this guide involve executing commands in a terminal. If you’re new to the command line, consider reviewing a basic tutorial to get comfortable with navigating directories and running commands.

Minimal example

To get started with Toucan, let’s create a minimal example project as a foundation.

Run the following command to initialize a new site:

toucan init

This command will download a minimal starter theme and set up a basic website within a newly created site directory, providing everything you need to begin.

ng>Tip: Use toucan init my-site to create a custom folder named my-site instead of the default site.

The newly created site directory will include all the source materials for your website, such as the src directory, which contains contents, pipelines, themes, and content type definitions. To generate the final website, you need to render the source materials. This process converts the Markdown files and other assets into the final HTML files using the render pipeline.

To generate the final website content, execute the following commands:

# Navigate to the site directory
cd site
# Generate the final website
toucan generate
#2025-04-15T18:03:52+0200 info toucan : baseUrl=nil input=./src output=./docs [toucan_generate] Site generated successfully.

The generated website files will be located in a newly created docs folder. You can host these files on a file server or use a static website hosting provider, such as GitHub Pages. If you choose to host the site, ensure that the correct base URL is configured, which corresponds to your domain name.

Currently, the docs folder contains a local development version of the website. To preview it, run the following command:

toucan serve

Now, navigate to http://localhost:3000 in your browser to view your newly created website. You should see a basic static website generated by Toucan.

Congratulations! You’ve successfully built your first static website using Toucan.

Source Materials

The src directory serves as the foundation of your website, housing all the essential source materials required to build your static site. This includes content files, themes, and configuration files. Below is an overview of the directory structure:

.
├── config.yml
├── contents
│   ├── assets
│   │   ├── CNAME
│   │   ├── css
│   │   │   └── style.css
│   │   └── images
│   │       └── logo.png
│   ├── 404
│   │   └── index.md
│   ├── about
│   │   └── index.md
│   ├── home
│   │   └── index.md
│   ├── sitemap.xml
│   │   └── index.yml
│   └── site.yml
├── pipelines
└── themes

• The config.yml file contains Toucan-specific configurations. You can learn more about it in the next guide.
• The contents folder is where you store Markdown files and public assets, such as JavaScript, CSS, or images. For example:
  • home/index.md serves as your home page.
  • about/index.md represents an about page.
  • 404/index.md corresponds to the “not found” page.
• The sitemap.xml directory, with its index.yml file, provides a basic sitemap for your website.
• The site.yml file allows you to configure site-related properties, such as the name, description, base URL (domain name), and navigation structure. You can also define additional variables here to pass context to your template files. Refer to the template guides for more details.

To see changes reflected on your website, modify files in the contents directory and regenerate the site. Toucan offers a built-in watch command to streamline this process. It monitors file changes in the source directory and automatically regenerates the site:

toucan watch

With the toucan serve command running in a terminal, refresh your browser (ensure the cache is disabled) to instantly view updates made to the source directory.

For more insights into how Toucan works, explore our guides or review open-source reference projects. Additional documentation and tutorials will be available soon. If you have any questions, feel free to reach out to us.