Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 177 lines (113 sloc) 6.04 kB
fe3d0b9 @paulirish readme updates
paulirish authored
1 # Welcome, Friend!
2
325ebaa @addyosmani Some more readme tweaks.
addyosmani authored
3 ## What am I?
4
5 Yeoman is a robust and opinionated client-side stack, comprised of tools and frameworks that can help developers quickly build beautiful web applications. We take care of providing everything needed to get started without any of the normal headaches associated with a manual setup.
6
7 Yeoman is fast, performant and is optimized to work best in modern browsers.
8
d063611 @sindresorhus Improve readme
sindresorhus authored
9 For more information about the project, see [yeoman.io](http://yeoman.io).
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
10
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
11
fe3d0b9 @paulirish readme updates
paulirish authored
12 ## Installing
13
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
14 * Clone this repo and `cd` into it
d063611 @sindresorhus Improve readme
sindresorhus authored
15 * Run this command: `./setup/install.sh`
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
16 * Navigate to a new directory and run `yeoman init` to make sure everything is working as expected.
450e42c @paulirish adding rvm to install dependencies. cleanup of readme. Install is eas…
paulirish authored
17
fe3d0b9 @paulirish readme updates
paulirish authored
18
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
19 ## Documentation
20
21 Yeoman supports a powerful set of high-level commands. These include:
22
8f98e17 @paulirish more syntax highlighting
paulirish authored
23 ```shell
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
24 yeoman init # Initialize and scaffold a new project using generator templates
25 yeoman build # Build an optimized version of your app, ready to deploy
26 yeoman server # Launch a preview server which will begin watching for changes
27 yeoman test # Run a Jasmine test harness in a headless Phantom.js
28
29 yeoman install # Install a package from the clientside package registry
30 yeoman uninstall # Uninstall the package
31 yeoman update # Update a package to the latest version
32 yeoman list # List the packages currently installed
33 yeoman search # Query the registry for matching package names
34 yeoman lookup # Look up info on a particular package
35
36 ```
37
38 A common initial workflow with Yeoman might be:
39
8f98e17 @paulirish more syntax highlighting
paulirish authored
40 ```shell
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
41 yeoman init # invoke the most basic application scaffold (Bootstrap, Boilerplate etc.)
42 yeoman build # build your project, creating an optimized version in the publish folder
43 yeoman server # create an intermediate version of your app, firing off a watch process.
44
45 ```
46
47 Some more examples of how to use our commands include:
48
8f98e17 @paulirish more syntax highlighting
paulirish authored
49 ```shell
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
50 yeoman init angular:bootstrap # invoke the AngularJS generator scaffold
51 yeoman init angular:controller # invoke the AngularJS Controller sub-generator
52 yeoman install jquery underscore [depName] # install a dependency or dependencies
53 yeoman update jquery # update a specific dependency (e.g jquery)
54 yeoman search jquery # lookup jquery in the bower registry
55 ```
56
57
58 The current complete documentation for Yeoman can be found [here](http://yeoman.github.com/docs/docs.html). We also have extended documentation available [here](https://github.com/mklabs/yeoman/wiki/_pages).
59
60
61
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
62 ### Trouble-shooting
63
64 If for any reason you experience exceptions after the yeoman installation process above, you may find the
65 following steps resolve these issues:
66
8f98e17 @paulirish more syntax highlighting
paulirish authored
67 ```shell
68 cd yeoman/cli
69 sudo -s 'npm install -g && npm link'
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
70 ```
fe3d0b9 @paulirish readme updates
paulirish authored
71
450e42c @paulirish adding rvm to install dependencies. cleanup of readme. Install is eas…
paulirish authored
72 ## Running
fe3d0b9 @paulirish readme updates
paulirish authored
73
d063611 @sindresorhus Improve readme
sindresorhus authored
74 Here's a small shell script that you can save as `server.sh` which opens and serves the current directory:
75
76 ```sh
77 #!/usr/bin/env sh
b9b8779 @ebidel Linux support
ebidel authored
78
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
79 port=$1
d063611 @sindresorhus Improve readme
sindresorhus authored
80 if [ $# -ne 1 ]; then
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
81 port=8000
82 fi
83
d063611 @sindresorhus Improve readme
sindresorhus authored
84 if [ $(uname -s) == "Darwin" ]; then
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
85 open=open
86 else
87 open=xdg-open
88 fi
89
90 $open http://localhost:$port && python -m SimpleHTTPServer $port;
b9b8779 @ebidel Linux support
ebidel authored
91 ```
92
d063611 @sindresorhus Improve readme
sindresorhus authored
93 You then need to make it executable: `$ chmod +x server.sh`
b9b8779 @ebidel Linux support
ebidel authored
94
d063611 @sindresorhus Improve readme
sindresorhus authored
95 For example, run this guy as `$ server` (defaults to port 8000), or supply a port yourself `$ server 3000`.
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
96
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
97
325ebaa @addyosmani Some more readme tweaks.
addyosmani authored
98
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
99 ## Browser Support
100
d063611 @sindresorhus Improve readme
sindresorhus authored
101 * Modern browsers (latest version of Chrome, Safari, Firefox, Opera and IE10)
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
102 * Chrome on Android
103 * Mobile Safari
104
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
105
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
106 ## Platform Support
107
d063611 @sindresorhus Improve readme
sindresorhus authored
108 Yeoman 1.0 will support Mac OS X and will attempt to support Linux as well. We will be aiming to bring in support for Windows in a future version of the project.
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
109
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
110 ## Contribute
111
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
112 ### Repos
113
114 * [Yeoman (CLI, Insights)](http://github.com/yeoman/yeoman)
115 * [Yeoman I/O Holding Page](http://github.com/yeoman/yeoman.io)
d063611 @sindresorhus Improve readme
sindresorhus authored
116 * [Yeoman I/O Site](http://github.com/yeoman/yeoman.io) (site branch)
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
117 * [Yeoman Docs](http://github.com/yeoman/docs)
118
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
119 ### Style Guide
120
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
121 This project follows the [jQuery Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) with an exception of two space indentation and multiple var statements. Please ensure any pull requests follow this closely. If you notice existing code which doesn't follow these practices, feel free to shout and we will address this.
122
b9fe2e5 @sindresorhus Make the CLI code pass JSHint
sindresorhus authored
123 ### Pull Request Guidelines
124
125 - Lint the code by running `grunt` in the `/cli` folder before submitting a pull request
126 - Develop in a topic branch, not master
127
987517f @paulirish update readme with testing info.
paulirish authored
128 ### Tests
129
130 Yeoman has a test suite to ensure it's reliably and accurately working as a developer tool. You can find the main test suite in [`test/test-build.js`](https://github.com/yeoman/yeoman/blob/master/cli/test/test-build.js), most of the assertions are [checks against yeoman cli stdout](https://github.com/mklabs/yeoman/wiki/test-build).
131
b4b6057 @paulirish readme update about testing
paulirish authored
132 To run our test suite:
133
134 ```sh
135 npm test
136 ```
137
138 Do note that if any CLI prompts are not accounted for the test suite will have a timeout failure.
139
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
140 ### Developer Docs
141
142 We have significant developer docs for you if you'd like to hack on Yeoman.
143
144 Currently you can find much of the details on [mklabs' yeoman wiki](https://github.com/mklabs/yeoman/wiki/_pages) but also [our first site's docs section](http://yeoman.github.com/docs/docs.html).
145
146 You're also welcome to `git blame` back to commit messages and pull requests. As a project we value comprehensive discussion for our fellow developers.
b9fe2e5 @sindresorhus Make the CLI code pass JSHint
sindresorhus authored
147
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
148 ## About
149
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
150 Yeoman is an open-source project by [Google](http://google.com) which builds on top of [Grunt](https://github.com/cowboy/grunt) and [node-build-script](http://github.com/h5bp/node-build-script). We utilize a number of useful open-source solutions including:
151
152 * Twitter Bootstrap
d063611 @sindresorhus Improve readme
sindresorhus authored
153 * HTML5 Boilerplate
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
154 * Modernizr
155 * Twitter Bower
d063611 @sindresorhus Improve readme
sindresorhus authored
156 * Node.js
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
157 * NPM
158 * Compass
d063611 @sindresorhus Improve readme
sindresorhus authored
159 * Socket.IO
160 * CoffeeScript
161 * Mocha
162 * Jasmine
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
163 * PhantomJS
d063611 @sindresorhus Improve readme
sindresorhus authored
164 * And [more...](https://github.com/yeoman/yeoman/wiki/Dependencies)
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
165
166 Version 1 of the project features the combined efforts of:
167
d063611 @sindresorhus Improve readme
sindresorhus authored
168 * [Paul Irish](http://paulirish.com)
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
169 * [Addy Osmani](http://addyosmani.com)
d063611 @sindresorhus Improve readme
sindresorhus authored
170 * [Mickael Daniel](http://blog.mklog.fr)
171 * [Sindre Sorhus](http://sindresorhus.com)
8bc0352 @ebidel Update master
ebidel authored
172 * [Eric Bidelman](http://ericbidelman.com)
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
173
d063611 @sindresorhus Improve readme
sindresorhus authored
174 and other developers.
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
175
176 We will be aiming to officially release the project in late July, 2012.
Something went wrong with that request. Please try again.