Migrating from Cobalt

Migrating from Rust-based Cobalt to Rustyll? This guide will help you transition between these two Rust-powered static site generators, retaining your content and gaining additional features with Rustyll.

Installation

Since both Cobalt and Rustyll are Rust-based, you likely already have Rust installed. If not:

# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Rustyll
cargo install rustyll

Automatic Migration

Rustyll provides a built-in migration tool for Cobalt sites:

rustyll migrate --from cobalt --source ./my-cobalt-site --destination ./my-rustyll-site

This command will:

Copy all content files
Convert Cobalt front matter to Rustyll format
Transform Liquid templates with Cobalt specifics to Rustyll’s Liquid templates
Adjust configuration settings
Generate a migration report

Directory Structure Differences

Cobalt	Rustyll	Notes
`posts/`	`_posts/`	Blog posts
`_layouts/`	`_layouts/`	Layout templates (same structure)
`_includes/`	`_includes/`	Include templates (same structure)
`_data/`	`_data/`	Data files (same structure)
`_defaults/`	Front matter defaults in `_config.yml`	Default front matter values
`assets/`	`assets/`	Static assets (same structure)
`_cobalt.yml`	`_config.yml`	Configuration file
`build/`	`_site/`	Generated site

Content Conversion

Cobalt pages and posts convert to Rustyll format:

---
title: My First Post
layout: post
date: 2023-01-15
tags:
  - rust
  - static site
---

This is my first post.

This format works identically in Rustyll, though posts may need to be renamed to follow the YYYY-MM-DD-title.md format.

Configuration Conversion

Cobalt’s YAML configuration converts to Rustyll’s format:

# Cobalt (_cobalt.yml)
site:
  title: My Cobalt Site
  description: A static site built with Cobalt
  base_url: https://example.com
  data:
    author:
      name: Author Name
      
posts:
  dir: posts
  default:
    permalink: /blog/{year}/{month}/{slug}/

assets:
  sass:
    style: compressed

Converts to:

# Rustyll (_config.yml)
title: My Cobalt Site
description: A static site built with Cobalt
url: https://example.com
author:
  name: Author Name

# Posts configuration
permalink: /blog/:year/:month/:slug/

# Sass configuration
sass:
  style: compressed

Template Differences

Both Cobalt and Rustyll use Liquid templates, but with some differences:

Cobalt (Liquid)	Rustyll (Liquid)
`{{ page.title }}`	`{{ page.title }}`
`{% for post in posts %}`	`{% for post in site.posts %}`
`{% include "header.liquid" %}`	`{% include header.html %}`
`{{ page.permalink }}`	`{{ page.url }}`
`{{ post.slug }}`	`{{ post.slug }}` or `{{ post.path \| slugify }}`

Front Matter Defaults

Cobalt’s default front matter in _defaults/ converts to Rustyll’s front matter defaults:

# _defaults/pages.md in Cobalt
---
layout: page
---

Converts to:

# Rustyll (_config.yml)
defaults:
  - scope:
      path: ""
      type: "pages"
    values:
      layout: "page"

Syntax Highlighting

Both Cobalt and Rustyll use syntax highlighters, with slightly different configuration:

# Cobalt (_cobalt.yml)
syntax_highlight:
  theme: "base16-ocean.dark"

# Rustyll (_config.yml)
highlight:
  theme: "base16-ocean-dark"
  line_numbers: true

Asset Handling

Both generators have similar asset handling capabilities:

Cobalt	Rustyll	Notes
SASS/SCSS processing	Built-in SASS processing	Similar functionality
File copying	Asset copying	Automatic handling
Syntax highlighting	Syntax highlighting	Both use fast engines

Performance Considerations

Both Cobalt and Rustyll are Rust-based and focus on performance, but Rustyll offers enhanced options:

# Rustyll performance options
threads: auto  # Use all available CPU cores
incremental: true  # Enable incremental builds
cache:
  enabled: true
  strategy: aggressive

Extended Features in Rustyll

Rustyll builds on Cobalt’s foundation with additional features:

Collections: More flexible content organization beyond just posts and pages
Live reload: Automatic browser refresh during development
Incremental builds: Only rebuild changed files
Plugin ecosystem: Larger selection of plugins and extensions
Multilingual support: Better handling of multiple languages

Troubleshooting Common Issues

Liquid Template Differences

If you encounter template rendering issues:

Check for Cobalt-specific Liquid syntax
Verify page variable access (particularly with collections)
Update include statements to use .html extension

Front Matter Variables

Some front matter variables work differently:

Cobalt uses permalink for custom URLs, Rustyll uses both permalink and site-wide permalink patterns
Rustyll uses date in posts front matter and filenames
Cobalt’s custom data fields work the same in Rustyll