Top 3 Rust static site generators and when to use them

Rust isn’t focused on generating websites, but in this post, we’ll cover three Rust projects that do just that.

Content management systems (CMSs) are tools that enable you to host static content. Static site generators apply that content to templates so they can generate pages in advance to serve immediately when they’re requested.

In this guide, we’ll explore three of the most popular and interesting static site generators for Rust:

1. Cobalt
2. mdBook
3. Zola

We’ll review each project based on the features they offer, take a look at their documentation, and explore some examples to determine production readiness.

1. Cobalt

The first project on our list is Cobalt, which was created entirely using Rust. The project serves as a static site generator. Its primary objective is to reduce the workload for projects getting started with their website.

The project focuses on three pillars to make Cobalt as convenient as possible.

1. Simplicity: Cobalt runs in a matter of minutes but scales for more complex cases
2. Ease of use: Cobalt provides a convenient installation procedure and a workflow-centric command-line tool
3. Speed: Cobalt leverages Rust’s native speed to quickly generate static pages

Let’s take a further look at the command line tool to generate new static websites. The Cobalt CLI tool is very similar to the create-react-app CLI tool. You can instantiate a new project using cobalt init. This generates a new project with the following directory structure.

.
|- _cobalt.yml
|- _layouts
|  |- default.liquid
|- _includes
|  |- header.liquid
|- _data
|  |- movies.json
|- _sass
|  |- base.scss
|- _site
|  |- index.html
|- _defaults
|  |- pages.md
|  |- posts.md
|- posts
|  |- cats.md
|- _drafts
|  |- dogs.md
|- index.liquid

Let’s quickly clarify some of the most important folders. The _layouts directory contains templates that make up the skeleton of your website. It’s possible to include shared template layouts that reside in the _includes directory. Furthermore, you can include JSON data in your templates, which resides in the _data directory. However, Cobalt also supports yaml and toml files for loading dynamic data.

Once your project architecture has been created, you can serve your project using cobalt serve. This will host the project locally at 127.0.0.1:3000.

Key features

• Straightforward templating engine
• CLI tool to generate the project file structure. The tool also hosts much more functionality, such as creating new pages, building the project, and serving the project locally.
• Simple file structure that makes a clear distinction between data, templates, and posts
• Configuration file _cobalt.yml for quickly altering site and page/post options

Code snippets and examples

Let’s take a look at the templating engine and how you can access data from your templates. In this example, we have a list of dog breeds for which we want to generate an unordered list using HTML.

First, let’s define the dog breeds file under _data/dogs.yml.

- name: Corgi
- name: Malamute

Next, let’s create our dog overview template. Notice how we use the for - endfor loop to loop over the dog breeds data.

<ul>
{% for breed in site.data.dogs %}
  <li>{{ breed.name }}</li>
{% endfor %}
</ul>

As you can see, we can access the data folder directly using interpolation. The data is made available in the file _data/dogs.yml. Therefore, we can access it via site.data.dogs. It’s pretty useful since you don’t have to think about imports. All data is available to you in your templates.

Production readiness

To evaluate the production readiness, let’s take a look at the release frequency first. On GithHub, we can find 41 releases at the time of writing. Releases happen infrequently, but developers seem to focus on updating dependencies and making sure the project remains usable, which is a good sign.

Furthermore, Cobalt provides deployment configurations for TravisCI, Git, and GitLab CI.

Lastly, you can access troubleshooting support using the cobalt debug command to detect syntax errors and log additional details while the website is running.

Overall, Cobalt looks pretty stable with support for deployment configurations and troubleshooting issues.

Stats that matter

• GitHub stars: 880
• All-time downloads on crates.io: 8,181
• Versions published: 41

2. mdBook

mdBook enables you to write pages using markdown and publish the generated book as an online book-like website. The project is mostly used for generating documentation and simple static websites.

Again, mdBook comes with a command-line tool although it exposes all its functionality as a Rust crate, so you can integrate mdBook into other projects or build on top of the project.

You can generate a new mdBook project via the CLI using mdbook init. This command generates the following file structure.

project-name/
├── book
└── src
    ├── chapter_1.md
    └── SUMMARY.md

The src directory contains the markdown files while the book directory contains the rendered output. You can use the mdbook build command to build the book. You have to define a SUMMARY.md file. This file tells the mdbook build command on how to structure your book.

Key features

• Markdown-based content
• CLI tool to generate, build, test, and serve your project
• Ability to add preprocessors
• Availability of API docs if you would like to integrate mdBook into an existing project

Code snippets and examples

Let’s take a look at some preprocessor plugins, which you can enable by installing them. A very simple plugin called mdbook-linkcheck verifies whether each link in your text is valid and links to a reachable website.

You must first install the plugin and then add it to the book.toml file, which contains all configurations for your book.

Here’s an example from the documentation that shows how you can enable a plugin:

$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck]  # enable the "mdbook-linkcheck" renderer

$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend

Production readiness

To evaluate the production readiness, let’s take a look at the release frequency. On GithHub, we can find 55 releases so far. The project is actively maintained; developers regularly add both fixes as new functionality.

The project provides examples of how to set up continuous integration (CI) for Travis CI and GitHub Pages. The documentation itself is very clean and straightforward.

mdBook is a good choice for a simple reference website for tech projects. However, I wouldn’t use it to build a more advanced website. For complex projects, I prefer using Cobalt because provides data integrations and templating functionality.

Stats that matter

• GitHub stars: 5.1k
• All-time downloads on crates.io: 1,430,412
• Versions published: 55

3. Zola

The last project we’ll explore is Zola, which also serves as a static site generator.

Zola comes as a single executable with no dependencies. Therefore, installation is very straightforward. Moreover, it allows you to generate an average site in less than a second, according to the official website. Zola focuses on blogs, knowledge bases, landing pages, or a combination of the above.

Since Zola comes as an executable, you can use it as a CLI tool. Therefore, you can generate a new Zola project using zola init. This renders the following directory structure.

.
├── config.toml
├── content
├── sass
├── static
├── templates
└── themes

All project configurations reside in the config.toml file. The content folder contains all markup content. There’s a templates folder that contains all templates to render your site. You can find more information about templates in the documentation.

Key features

• Elaborate documentation
• Ability to define shortcodes for common or complex HTML elements
• Built-in search index
• Supports multilingual sites
• Ability to automatically resize images
• Comes with pagination, RSS feed, sitemap, robots.txt, breadcrumbs, internal linking, and 404 error pages

Code snippets and examples

It’s important to know that Zola doesn’t ship with regular markdown. It comes with the concept of augmented markdown. This enables you to create shortcodes for common elements you need. Why? Markdown is not great for injecting more complex HTML or inline styling.

Here’s an example where we create a shortcode to embed a YouTube video.

<div {% if class %}class="{{class}}"{% endif %}>
    <iframe
        src="https://www.youtube.com/embed/{{id}}{% if autoplay %}?autoplay=1{% endif %}"
        webkitallowfullscreen
        mozallowfullscreen
        allowfullscreen>
    </iframe>
</div>

Here, we inject an iframe that points towards a YouTube video. Next, you can use the create shortcode directly in your templates, like this:

Here is a YouTube video:

{{ youtube(id="dQw4w9WgXcQ") }}

{{ youtube(id="dQw4w9WgXcQ", autoplay=true) }}

As you can see, you can even pass arguments to your shortcode.

Production readiness

Zola excels when it comes to production readiness. First of all, it comes with excellent documentation and a rich set of features. Having RSS feed integration, automatic site map generation, pagination capabilities, and support for multilingual sites saves you a lot of time.

Furthermore, Zola comes with continuous integration support. It supports the following deployment options:

• Netlify
• Vercel (previously Zeit)
• GitHubPages
• GitLab Pages

Lastly, there is an active community in Zola’s Discourse group where you can ask support questions and submit feature requests.

In no uncertain terms, Zola is the clear winner when it comes to production readiness.

Stats that matter

• GitHub stars: 4.3k
• (Versions not available on crates.io)
• Versions published: 31

Conclusion

Let’s briefly recap the three Rust static site generators we explored.

• Cobalt is focused on simplicity and enables you to load data in your templates. Cobalt is a great solution for quickly creating a scalable static site.
• mdBook is not a great solution for creating a website, but it serves well for documentation projects.
• Zola comes with a rich set of features and shows great production readiness. It also has excellent documentation for developers.

Personally, I prefer Zola because it comes with so many prebuilt features, such as breadcrumbs and multilingual support. For a simple reference or documentation project, I would choose for mdBook. That said, you want to build a simple website quickly, you might consider using Cobalt.