better readme. closes #186

i18n_v4
Thomas Reynolds 2011-12-12 15:16:23 -08:00
parent 0b5094e953
commit 7b88b5fb35
1 changed files with 87 additions and 16 deletions

103
README.md
View File

@ -1,22 +1,93 @@
Middleman [![Build Status](http://travis-ci.org/tdreyno/middleman.png)](http://travis-ci.org/tdreyno/middleman) [![Dependency Status](https://gemnasium.com/tdreyno/middleman.png?travis)](https://gemnasium.com/tdreyno/middleman)
=========
# Middleman
Middleman is ever-vigilant against tag-soup, unreadable CSS and repetition. He stands-watch over your Haml, Sass, and CoffeeScript producing only the cleanest and most efficient markup.
Middleman makes developing stand-alone websites simple. The last few years has 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
* Sprockets for combining and minifying assets
* ERb & Haml for dynamic pages and simplified HTML syntax
Middleman gives the stand-alone developer access to all these tool 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.
# Install
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/
The community maintains it's own collection of tips and tricks in the GitHub wiki:
https://github.com/tdreyno/middleman/wiki
Finally, up-to-date generated code documentation is available on RubyDoc:
http://rubydoc.info/github/tdreyno/middleman
# Community
The official community forum is available on Convore at:
https://convore.com/middleman/
# 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/tdreyno/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.
# Build & Dependency Status
[![Build Status](http://travis-ci.org/tdreyno/middleman.png)](http://travis-ci.org/tdreyno/middleman)
[![Dependency Status](https://gemnasium.com/tdreyno/middleman.png?travis)](https://gemnasium.com/tdreyno/middleman)
# How to Run Cucumber Tests
1. Checkout Repository: `git clone https://tdreyno@github.com/tdreyno/middleman.git`
2. Install Bundler: `gem install bundler`
3. Run `bundle` inside the project root to install the gem dependencies.
4. Run test cases: `bundle exec rake test`
# Donate
[![Click here to lend your support to Middleman](https://www.pledgie.com/campaigns/15807.png)](http://www.pledgie.com/campaigns/15807)
## Getting Started
# License
Everything you need to know is on the official site:
http://middlemanapp.com
Copyright (c) 2010 Thomas Reynolds. MIT Licensed, see [LICENSE] for details.
## Mailing List
If you have questions, answers can be found on community forum: https://convore.com/middleman/
## Generated Source Documentation
http://rubydoc.info/github/tdreyno/middleman/master/frames
## Copyright
Copyright (c) 2010 Thomas Reynolds. See LICENSE for details.
[RubyInstaller]: http://rubyinstaller.org/
[LICENSE]: https://github.com/tdreyno/middleman/blob/master/LICENSE