First create a directory for your new website and cd into that directory

Installing with uv

If you don't have UV installed, you can get it here

uv venv venv              # Create a new virtualenv
source venv/bin/activate  # Activate it
uv pip install calico_ssg # Install Calico
calico init               # Create the basis of your new site

Let's look at what we just created.

The directory structure should now look like this:

.
├── content
│   ├── __404__.md
│   ├── _header
│   │   └── menu.md
│   ├── index.md
│   └── site.yml
├── plugins
├── public
└── website.py

The content of your website will live in the content directory while public will contain the static assets that you want to provide (images, documents, etc) and website.py is where the initialization code for Calico lives. You will probably not have to change anything there.

content/site.yml contains the general parameter for your website, let's update the site_name and add a title.

Some of the information in this file is only relevant to "the site" in general but a lot of it can also serve as default for pages that would be omitting a similarly named property.

As an example, remove the title from your homepage (content/index.md) and add a different title to content/site.yml and notice how the page title changes (thw content of the tab in your brower and also the window title).

Creating a page with Calico is as a matter of creating a .md file anywhere in (a subfolder of) the content directory.

Let's try that and create an "About" page

# content/about.md
---
title: About
---
Something about me

The portion in between ---s is the frontmatter. This is where you can define properties and variables that will be used by the rendering widget.

Sometimes, some of those properties can also be used by other, external to the page, widget. For example, the title is used by the menu widget.

Sometimes a single file is not enough and one needs to bring more structure to a page with different sections, maybe columns, images, dividers and more.

Any page in Calico can also be made of multiple files inside a directory representing the page.

Let's give that a go and transform our About page into a multi-file one:

calico single-to-multi-file about

Now instead of having a single about.md file we have a directory about/ containing 2 files:

• data.yml: all multi-file pages need a data.yml which contains the data that would have been in the frontmatter section of the single .md file
• main.md: which contains our markdown. This type of page can have any number of .md files, they will be rendered in the iascending order of their weight first and then alphabetically.

Here we transformed an existing single-file page into a multi-file one. You can of course create multi-files pages by creating the directory and data.yml file, as well as one or more .md files in that directory. As soon as there is a data.yml file inside a directory, that whole directory will be considered to be a single page.

You might have noticed that about/main.md now has a widget property set to text. Widgets are used to render .md files. The default widget is text. Different widgets can have different properties that can be stated in the frontmatter of the respective .md files.

A lot of widgets will take a style property for example, with which you can provide an inline style for that particular html element.

There are a couple of widgets (like text) that are provided by Calico itself but a lot of then will be provided by a plugin , a theme or both! You can refer to the widgets documentation to learn about each widget's possible properties!

You might have noticed a menu appearing at the top of your page. This menu lists all pages at the root of the site (other than the current page).

The menu is situated in the header area.

Your site is composed of a main content (what we have so far been creating when creating pages) as well as other secondary areas. By default, a Calico website will have a header and a footer.

The content of areas are located in special directories starting with _. The menu, for example, is located in content/_header. Areas work a lot like multi-file pages and will render every .md file in the directory.

Let's try it! We will create the content/_footer directory and will add a file inside.

# content/_footer/hello.md
This site was created with [Calico SSG](https://calico-ssg.com)

This footer will now appear on every page.

Like many other things in Calico, areas are hierarchical. This means that, for a specific sub-directory, creating an area folder will take precendence on the one located in its parent folder.

You can try it by creating a content/about/_footer folder and see the footer disappear on the About page.