Cargo is Rust’s build system and package manager. It handles tasks like building your code, downloading dependencies, and compiling packages.

Cargo is the perfect tool to use with Rustyll. Since Rustyll is built as a Rust crate, Cargo manages all dependencies and provides a consistent environment for your projects.

In this tutorial, we’ll show you how to create a new Rustyll project using Cargo and how to take advantage of Cargo’s powerful dependency management features.

This is the recommended way to start using Rustyll

This tutorial helps you get Rustyll set up using Cargo, which is the standard tool for Rust projects. For a simpler approach, you can also use the global installation method in the Quickstart.

Before You Begin

To complete this tutorial, you’ll need to have Rust and Cargo installed. Cargo comes installed with Rust by default. You can check your installation by running:

rustc --version
cargo --version

Create a New Rustyll Project

The easiest way to start a new Rustyll project is to use Cargo to create a new binary project, and then add the Rustyll dependency:

# Create a new binary project
cargo new my-rustyll-website
cd my-rustyll-website

Add Rustyll as a Dependency

Now, we’ll add Rustyll as a dependency in your Cargo.toml file:

# Add rustyll dependency
cargo add rustyll

This will update your Cargo.toml file to include Rustyll as a dependency.

Create A Rustyll Scaffold

Now that Rustyll is added as a dependency, we can use it to generate the scaffolding for our site:

# Generate a new Rustyll site
cargo run -- new --force .

This creates all the necessary files for a new Rustyll site in your current directory.

Serve the Site

Your new website is ready! You can serve the website with:

cargo run -- serve

This will compile your Rustyll project and start a local server. You can visit your site at http://127.0.0.1:4000. From here, you’re ready to continue developing the site on your own.

Optimizing for Development

For faster development, you can use the following features:

# Enable live reloading and incremental builds
cargo run -- serve --livereload --incremental

# Use all CPU cores for parallel processing
cargo run -- serve --threads auto

Commit to Source Control

If you’re storing your new site in version control, you’ll want to ignore the ./target/ directory and any other build artifacts. You can use this .gitignore file to get started:

.gitignore

# Ignore metadata generated by Rustyll
_site/
.sass-cache/
.rustyll-cache/
.rustyll-metadata

# Ignore folders generated by Cargo
/target/
**/*.rs.bk
Cargo.lock

Building for Production

When you’re ready to deploy your site, build it with optimizations enabled:

cargo run --release -- build

This will generate your static site in the _site directory, optimized for production use.