|
| 1 | +[](https://circleci.com/gh/driftyco/ionic) |
| 2 | + |
| 3 | + |
| 4 | +[](https://waffle.io/driftyco/ionic) |
| 5 | + |
| 6 | +The best place to start with Ionic is our [documentation page](http://ionicframework.com/docs/). |
| 7 | + |
| 8 | +Ionic currently best supports iOS 7+ and Android 4.1+. |
| 9 | + |
| 10 | +# What is Ionic? |
| 11 | + |
| 12 | +Ionic is the open source HTML5 Mobile Framework for building amazing, cross-platform hybrid native apps with HTML, JavaScript, and CSS. |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +We built Ionic because we wanted a framework that focused on building hybrid native apps, rather than mobile websites. We wanted this framework to be obsessive about great design and performance. A framework that left the past behind and focused on the future where mobile devices could make HTML5 feel native. |
| 17 | + |
| 18 | +It's important to realize that Ionic is not a replacement for frameworks used for building mobile web apps. There are a lot |
| 19 | +of great solutions that work well for websites, like [jQuery Mobile](http://jquerymobile.com/). |
| 20 | + |
| 21 | +Ionic is also not a good solution if you need to support older generation devices. Our compatibility *starts* at iOS 6 and Android 4.1. We will never support versions earlier than those. This is a framework for the future. Learn more: [Where does the Ionic Framework fit in?](http://ionicframework.com/blog/where-does-the-ionic-framework-fit-in/) |
| 22 | + |
| 23 | +## Quick Start |
| 24 | + |
| 25 | +To start using ionic, you have two options: copy over the built JS and CSS files, or |
| 26 | +use the `ionic` tool ([ionic-cli](https://github.com/driftyco/ionic-cli)) which can be installed through npm: _(You may need to prefix the command with `sudo` depending on your OS and setup.)_ |
| 27 | + |
| 28 | +```bash |
| 29 | +$ npm install -g ionic |
| 30 | +``` |
| 31 | + |
| 32 | +Then, you can start a new ionic project by running: |
| 33 | + |
| 34 | +```bash |
| 35 | +$ ionic start myproject |
| 36 | +``` |
| 37 | + |
| 38 | +### Manual Start |
| 39 | + |
| 40 | +- Download the latest **stable** release from: |
| 41 | + * The `release` folder of this repository |
| 42 | + * Ionic CDN: [Latest Release](http://code.ionicframework.com/) |
| 43 | + * Using bower: `bower install ionic` |
| 44 | +- Download the **bleeding edge just-from-master release** from: |
| 45 | + * Ionic CDN: [Nightly Build](http://code.ionicframework.com/#nightly) |
| 46 | + * Using bower: `bower install driftyco/ionic-bower#master` |
| 47 | + |
| 48 | +Once you have a release, use `js/ionic.js`, `js/ionic-angular.js`, and `css/ionic.css`. |
| 49 | + |
| 50 | +For most cases, you'll need AngularJS as well. This is bundled in `js/angular/` and `js/angular-ui-router/`. |
| 51 | + |
| 52 | + |
| 53 | +## Demos |
| 54 | + |
| 55 | + - [Ionic Codepen.io Demos](http://codepen.io/ionic/public-list) |
| 56 | + |
| 57 | + |
| 58 | +## Community |
| 59 | + |
| 60 | +* Follow [@ionicframework on Twitter](https://twitter.com/ionicframework) |
| 61 | +* Subscribe to the [Ionic Newsletter](http://ionicframework.com/subscribe/) |
| 62 | +* Have a question that's not a feature request or bug report? [Discuss on the Ionic Forum](http://forum.ionicframework.com/) |
| 63 | +* Read our [Blog](http://ionicframework.com/blog/) |
| 64 | +* Have a feature request or find a bug? [Submit an issue](http://ionicframework.com/submit-issue/) |
| 65 | + |
| 66 | + |
| 67 | +## Authors |
| 68 | + |
| 69 | +Originally created by [Adam Bradley](http://twitter.com/adamdbradley), [Ben Sperry](http://twitter.com/benjsperry), and [Max Lynch](http://twitter.com/maxlynch), Ionic has seen hundreds of great [contributors](https://github.com/driftyco/ionic/graphs/contributors) from around the world, including Ionic Team Members [Perry Govier](http://twitter.com/perrygovier), [Mike Hartington](http://twitter.com/mhartington), and [Tim Lancina](http://twitter.com/dopernicus). |
| 70 | + |
| 71 | +## Development |
| 72 | + |
| 73 | +* `npm install && npm install -g gulp protractor` to setup |
| 74 | +* (if you wish to run end-to-end tests): `webdriver-manager update --chrome` to install the webdriver. |
| 75 | +* `gulp` or `gulp build` to build |
| 76 | +* `gulp docs` to generate docs (read Documentation below for how to test docs locally). |
| 77 | +* `gulp build --release` to build with minification & strip debugs |
| 78 | +* `gulp watch` to watch and rebuild on change |
| 79 | +* `gulp karma` to test one-time |
| 80 | +* `gulp karma-watch` to test and re-run on source change |
| 81 | +* `gulp snapshot` to test e2e tests locally (run `gulp demos` first to generate e2e tests). Be sure to run `./node_modules/.bin/webdriver-manager update --chrome` to first install the chrome webdriver dependency. |
| 82 | + |
| 83 | +### Documentation |
| 84 | + |
| 85 | +* Documentation is generated into `dist/ionic-site`. To test documentation properly, follow these steps: |
| 86 | + 1. Clone ionic-site into `./dist/ionic-site` |
| 87 | + - `git clone git@github.com:driftyco/ionic-site dist/ionic-site` |
| 88 | + 2. Start jekyll, telling it to rebuild whenever the site changes |
| 89 | + - `cd dist/ionic-site && jekyll serve -w` |
| 90 | + 3. Go back to project root and build the docs |
| 91 | + - `gulp docs [--doc-version=(versionName|nightly)]` |
| 92 | + 4. Open localhost:4000 and see your changes! Re-run `gulp docs` again whenever you change something, and jekyll will update the site |
| 93 | + |
| 94 | +### Demos / Kitchen Sink |
| 95 | + |
| 96 | +* The demo site is generated into `dist/ionic-demo`. To test the demos, follow these steps: |
| 97 | + 1. Run `gulp demos [--demo-version=(versionName|nightly)]` |
| 98 | + 2. Start an http server from `dist/ionic-demo`: |
| 99 | + - `cd dist/ionic-demo && python -m SimpleHTTPServer` |
| 100 | + 3. Navigate to `http://localhost:8000/{versionName|nightly}` and use the demos |
| 101 | + 4. Run `gulp demos` again whenever you change the demos |
| 102 | + |
| 103 | +### Commit Conventions |
| 104 | + |
| 105 | +* Uses these [commit conventions](http://github.com/ajoslin/conventional-changelog) |
| 106 | + |
| 107 | +### Pushing New Release of Ionic |
| 108 | + |
| 109 | +- Almost all of the logic for releasing Ionic is done on the Travis server |
| 110 | +- To push a new release: |
| 111 | + 1. Update package.json version to new version |
| 112 | + 2. Generate changelog with `gulp changelog` |
| 113 | + 3. Go through the changelog, and fix any mistakes or clarify any unclear commit messages |
| 114 | + 4. Commit package.json and CHANGELOG.md and push to master |
| 115 | +- Travis will detect that this commit changed the version in package.json and push out all necessary for this new release (tags, release files, site config, ...) |
| 116 | + |
| 117 | +## LICENSE |
| 118 | + |
| 119 | +Ionic is licensed under the MIT Open Source license. For more information, see the LICENSE file in this repository. |
0 commit comments