Middleman

Learn how to deploy Middleman static sites with Forge for optimal performance and development workflow.

Overview

Middleman is a popular ruby-based static site generator (SSG) tool. You can continuously deploy your Middleman sites to Forge.

Getting Started

Go to your Site Settings > Cloud Compilers and select Middleman.

Now when you push to your GitHub repository, Forge will automatically run the Middleman build process, before making your site ready for deployment to the global CDN.

Prerequisites

Before deploying a Middleman site with Forge:

• Ensure you have a Middleman project with a proper Gemfile
• Configure your Middleman site for production builds
• Set up your config.rb file correctly
• Test your site locally with middleman server

Configuration

Configure your Middleman site for Forge deployment:

Gemfile Configuration

Ensure your Gemfile includes:

source "https://rubygems.org"

gem "middleman"
gem "middleman-autoprefixer"
gem "middleman-minify-html"

Middleman Configuration

Update your config.rb for production:

# Middleman configuration
activate :autoprefixer
activate :minify_html

# Build settings
set :build_dir, "build"
set :css_dir, "stylesheets"
set :js_dir, "javascripts"
set :images_dir, "images"

# Production settings
configure :build do
  activate :minify_css
  activate :minify_javascript
  activate :gzip
end

Build Settings

Forge does not auto-detect Middleman projects. You must manually specify Middleman in your build settings:

1. Navigate to your Site Settings
2. Go to Cloud Compilers section
3. Select Middleman from the available options
4. Configure your build command and output directory

Deployment Options

You can deploy Middleman sites using:

• GitHub Sync: Connect your repository for automatic deployments
• Drag & Drop: Upload the built build folder
• Forge CLI: Use the command line for deployments

Build Process

Once configured, Forge handles the Middleman build process:

1. Installs Ruby dependencies from Gemfile
2. Runs middleman build to generate static files
3. Deploys the contents of the build directory
4. Optimizes assets for production
5. Deploys to the global CDN

Custom Build Commands

If you need custom build commands, create a build script:

#!/bin/bash
# Custom build script
bundle install
bundle exec middleman build
# Additional build steps here

Performance Optimization

Optimize your Middleman site for Forge:

• Use Middleman's built-in asset optimization
• Enable gzip compression
• Optimize images and other assets
• Use CDN for static assets
• Minimize HTTP requests

Advanced Features

Middleman offers several advanced features:

• Data Files: Use YAML/JSON for dynamic content
• Helpers: Create custom helper methods
• Extensions: Add functionality with extensions
• Internationalization: Multi-language support

Troubleshooting

Common Middleman deployment issues:

• Build failures: Check your Gemfile and dependencies
• Missing extensions: Ensure extensions are in your Gemfile
• Configuration errors: Validate your config.rb syntax
• Asset issues: Check file paths and references