Angular.io is site for Angular documentation .
This site also includes links to other helpful angular resources including Angular 2, Angular 1, Angular Material, and AngularFire.
Please file Developer Guide, Cookbook, and code sample issues only in this Angular.io github repo.
Angular API issues, cheatsheet corrections, feature requests, defect reports, and technical questions concerning Angular itself belong in the angular source code github repo. We can't handle those topics here and will ask you to re-post them on the angular repo.
How you can help
Filing issues is helpful but pull requests that improve the docs are even better!
Learn how to contribute to Angular.io.
IMPORTANT: Do NOT make changes to cached files under
public/docs/ts/_cache. Cached files are updated through a separate workflow.
This site relies heavily on node and npm.
Make sure you are using at least node v.5+ and latest npm; if not install nvm to get node going on your machine.
Install these npm packages globally:
npm install -g harp gulp
Clone this repo, the angular/angular source code repo, and the dart-lang/angular2 source code repo to the same parent directory. The three cloned repo directories must be siblings, with the latter two repo directories named angular and angular-dart, respectively.
cd into root directory
install the all-docs local packages by running
You probably must rebuild
node-sassin a separate step:
npm rebuild node-sass
See below for code sample development preparation.
All documentation content is written in Jade which has its own syntax.
Be aware of the strict demands imposed by this significant-whitespace language.
We strongly recommend running one of the gulp
serve-and-sync commands described below
while editing content so you can see the effect of your changes as you type.
The documentation relies on specific styles and mixins. Learn about those in the documentation styleguide.
The jade documentation files are language-specific directories under either
For example, all of the TypeScript docs are in
Local server with watches and browser reload
- cd into root directory
- browser will launch on localhost:3000 and stay refreshed automatically.
gulp serve-and-sync: watch all the local Jade/Sass files, the API source and examples, and the dev guide files
gulp serve-and-sync-api: watch only the API source and example files
gulp serve-and-sync-devguide: watch only the dev guide files
gulp build-and-serve: watch only the local Jade/Sass files
Code Sample Development
All documentation is supported by sample code and plunkers.
Such code resides in the
public/docs/_examples directory, under page-specific directories, further divided by language track.
For example, the TypeScript QuickStart sample is in
All samples are in a consistent directory structure using the same styles and the same npm packages, including the latest release of Angular. This consistency is possible in part thanks to gulp-driven tooling. To run the samples locally and confirm that they work properly, take the following extra steps to prepare the environment:
install the canonical node packages for all samples by running
cd back up to
gulp add-example-boilerplate(elevate to admin on Windows) to copy canonical files to the sample directories and create symlinks there for node_modules.
Now cd into any particular sample's language directory (e.g.,
public/docs/_examples/quickstart/ts) and try:
npm startto simultaneously compile-with-watch and serve-in-browser-with-watch
npm run tscto compile only
npm run liteto serve-and-watch in browser
Look at the scripts in
package.json for other options.
Also, open any
plunkr.no-link.html to see the code execute in plunker
(you may have to run
gulp build-plunkers first to create/update).
You must check that your example is free of lint errors.
Sample end-to-end tests
All samples should be covered to some degree by end-to-end tests:
gulp run-e2e-tests --lang=dartto run all Dart tests
gulp run-e2e-tests --filter=quickstartto filter the examples to run, by name
gulp run-e2e-tests --fastto ignore npm install, webdriver update and boilerplate copy
Any combination of options is possible.
Resetting the project
This project generates a lot of untracked files, if you wish to reset it to a mint state, you can run:
git clean -xdf
Also, there is a script available for Linux, OSX and Windows Gitbash users that will setup the project using the steps shown in this section:
Run with current build instead of release packages
Can switch the
@angular packages in
~/public/docs/_examples/node_modules to the current build packages with
gulp install-example-angular --build
Restore to RELEASE packages with
These commands will fail if something is locking any of the packages ... as an IDE often does.
The symptom typically is an error trying to
rm -rf node_modules/@angular.
Solution: unlock the hold on the package(s). In VS Code, re-load the window (
- Angular 1.x: The production ready version of Angular
- Angular Material: An implementation of Material Design in Angular.js
- Gulp: node-based tooling
- Harp: The static web server with built-in preprocessing.
- Sass: A professional grade CSS extension language
- Normalize: A modern, HTML5-ready alternative to CSS resets
- Grids: A highly customizable CSS Grid Framework built with Sass
- Prettify: A JS module and CSS for syntax highlighting of source code snippets.
- Icomoon: Custom built icon fonts