Deployment

v2.1

Deploy your site to GitHub Pages, Netlify, or Vercel

This guide covers deploying your Jekyll site to various hosting platforms.

Prerequisites

Make sure your Gemfile includes all required plugins:

source "https://rubygems.org"

gem "jekyll", "~> 4.3"

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.17"
  gem "jekyll-seo-tag", "~> 2.8"
  gem "jekyll-sitemap", "~> 1.4"
  gem "jekyll-paginate-v2", "~> 3.0"
end

GitHub Pages

The easiest way to deploy is with GitHub Pages.

Setup Steps

  1. Push your code to a GitHub repository
  2. Go to Settings → Pages
  3. Select your branch (usually main)
  4. Your site will be live at username.github.io/repo

Using Remote Theme

If you’re adding Minima+ to an existing repo using remote_theme, create these files in your docs folder:

docs/_config.yml:

remote_theme: E-Segments/minima-plus
baseurl: "/your-repo-name"
plugins:
  - jekyll-remote-theme
  - jekyll-paginate-v2

docs/404.html (Custom 404 page):

---
layout: 404
title: "Page not found"
permalink: /404.html
---

docs/coming-soon.html (Optional pre-launch page):

---
layout: coming-soon
title: "Coming Soon"
headline: "Launching Soon!"
launch_date: "2025-06-01T00:00:00"
permalink: /coming-soon/
---
Tip: All layouts (404, coming-soon, api, cli, changelog) are automatically available when using remote_theme.

Custom Domain

To use a custom domain:

  1. Add a CNAME file with your domain
  2. Configure DNS with your registrar
  3. Enable HTTPS in GitHub Pages settings
example.com
Note: DNS changes can take up to 48 hours to propagate.

Netlify

Netlify offers more features like form handling and serverless functions.

Deploy Steps

  1. Connect your GitHub repository to Netlify
  2. Set build command: jekyll build
  3. Set publish directory: _site
  4. Deploy!

Environment Variables

Add these in Netlify’s dashboard:

JEKYLL_ENV=production

netlify.toml

Create a netlify.toml for build configuration:

[build]
  command = "jekyll build"
  publish = "_site"

[build.environment]
  JEKYLL_ENV = "production"

[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404

Vercel

Vercel is great for performance and global CDN.

Setup

  1. Import your repository in Vercel
  2. Select "Jekyll" as the framework
  3. Deploy

vercel.json

{
  "buildCommand": "jekyll build",
  "outputDirectory": "_site"
}

Cloudflare Pages

Fast and free hosting with Cloudflare’s network.

Configuration

  • Build command: jekyll build
  • Build output: _site
  • Environment variable: JEKYLL_ENV=production

Performance Tips

Enable Compression

Add to your web server config or use a CDN.

Optimize Images

Use modern formats like WebP:

<picture>
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="Description">
</picture>

Caching Headers

Example for Netlify (_headers file):

/assets/*
  Cache-Control: public, max-age=31536000

Custom 404 Page

Minima+ includes a beautiful, animated 404 error page that works automatically with GitHub Pages.

How It Works

GitHub Pages automatically serves 404.html from your site root when a page is not found. The theme includes this file pre-configured.

Customizing 404

Edit 404.html to customize the error page:

---
layout: 404
title: "Page not found"
description: "Custom description here"
permalink: /404.html
suggestions:  # Optional: override navigation suggestions
  - title: "Home"
    url: "/"
  - title: "Docs"
    url: "/docs/"
---

404 for Other Platforms

Netlify: Add to netlify.toml:

[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404

Vercel: Add to vercel.json:

{
  "rewrites": [
    { "source": "/((?!assets|api).*)", "destination": "/404.html" }
  ]
}

Cloudflare Pages: Automatically uses 404.html from root.

Coming Soon / Maintenance Page

Use the Coming Soon page for pre-launch or maintenance mode.

Setup

The theme includes coming-soon.html ready to use:

---
layout: coming-soon
title: "Coming Soon"
headline: "Something Amazing is Coming"
tagline: "We're working hard to bring you something special."
launch_date: "2025-06-01T00:00:00"
social:
  - name: "Twitter"
    icon: "twitter"
    url: "https://twitter.com/handle"
  - name: "GitHub"
    icon: "github"
    url: "https://github.com/repo"
---

Using as Homepage (Pre-Launch)

To make Coming Soon your homepage temporarily:

Option 1: Rename files

mv index.html index-backup.html
mv coming-soon.html index.html

Option 2: Change permalink in coming-soon.html:

---
layout: coming-soon
permalink: /
---

GitHub Pages Pre-Launch Strategy

  1. Create a prelaunch branch from main
  2. On prelaunch, set Coming Soon as the index
  3. Deploy prelaunch branch to GitHub Pages
  4. When ready, switch Pages to deploy from main

Email Collection

By default, emails are stored in browser localStorage (demo mode). For production, connect to an email service:

# coming-soon.html front matter
form_action: "https://buttondown.email/api/emails/embed-subscribe/newsletter"
# Or Mailchimp, ConvertKit, etc.
Tip: Set noindex: true in front matter to prevent search engines from indexing your Coming Soon page.

Troubleshooting

Build Fails

Common causes:
  • Missing dependencies in Gemfile
  • Incorrect Ruby version
  • Syntax errors in YAML files

404 Errors

Make sure your baseurl is set correctly in _config.yml:

# For username.github.io/repo
baseurl: "/repo"

# For custom domain
baseurl: ""

Coming Soon Not Showing

Ensure the permalink is correct and there’s no conflicting index.html.

Next Steps