Migrating from GitBook

Migrating from GitBook to Rustyll? This guide will help you transition from the JavaScript-based GitBook to Rust-powered Rustyll, keeping your documentation structure while gaining performance and flexibility.

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 GitBook sites:

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

This command will:

Copy all content files
Convert GitBook’s directory structure to Rustyll format
Transform GitBook’s configuration to Rustyll’s _config.yml
Convert GitBook plugins to Rustyll equivalents where possible
Generate a migration report

Directory Structure Differences

GitBook	Rustyll	Notes
Root content files	Root directory	Most content stays in the same location
`book.json`	`_config.yml`	Configuration file
`SUMMARY.md`	`_data/toc.yml`	Table of contents becomes data file
`README.md`	`index.md`	Home page
`styles/`	`_sass/`	Custom styling

SUMMARY.md Conversion

GitBook’s SUMMARY.md becomes a YAML data file in Rustyll:

# GitBook (SUMMARY.md)
# Summary

* [Introduction](README.md)
* [Getting Started](getting-started.md)
  * [Installation](getting-started/installation.md)
  * [Configuration](getting-started/configuration.md)
* [Advanced Topics](advanced.md)

Converts to:

# Rustyll (_data/toc.yml)
- title: Introduction
  url: /
- title: Getting Started
  url: /getting-started/
  children:
    - title: Installation
      url: /getting-started/installation/
    - title: Configuration
      url: /getting-started/configuration/
- title: Advanced Topics
  url: /advanced/

Configuration Conversion

GitBook’s JSON configuration converts to Rustyll’s YAML:

// GitBook (book.json)
{
  "title": "My Documentation",
  "description": "A comprehensive guide",
  "author": "Author Name",
  "plugins": ["search", "highlight", "github"],
  "pluginsConfig": {
    "github": {
      "url": "https://github.com/me/myproject"
    }
  }
}

Converts to:

# Rustyll (_config.yml)
title: "My Documentation"
description: "A comprehensive guide"
author: "Author Name"
repository: "https://github.com/me/myproject"

# Plugin configuration
plugins:
  - rustyll-search
  - rustyll-highlight
  - rustyll-github

GitBook Plugin Conversion

Many GitBook plugins have Rustyll equivalents:

GitBook Plugin	Rustyll Equivalent
search	Built-in search
highlight	Built-in syntax highlighting
github	rustyll-github
ga	rustyll-analytics
sharing	rustyll-social-share
fontsettings	Theme controls
lunr	Built-in search

Content Features

Code Blocks

GitBook code blocks convert easily to Rustyll format:

# Both formats support standard code blocks
```javascript
function hello() {
  console.log("Hello, world!");
}
```

Hints and Callouts

GitBook hints convert to Rustyll includes:

# GitBook
> **Hint:** This is a hint

# Rustyll
`{% include hint.html content="This is a hint" %}`

Page Front Matter

GitBook uses minimal front matter, which Rustyll expands:

# GitBook (minimal or none)
---
description: Getting started guide
---

# Rustyll (expanded)
---
title: Getting Started
description: Getting started guide
permalink: /getting-started/
layout: docs
---

Theme and Styling

GitBook’s theming system is replaced with Rustyll’s:

GitBook Feature	Rustyll Equivalent
`styles/website.css`	`_sass/custom.scss`
Theme plugin	Theme configuration
Font settings	Typography settings

Multi-language Support

If your GitBook uses multiple languages:

# _config.yml
languages:
  - code: en
    name: English
    default: true
  - code: es
    name: Español

# Collections for each language
collections:
  docs_en:
    output: true
    permalink: /en/:path/
  docs_es:
    output: true
    permalink: /es/:path/

Performance Improvements

Rustyll offers significant performance improvements over GitBook:

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

API Documentation

If you’re using GitBook for API documentation:

Use Rustyll’s API documentation plugins
Consider OpenAPI/Swagger integration
Utilize code sample includes

# _config.yml
plugins:
  - rustyll-openapi  # OpenAPI/Swagger support

Search Functionality

GitBook’s search is replaced with Rustyll’s search system:

# _config.yml
search:
  enabled: true
  provider: lunr  # Fast search engine
  index_fields:
    - title
    - content
    - tags
    - categories

Troubleshooting Common Issues

Plugin Dependencies

If your GitBook relies heavily on plugins:

Check for Rustyll equivalents in the plugin ecosystem
Consider custom includes for simple plugin functionality
Use JavaScript for client-side features when needed

If you have complex navigation:

Review the generated _data/toc.yml
Adjust the structure as needed
Consider adding weight/order values for precise control

GitBook.com vs GitBook Legacy

This migration guide primarily addresses GitBook Legacy (open-source version):

For GitBook.com (cloud service) sites, export to Markdown first
Use the exported content with the migration tool
Review the structure and organization