Directory Structure

A basic Rustyll site usually looks something like this:

.
├── _config.yml
├── _data
│   └── members.yml
├── _drafts
│   ├── begin-with-the-crazy-ideas.md
│   └── on-simplicity-in-technology.md
├── _includes
│   ├── footer.html
│   └── header.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
│   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
│   ├── _base.scss
│   └── _layout.scss
├── _site
├── .rustyll-cache
│   └── Rustyll
│       └── Cache
│           └── [...]
├── .rustyll-metadata
├── Cargo.toml  # for crate-based themes and plugins
└── index.html # can also be an 'index.md' with valid front matter

Directory structure of Rustyll sites using crate-based themes

A new Rustyll project bootstrapped with rustyll new uses crate-based themes to define the look of the site. This results in a lighter default directory structure: _layouts, _includes and _sass are stored in the theme-crate, by default.

minima is the current default theme, and cargo theme-info rustyll-theme-minima will show you where minima theme's files are stored on your computer.

An overview of what each of these does:

File / Directory	Description
`_config.yml`	Stores configuration data. Many of these options can be specified from the command line executable but it's easier to specify them here so you don't have to remember them.
`_drafts`	Drafts are unpublished posts. The format of these files is without a date: `title.MARKUP`. Learn how to work with drafts.
`_includes`	These are the partials that can be mixed and matched by your layouts and posts to facilitate reuse. The liquid tag `{% include file.ext %}` can be used to include the partial in `_includes/file.ext`.
`_layouts`	These are the templates that wrap posts. Layouts are chosen on a post-by-post basis in the front matter, which is described in the next section. The liquid tag `{{ content }}` is used to inject content into the web page.
`_posts`	Your dynamic content, so to speak. The naming convention of these files is important, and must follow the format: `YEAR-MONTH-DAY-title.MARKUP`. The permalinks can be customized for each post, but the date and markup language are determined solely by the file name.
`_data`	Well-formatted site data should be placed here. The Rustyll engine will autoload all data files (using either the `.yml`, `.yaml`, `.json`, `.csv` or `.toml` formats and extensions) in this directory, and they will be accessible via `site.data`. If there's a file `members.yml` under the directory, then you can access contents of the file through `site.data.members`.
`_sass`	These are sass partials that can be imported into your `main.scss` which will then be processed into a single stylesheet `main.css` that defines the styles to be used by your site. Learn how to work with assets.
`_site`	This is where the generated site will be placed (by default) once Rustyll is done transforming it. It's probably a good idea to add this to your `.gitignore` file.
`.rustyll-cache`	Keeps a copy of the generated pages and markup (e.g.: markdown) for faster serving. Created when using e.g.: `rustyll serve`. Can be configured with configuration options. Rustyll's cache is optimized for speed and can dramatically improve build times for larger sites. This directory will not be included in the generated site. It's probably a good idea to add this to your `.gitignore` file.
`.rustyll-metadata`	This helps Rustyll keep track of which files have not been modified since the site was last built, and which files will need to be regenerated on the next build. Only created when using incremental regeneration (e.g.: with `rustyll serve -I` or `rustyll serve --incremental`). This file will not be included in the generated site. It's probably a good idea to add this to your `.gitignore` file.
`Cargo.toml`	This file lists the Rust crates your site depends on, including Rustyll themes and plugins. It's automatically created when you start a new site with `rustyll new`. Cargo uses this file to manage your site's dependencies.
`index.html` or `index.md`	Provided that the file has a front matter section, it will be transformed by Rustyll. The same will happen for any `.html`, `.markdown`, `.md`, or `.textile` file in your site's root directory or directories not listed above.
`assets`	A directory for storing site assets like images, stylesheets, and JavaScript. These will be copied directly to the output directory during build.
Other Files/Folders	Every other directory and file except for those listed above—such as `css` and `images` folders, `favicon.ico` files, and so forth—will be copied verbatim to the generated site. There are plenty of sites already using Rustyll if you're curious to see how they're laid out.

Parallel Processing Architecture

Rustyll is designed to process your site in parallel, taking advantage of all available CPU cores. This architecture means:

Files are read and processed concurrently
Templates are rendered in parallel when possible
Assets can be generated simultaneously

This is a major difference from Jekyll’s sequential processing model and explains Rustyll’s significantly faster build times.

Performance Tips

To optimize your site’s build performance:

Consider using incremental builds with rustyll serve --incremental

Enable aggressive caching in your config:

# _config.yml
cache:
  enabled: true 
  strategy: aggressive

For large sites, increase the number of threads:

# _config.yml
threads: 8  # or "auto" to use all available cores