Migrating from Slate

Migrating from Slate to Rustyll? This guide will help you transition your API documentation from Ruby-based Slate to high-performance Rust-powered Rustyll while preserving the three-column layout and interactive features.

Installation

First, install Rustyll using Cargo (Rust’s package manager):

# 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 Slate sites:

rustyll migrate --from slate --source ./my-slate-project --destination ./my-rustyll-site

This command will:

Copy all Markdown content
Convert Slate’s structure to Rustyll format
Create equivalent Liquid templates for the three-column layout
Set up syntax highlighting and other API doc features
Generate a migration report

Directory Structure Differences

Slate	Rustyll	Notes
`source/index.html.md`	`index.md`	Main content file
`source/includes/*.md`	`_includes/*.md`	Included documentation sections
`source/layouts/layout.erb`	`_layouts/api.html`	Layout template
`source/stylesheets/`	`_sass/`	Styling
`source/javascripts/`	`assets/js/`	JavaScript files
`config.rb`	`_config.yml`	Configuration file

Content Organization

Slate typically has a single large Markdown file with include directives. These are converted to Rustyll includes:

# Slate (index.html.md)
---
title: API Reference

language_tabs: # must be one of https://git.io/vQNgJ
  - shell
  - ruby
  - python
  - javascript

includes:
  - errors
  - authentication

search: true
---

# Introduction

Welcome to the API!

# Slate (includes/errors.md)
# Errors

This API uses the following error codes...

Converts to:

# Rustyll (index.md)
---
title: API Reference
layout: api
language_tabs:
  - shell
  - ruby
  - python
  - javascript
search: true
---

# Introduction

Welcome to the API!

{{% include_relative _includes/errors.md %}}
{{% include_relative _includes/authentication.md %}}

Configuration Conversion

Slate’s Ruby configuration converts to Rustyll’s YAML:

# Slate (config.rb)
set :markdown_engine, :redcarpet
set :markdown, fenced_code_blocks: true, smartypants: true, tables: true
set :base_url, "https://example.com"

Converts to:

# Rustyll (_config.yml)
title: API Documentation
url: https://example.com
markdown: comrak
highlight:
  theme: "monokai"
  line_numbers: true
api_docs:
  language_tabs:
    - shell
    - ruby
    - python
    - javascript
  search: true

Three-Column Layout

Rustyll provides an API documentation theme with the familiar three-column layout:

# _config.yml
theme: api

The layout includes:

Left column: Navigation/table of contents
Middle column: Documentation content
Right column: Code examples

Language Tabs and Code Samples

Slate’s language tabs feature is supported in Rustyll:

# Request example in multiple languages

```ruby
require 'kittn'

api = Kittn::APIClient.authorize!('meowmeowmeow')

import kittn

api = kittn.authorize('meowmeowmeow')

curl "https://example.com/api/kittens" \
  -H "Authorization: meowmeowmeow"

const kittn = require('kittn');

let api = kittn.authorize('meowmeowmeow');

## Search Implementation

Slate's search functionality is replaced with Rustyll's search:

```yaml
# _config.yml
search:
  enabled: true
  provider: lunr  # Fast search engine
  index_fields:
    - title
    - content
    - headings

Styling and Customization

Slate’s styling converts to Rustyll’s SCSS structure:

Slate	Rustyll	Notes
`_variables.scss`	`_sass/_variables.scss`	Theme variables
`screen.css.scss`	`_sass/main.scss`	Main styling
Custom styles	`_sass/custom.scss`	Your customizations

API Documentation Features

Rustyll provides specific features for API documentation:

Feature	Implementation
HTTP request examples	Code blocks with language tabs
Request/response objects	Structured examples with JSON highlighting
Parameter tables	Markdown tables with styling
Authentication details	Special includes for auth sections
Status codes	Styled tables for error codes

Interactive Features

Slate’s interactive features have Rustyll equivalents:

Slate Feature	Rustyll Equivalent
Language switching	JavaScript-based language tabs
Sticky navigation	CSS-based sticky positioning
Scroll spy	JavaScript for navigation highlighting
Code highlighting	Syntax highlighting with Syntect
On-page search	Client-side search implementation

Performance Improvements

Rustyll offers significant performance advantages over Ruby-based Slate:

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

Benefits include:

Build Speed: 10-20x faster builds
Memory Usage: Significantly lower resource consumption
Deployment: Simpler deployment with static files

OpenAPI/Swagger Integration

If you use OpenAPI/Swagger specifications:

# _config.yml
plugins:
  - rustyll-openapi
  
openapi:
  spec_file: api/openapi.yaml
  expand_endpoints: true

Troubleshooting Common Issues

Ruby Dependencies

Unlike Slate, Rustyll doesn’t require Ruby or its dependencies:

No need for Bundler or Gemfile
No middleware dependencies
Simplified deployment

Custom JavaScript

If you have custom JavaScript for your Slate documentation:

Review the JavaScript files in assets/js/
Update DOM selectors to match the new HTML structure
Test interactive features thoroughly

Syntax Highlighting

Rustyll uses Syntect instead of Rouge for syntax highlighting:

Check highlighted code blocks in all languages
Adjust theme if needed
Configure additional languages if required

Migration Checklist

Need Help?

Slate Helper | Rustyll Equivalent

Slate Helper	Rustyll Equivalent
`link_to(text, path)`	`[text](`{% link path %}`)`
`include_file(path)`	`{% include path %}`
`toc_generate`	`{% include toc.html %}`
`language_tabs`	`{% include language-tabs.html %}`

Template Conversion

Slate templates convert to Rustyll layouts:

Slate Template	Rustyll Layout
`layout.erb`	`_layouts/default.html`
`index.html.erb`	`index.html`
`includes/`	`_includes/`
`javascripts/`	`assets/js/`
`stylesheets/`	`assets/css/`

Code Block Conversion

Slate’s code blocks convert to Rustyll’s syntax highlighting:

# Slate
```ruby
def hello
  puts "Hello, world!"
end

Converts to:

# Rustyll
`{% highlight ruby %}
def hello
  puts "Hello, world!"
end
{% endhighlight %}`

Rustyll