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.
You should also be comfortable using the command line.
Site index
To begin using Toucan, a source directory is required for the site. This directory will contain all content, and theme files. This guide provides a quick setup using a minimal starter theme.
The first step is to start a new project for the website and create the source directory with the contents and themes folders:
# The directory for the website
mkdir my-website
cd my-website
# The location of the source files
mkdir src
cd src
# The location of the site contents
mkdir contents
cd contents
The next step involves creating a site index file in YAML format. A index.yml file should be created inside the src/contents directory with the following contents:
# FILE: src/contents/index.yml
baseUrl: "http://localhost:3000/"
title: "My website"
The base URL refers to the site’s final domain where it will be available. In this case, a development environment is being used, which is why http://localhost:3000 was set. For production, the URL should match the site’s domain without the port, and the protocol should be HTTPS.
The site title will be appended to every page as a suffix, with a dash character used as a separator.
The home page
With the basic settings in place, the next step is to create the homepage for the website. Create a home directory inside the src/contents folder:
# The location of the Markdown content, inside the src/contents folder
mkdir home
cd home
Next, create an index.md file to serve as the homepage for the website. Place the Markdown file in the src/content/home directory with the following contents:
---
title: "Home"
description: "Welcome to the home page."
---
# Hello
This is the home page.
The first part of the Markdown, located between the --- characters, is called the front matter. This section defines additional properties for the content, such as the title, description, or the name of the template file used during the site generation process.
Now that we have a simple home page, we still need a theme to render the website. For this purpose we can grab the minimal-theme from GitHub.
# Run this snippet inside the src folder
mkdir themes
cd themes
curl -L -O https://github.com/toucansites/minimal-theme/archive/refs/heads/main.zip
unzip main.zip
mv minimal-theme-main default
rm main.zip
The snippet above retrieves the minimal theme and places it inside the content/themes/default directory. Toucan will automatically use the theme in this folder by default to render the website. With the minimal theme set as default, the website is now ready for generation.
The final website is generated by running the generate command. The generated files will be placed inside the docs folder, which is located next to the src folder.
During development, monitoring the source files for changes can be helpful, which can be done using the watch command. More information can be found in the commands section.
# Run this inside the my-website folder
toucan generate
To preview the website, run the serve command. This will start a basic web server using the Hummingbird framework and host the website locally on port 3000. The contents will be served from the docs folder.
# Run this inside the my-website folder
toucan serve
To preview the site, navigate to http://localhost:3000/ in a web browser.
The site logo might appear to be missing. Let’s address this issue quickly and take a moment to explain how asset management works.
Site assets
Global website assets are stored in the src/contents/assets folder. Any files placed in this folder will be recursively copied to the root directory of the final website.
# Inside the src/contents directory
mkdir assets
cd assets
mkdir images
cd images
# Pick a logo and copy to the images directory
cp ~/my-logo.png ./logo.png
The minimal theme uses the logo.png file as the main image for the website. This file must be placed inside the images folder.
It is also possible to create additional directories and place images, JavaScript, CSS, and other files in the assets folder. These files will be available as global assets when the website is built.
Toucan differentiates between page assets and global assets. Each subpage can have its own assets directory, and together, the subpage and its assets are referred to as page bundles.
The 404 page
Creating a custom “Not Found” page is a common use case for a website. To do this, create a special 404 directory inside the contents folder:
# Inside the src/contents directory
mkdir 404
cd 404
The starting point for the 404 page is an index.md Markdown file. Create this file with the following contents:
---
title: "Not found"
description: "Page not found"
---
# Not found
This page does not exists.
[Take me home](/)
This page includes a “not found” image, which needs to be placed inside the 404/assets directory. As mentioned earlier, pages can have their own assets stored within the page bundle, which, in this case, is the 404 directory.
# Inside the src/content/404 directory
mkdir assets
cd assets
cp ~/not-found.png ./not-found.png
Regenerate the website and refresh the browser window. Ensure that the browser cache is disabled to view the changes properly. Enter an invalid URL to verify that the system redirects to the custom 404 page.
Page bundles
Like the 404 page, every subpage of the website can be defined as a page bundle. Page bundles are simple directories where the slug of the subpage matches the folder name containing the index.md file.
Create a new about subpage by setting up a directory named about and placing an index.md file inside it.
# Inside the src/content directory
mkdir about
Create an index.md file inside the about directory with the following contents:
---
title: "About"
description: "About my website"
---
# About
This page is all about my website.
Customize the contents of the about page as desired. Regenerate the site or use the watch command to monitor for changes and preview the updates in the browser.
Site navigation
The final step of this tutorial is setting up a basic menu for the website. The minimal theme supports navigation, and new menu items can be added by defining them in the site’s index file as shown below:
baseUrl: "http://localhost:3000/"
title: "My website"
navigation:
- label: "Home"
url: "/"
- label: "About"
url: "/about/"
The navigation key should include all the menu items, with each item containing its URL and label.
Page templates
To fully customize the look and feel of a subpage, create a custom Mustache file and reference it in the template front matter key, as done for the homepage. The value should match the location of the template file without the .mustache extension.
This concludes the basics. To learn more about how Toucan works, check out the open-source reference projects. More documentation and tutorials will be available soon. For any questions, feel free to contact us.