This is a project template for the Middleman Static Site Generator optimized for creating digital books. It is based on the Proteus Middleman Template, and has been extended by the team at Getty Publications.
- HAML: Simple template markup
- Coffeescript: Write javascript with simpler syntax
- Sass (LibSass): CSS with superpowers
- Bourbon: Sass mixin library
- Neat: Semantic grid for Sass and Bourbon
- Bitters: Scaffold styles, variables and structure for Bourbon projects.
- Middleman Live Reload: Reloads the page when files change
- Middleman Deploy: Deploy your Middleman build via rsync, ftp, sftp, or git (deploys to Github Pages by default)
This project is designed for use as a Middleman template. To get started, first make sure you have recent versions of Ruby and Middleman installed.
For best results, we recommend that you have a ruby development environment set up on your machine. Assuming you are using a mac, Thoughtbot's Laptop Script is an excellent place to start. Using this script removes the need to do any of the steps below. If you plan to set up manually, install the following tools (in this order):
- Xcode Command-line tools (
xcode-select --install), or all of Xcode if running on Mac OSX 10.8 or lower - Homebrew package manager
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - Rbenv and ruby-build to manage different versions of Ruby
After install, runrbenv initto setup
brew install rbenv ruby-build - Ruby 2.3.1:
rbenv install 2.3.1(may take some time) - Use this version of ruby everywhere with
rbenv global 2.3.1 - Finally, run
gem install bundlerto install Ruby's Bundler tool. This tool will install the remaining dependencies automatically.
To make use of the PDF generation features, install Prince XML. A free version of Prince is available for non-commercial use. If you plan to use this feature commercially, please purchase an appropriate license.
Create a new project by running this command:
middleman init my_book --template=gettypubs/middleman-book-template
This will create a my_book directory inside the current folder that contains
everything you need to get started.
Consider adding this project to version control by running git init inside
this folder after initializing.
Install dependencies:
bundle install
Run the server
bundle exec middleman
Deploy to Github Pages
bundle exec middleman deploy
Build a PDF
bundle exec middleman build -e pdf
Add data that describes your book to the /data/book.yml file. This file
includes fields for title, author, description, etc.; you are free to add
additional fields.
Stylesheets, fonts, images, and JavaScript files go in the /source/assets/
directory. Vendor stylesheets and JavaScripts should go in each of their
/vendor/ directories. If you are planning on modifying the theme, take a look
at the _variables.scss file in /source/assets/stylesheets/base/.
Inside the /source/ directory, simply create whatever files you need, using
the following format to name them: filename.html.md: The first extension
(.html) represents the final format the file will convert to when built; the
second extension (.md) represents the templating language being used.
Middleman supports a variety of
templating languages.
At the beginning of your files, you can define page-specific metadata (frontmatter). More information on how to use this feature is available here.
There is one special frontmatter value to be aware of: this template pays
special attention to any files which contain a sort_order value, represented
as an integer. Any item that has a sort_order defined becomes a "chapter",
meaning it gets picked up by navigational elements and will automatically get
included in any PDF generated from the site. Here's an example:
---
title: Chapter 1
layout: page
author: Getty Publications
sort_order: 1
---