Hand-crafted frontend development

Find a file

Ben Hollis 04d94d9b60 Merge pull request #1201 from middleman/templates-rejig Templates rejig		2014-03-15 19:59:46 -07:00
middleman	move to middleman-templates	2014-03-11 11:07:55 +00:00
middleman-cli	Avoid loading middleman-core unless needed. Fixes #1203 .	2014-03-13 20:27:41 -07:00
middleman-core	friendlier localhost print	2014-03-14 06:46:10 +00:00
middleman-templates	Merge pull request #1201 from middleman/templates-rejig	2014-03-15 19:59:46 -07:00
.gitignore	ignore bin directory	2013-12-28 00:33:33 +00:00
.gitmodules	Move CLI into middleman-cli	2014-01-02 16:39:06 -08:00
.rubocop.yml	include additional files to 'cop'	2013-12-28 18:13:44 +00:00
.travis.yml	Put template rendering in a jail	2014-01-02 16:05:39 -08:00
.yardopts	Move CLI into middleman-cli	2014-01-02 16:39:06 -08:00
CHANGELOG.md	Require Bundler (a Gemfile) for all set up Middleman projects. We still do extension auto-discovery for "init". Gemfile may now be in any parent directory of 'config.rb', in case the Middleman project is in a subdirectory of a larger project.	2014-03-03 23:47:24 -08:00
CONTRIBUTING.md	Doc: topic branch link fix	2013-10-15 13:16:32 +02:00
gem_rake_helper.rb	whitespace [ci skip]	2013-12-30 21:39:28 +00:00
Gemfile	move to middleman-templates	2014-03-11 11:07:55 +00:00
LICENSE.md	Happy 2014!	2014-01-15 14:54:16 +00:00
middleman.sublime-project	write some file change and deletion tests for better data coverage	2013-05-29 10:59:03 -04:00
Rakefile	move to middleman-templates	2014-03-11 11:07:55 +00:00
README.md	Happy 2014!	2014-01-15 14:54:16 +00:00
vendor.yml	Update vendor.yml	2013-06-04 15:23:01 -06:00

README.md

Middleman - Makes developing websites simple

Middleman is a static site generator using all the shortcuts and tools in modern web development. Check out middlemanapp.com for detailed tutorials, including a getting started guide. You can also follow @middlemanapp for updates.

Why Middleman?

The last few years have seen an explosion in the amount and variety of tools developers can use to build web applications. Ruby on Rails selects a handful of these tools:

Sass for DRY stylesheets
CoffeeScript for safer and less verbose javascript
Multiple asset management solutions, including Sprockets
ERb & Haml for dynamic pages and simplified HTML syntax

Middleman gives the stand-alone developer access to all these tools and many, many more. Why would you use a stand-alone framework instead of Ruby on Rails?

These days, many websites are built with an API in mind. Rather than package the frontend and the backend together, both can be built and deployed independently using the public API to pull data from the backend and display it on the frontend. Static websites are incredibly fast and require very little RAM. A front-end built to stand-alone can be deployed directly to the cloud or a CDN. Many designers and developers simply deliver static HTML/JS/CSS to their clients.

Installation

Middleman is built on Ruby and uses the RubyGems package manager for installation. These are usually pre-installed on Mac OS X and Linux. Windows users can install both using RubyInstaller.

gem install middleman

Getting Started

Once Middleman is installed, you will have access to the middleman command. First, let's create a new project. From the terminal:

middleman init MY_PROJECT

This will create a new Middleman project located in the "MY_PROJECT" directory. This project contains a config.rb file for configuring Middleman and a source directory for storing your pages, stylesheets, javascripts and images.

Change directories into your new project and start the preview server:

cd MY_PROJECT
middleman server

The preview server allows you to build your site, by modifying the contents of the source directory, and see your changes reflected in the browser at: http://localhost:4567/

To get started, simply develop as you normally would by building HTML, CSS, and Javascript in the source directory. When you're ready to use more complex templates, simply add the templating engine's extension to the file and start writing in that format.

For example, say I am working on a stylesheet at source/stylesheets/site.css and I'd like to start using Compass and Sass. I would rename the file to source/stylesheets/site.css.scss and Middleman will automatically begin processing that file as Sass. The same would apply to CoffeeScript (.js.coffee), Haml (.html.haml) and any other templating engine you might want to use.

Finally, you will want to build your project into a stand-alone site. From the project directory:

middleman build

This will compile your templates and output a stand-alone site which can be easily hosted or delivered to your client. The build step can also compress images, employ Javascript & CSS dependency management, minify Javascript & CSS and run additional code of your choice. Take a look at the config.rb file to see some of the most common extensions which can be activated.

Learn More

A full set of in-depth instructional guides are available on the official website at: http://middlemanapp.com.

Additionally, up-to-date generated code documentation is available on RubyDoc.

Build & Dependency Status

Community

The official community forum is available at: http://forum.middlemanapp.com

Bug Reports

Github Issues are used for managing bug reports and feature requests. If you run into issues, please search the issues and submit new problems: https://github.com/middleman/middleman/issues

The best way to get quick responses to your issues and swift fixes to your bugs is to submit detailed bug reports, include test cases and respond to developer questions in a timely manner. Even better, if you know Ruby, you can submit Pull Requests containing Cucumber Features which describe how your feature should work or exploit the bug you are submitting.