Eleventy: Static Site Generator with Docker

06-12-2024 - 2 minutes, 3 seconds -
documentation eleventy docker static-site-generator

Introduction

Eleventy (11ty) is a powerful and flexible static site generator that allows developers to build fast and modern websites. Using the femtopixel/eleventy Docker image, you can containerize your Eleventy workflows for consistent builds. However, this Docker container is limited to building the project and serving it locally. This guide explains how to set up Eleventy with Docker, noting why Grav was chosen as an alternative for instant file updates.


Prerequisites

  1. Docker and Docker Compose installed on your system.
  2. A working Eleventy project or the intention to create one.

Steps to Set Up Eleventy with Docker

1. Create a Docker Compose File

Use the following docker-compose.yml to set up Eleventy:

version: '3'

services:
  eleventy:
    image: femtopixel/eleventy
    volumes:
      - ./app:/app
    ports:
      - "8010:8080"
    command: ["--serve"]
    container_name: eleventy

This configuration mounts your project directory (./app) to the container’s /app directory, exposes port 8010 for development, and runs Eleventy’s --serve command.

2. Start the Eleventy Container

To build and serve your Eleventy site locally, run:

docker-compose up -d

Access your site at:

http://localhost:8010

3. Build the Site

Eleventy generates the output site into the _site directory. Use the following Docker command to build the project:

docker run --rm -v /path/to/your/site:/app --name eleventy femtopixel/eleventy --output=/app/_site/

This command mounts the site folder and builds the static files into the _site directory.


Extended Configuration

Adding Plugins or Dependencies

If your project requires additional plugins or dependencies:

  1. Ensure your package.json and package-lock.json files are present in the project folder.
  2. Use Docker’s npm commands to install them:
    docker run --rm -v /path/to/your/site:/app --name eleventy femtopixel/eleventy npm install

Serving a Custom Port

To change the local development port, update the ports section in docker-compose.yml:

ports:
  - "8011:8080"

Access your site at:

http://localhost:8011

Updating the Site

Since Eleventy in Docker doesn't support live file updates, you'll need to stop and restart the container after modifying files:

docker-compose down
docker-compose up -d

Transition to Grav

Eleventy was replaced with Grav in this workflow due to its limitation of requiring a manual rebuild for every file change. Grav offers instant updates by directly dropping Markdown files into the content directory, making it more efficient for projects that require frequent updates.


Resources and References


Conclusion

Eleventy in Docker provides a consistent and portable environment for building static sites. However, for projects requiring frequent and instant content updates, Grav proves to be a better alternative due to its ability to reflect changes instantly without manual rebuilds.