Skip to content

Commit

Permalink
Version 1.9.0 (tars#281)
Browse files Browse the repository at this point in the history 
* Version 1.9.0
* tars#255
* tars#234
* tars#232
* Update docs
  • Loading branch information
@artem-malko
artem-malko authored Oct 9, 2016
1 parent 7d65f33 commit b970747
Show file tree
Hide file tree
Showing 37 changed files with 515 additions and 311 deletions.
66 changes: 34 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ English description | <a href="README_RU.md">Описание на русско

[![Mac/Linux Build Status](https://img.shields.io/travis/tars/tars/master.svg?label=Mac%20OSX%20%26%20Linux&style=flat-square)](https://travis-ci.org/tars/tars) [![Windows Build status](https://img.shields.io/appveyor/ci/artem-malko/tars/master.svg?label=Windows&style=flat-square)](https://ci.appveyor.com/project/artem-malko/tars/branch/master) [![Gitter](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg?style=flat-square)](https://gitter.im/tars/tars?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

TARS is a builder for modern frontend of any complexity, which is based on [Gulp.js](http://gulpjs.com/). It facilitates and accelerates process of web-development. TARS will be suitable for teams and individual developer. It solves the most routine cases associated with a web-development and it brings you more pleasure from work.
TARS is a builder for modern frontend of any complexity, which is based on [Gulp.js](http://gulpjs.com/). It facilitates and accelerates process of web-development. TARS will be suitable for teams and individual developers. It solves the most routine cases associated with web-development and brings you more pleasure from work.

TARS is the framework for gulp, including a set of gulp-tasks and it allows the ability to easily expand (creating new tasks) and modification of existing tasks, provides comfortable architecture for storage tasks and watchers in the project.
TARS is a framework for gulp, including a set of gulp-tasks. It allows for easy expansion (creating new tasks) and customization (modification of existing tasks), provides comfortable architecture for tasks and watchers storage in the project.

There is [TARS-CLI](https://github.com/tars/tars-cli) in order to not install all dependencies all the time, when you are installing TARS. So, TARS is not a npm-package by itself. This decision was decided so that everyone can customize the builder as comfortable as possible for themselves. CLI — just simple interface for builder, which includes all dependencies for TARS.
To bypass dependencies installation for every TARS project, [TARS-CLI](https://github.com/tars/tars-cli) was created. As such, TARS is not a npm-package by itself. This decision was made so that everyone could comfortably customize the builder for themselves. TARS-CLI is just a simple builder interface, which includes all dependencies for TARS.

**It is strongly recommended to use TARS-CLI for developing from this moment.**
**It is strongly recommended to use TARS-CLI for development.**

You can install TARS-CLI via NPM. More info in [project's repository](https://github.com/tars/tars-cli).

Expand All @@ -22,19 +22,19 @@ You can install TARS-CLI via NPM. More info in [project's repository](https://gi

Listed below are just a little part of the features. In fact builder has much more.

* [Jade](http://jade-lang.com/) or [Handlebars](http://handlebarsjs.com/) as html-templater. You can also use a regular html. Read more [in docs](/docs/en/html-processing.md).
* [Webpack](https://webpack.github.io) (with [Hot Module Replacing](https://webpack.github.io/docs/hot-module-replacement.html)) or simple JavaScript-code concatenation into one bundle.
* Using json (js-object actually, which can be described in json) to transfer data in templates (optional, but it is very cool thing that will let you to rid of copypast). Read more [in docs](/docs/en/html-processing.md#%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D0%BC%D0%BE%D0%B4%D1%83%D0%BB%D1%8F%D0%BC%D0%B8-%D0%B8-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D0%BC%D0%B8-%D0%B2-handlebars).
* [Jade](http://jade-lang.com/), [Pug](https://pugjs.org/api/getting-started.html) or [Handlebars](http://handlebarsjs.com/) as html templater. You can also use a regular html. Read more [in docs](/docs/en/html-processing.md).
* [Webpack](https://webpack.github.io) (with [Hot Module Replacing](https://webpack.github.io/docs/hot-module-replacement.html)) or simple JavaScript code concatenation into one bundle.
* Using json (js-object actually, which can be described in json) to transfer data in templates (optional, but it is a very cool thing that will let you get rid of copypaste). Read more [in docs](/docs/en/html-processing.md#%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D0%BC%D0%BE%D0%B4%D1%83%D0%BB%D1%8F%D0%BC%D0%B8-%D0%B8-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D0%BC%D0%B8-%D0%B2-handlebars).
* [TARS-CLI](https://github.com/tars/tars-cli) and **auto update of your project**.
* You can use ES6 (and some experimental features from ES7) right now. [More info](/docs/en/js-processing.md).
* [SCSS (SASS)](http://sass-lang.com/), [LESS](http://www.lesscss.ru/) or [Stylus](http://learnboost.github.io/stylus/) as a preprocessor for css. Also it includes a small set of mixins. Sourcemaps are included. You can use .scss and .sass extension then scss is selected as preprocessor. You can use .scss and .sass files together. Read more [in docs](/docs/en/css-processing.md). [PostCSS](https://github.com/postcss/postcss) with [autoprefixer](https://github.com/postcss/autoprefixer) is supported by default and it is really easy [to use additional plugins for PostCSS](/docs/en/options.md#postcss).
* No external libraries and plugins (except [html5shiv](https://ru.wikipedia.org/wiki/Html5_Shiv)). Yes, this is a feature because you can choose library for using. Sourcemaps for JavaScript is included.
* [Chokidar](https://github.com/paulmillr/chokidar) module is used for watching files
* Sharing of markup from your local computer to an external web, optional. And of course it has a livereload in browser (and not just locally) + GUI to control panel for devices, on which markup was shearing.
* No external libraries or plugins (except [html5shiv](https://ru.wikipedia.org/wiki/Html5_Shiv)). Yes, this is a feature because you can choose which library to use. Sourcemaps for JavaScript are included.
* [Chokidar](https://github.com/paulmillr/chokidar) module is used to watch files
* Optional markup sharing from your local computer to the world. And of course it has livereload in browser (and not just locally) + GUI control panel for devices, to which markup is shared.
* [You can easily add new tasks and watchers](/docs/en/tasks-and-watchers.md). There are several examples of how to create and use a new task or watcher inside the TARS. Thereby, it is really easy to add any task from your builder to TARS or integrate TARS into your project.
* Smart work with images. First of all with vector(svg). There will be no more hell with markup for screens with high pixel density. TARS supports two workflows of working with SVG: [SVG-sprites](docs/en/svg-processing.md#svg-sprites) and [SVG-symbols](docs/en/svg-processing.md#svg-symbols).
* Several modes of assembly (common, with minified files, with hash in the title of css- and js-files for deploy).
* Creating archive with the ready build.
* Smart work with images. First of all with vector (svg). There will be no more hell with markup for screens with high pixel density. TARS supports two workflows of working with SVG: [SVG-sprites](docs/en/svg-processing.md#svg-sprites) and [SVG-symbols](docs/en/svg-processing.md#svg-symbols).
* Several modes of assembly (common, with minified files, with hash in the title of css and js files for deployment).
* Creating archive with a complete build.

## Documentation

Expand All @@ -56,10 +56,10 @@ It is important! All examples in documentation use the default settings.

## Installation

**Attention, [TARS-CLI](https://github.com/tars/tars-cli) is the preferably
way to work with TARS. It is more comfortable, fast to work with TARS-CLI. In case of using TARS with TARS-CLI all installation steps are not necessary!**
**Attention, [TARS-CLI](https://github.com/tars/tars-cli) is the preferred
way to work with TARS. It is faster and more comfortable to work with TARS-CLI. In case of using TARS with TARS-CLI all installation steps are not necessary!**

You need to [install `Node.js`](http://nodejs.org/) with version equal to 4.x.x or higher. If you use Node.js version 5.x.x, please, be sure, that you use npm version 3.x.x and higher. Otherwise update npm by using command:
You need to [install `Node.js`](http://nodejs.org/) with version equal to 4.x.x and higher. If you use Node.js version 5.x.x, please, make sure, that you use npm version 3.x.x and higher. Otherwise update npm by using command:

```bash
npm i -g npm
Expand All @@ -70,7 +70,7 @@ For Windows you have to do some more steps:
* navigate to C:\Program Files (x86)\nodejs or C:\Program Files\nodejs via cmd.exe or any available terminal. The path depends on how Node.js was installed;
* run command `npm install npm@latest`.

If you get a **Permission denied** or **Error: EACCES** error, you should run the previous command again in sudo.
If you get a **Permission denied** or **Error: EACCES** error, you should run the previous command again in sudo (as Administrator for Windows).

Next you need to install gulp globally. (You may need rights of superuser or administrator).

Expand All @@ -92,37 +92,39 @@ After installing of all dependencies you need to open tars-config (detailed desc
gulp init
```

**Attention, [TARS-CLI](https://github.com/tars/tars-cli) is the preferably
way to work with TARS. [Init command is available in TARS-CLI too](https://github.com/tars/tars-cli/blob/master/docs/en/commands.md#tars-init).**
**Attention, [TARS-CLI](https://github.com/tars/tars-cli) is the preferred
way to work with TARS. It is faster and more comfortable to work with TARS-CLI. [Init command is available in TARS-CLI too](https://github.com/tars/tars-cli/blob/master/docs/en/commands.md#tars-init).**

This command will create the basic file structure, download tasks for selected templater and css-preprocessor.
Everything is ready, make it work! :)
Everything is ready, get to work! :)


## Basic commands

**Attention, [TARS-CLI](https://github.com/tars/tars-cli) is the preferably
way to work with TARS. It is more comfortable, fast to work with TARS-CLI. All commands are available and [described in TARS-CLI](https://github.com/tars/tars-cli/blob/master/docs/en/commands.md), so use only TARS-CLI for working with your project. TARS used Gulp to start tasks, when CLI was not created.**
**Attention, [TARS-CLI](https://github.com/tars/tars-cli) is the preferred
way to work with TARS. It is faster and more comfortable to work with TARS-CLI. All commands are available and [described in TARS-CLI](https://github.com/tars/tars-cli/blob/master/docs/en/commands.md), so use only TARS-CLI for working with your project. TARS used Gulp to start tasks, when CLI was not created.**

`gulp init` — initializes project with the specified settings in the tars-config. Creates a file structure.

`gulp re-init` — **This command is depricated!** reinitialize the project with specified settings in the tars-config. It is proposed to use this command if you initialize the project with incorrect options. **Attention, files from pages and static folder will be deleted.**
`gulp re-init` — **This command is deprecated!** reinitialize the project with specified settings in the tars-config. It is advised to use this command if you initialize the project with incorrect options. **Attention, files from pages and static folder will be deleted.**

`gulp` or `gulp build` — make project assembly. There not minimized files are connected. Type of assembly depends on the transmitted keys with this command. Available keys:
`gulp` or `gulp build` — build project. Non-minimized files are used by default. Build type depends on command parameters.
Available parameters:

* `--min` – minimized files connected to html.
* `--release` – minimized files connected to html whose names have hash. This mode is useful if you are directly trying to deploy ready markup to the server.
* `--min` – minimized files are connected to html.
* `--release` – minimized files are connected to html whose names have hash. This mode is useful if you are trying to directly deploy ready markup to the server.

`gulp dev` — initialization of builder in development mode. Dev-version of the project is created without any minifications. Also it launches watchers for project files. Available keys:
`gulp dev` — initialize of builder in development mode. Dev-version of the project is created without any minifications. It also launches watchers for project files.
Available parameters:

* `--lr` – initialization livereload (live page reloads with changes in project files), if it is included in the configuration of the project.
* `--tunnel` – initialization project with sharing markup to an external web.
* `--lr` – initialize livereload (live page reloads with changes in project files), if it is included in the configuration of the project.
* `--tunnel` – initialize project with markup sharing to the external web.

The link will be shown in the console. There also will be a link to control panel for devices on which markup was sharing.
The link will be shown in the console. There also will be a link to the control panel for devices to which markup is shared.

`gulp build-dev` — generation of dev-version of the project without watchers.

Keys are available in any mode of assembly:
These parameters are available in any mode of assembly:

* `--ie8` – to include in the build styles for ie8.
* `--ie9` – to include in the build styles for ie9.
Expand All @@ -149,7 +151,7 @@ It is important! All examples in documentation use the default settings.

## Last changes

All recent changes are available at the link: [changelog](/docs/en/changelog.md).
All recent changes are available here: [changelog](/docs/en/changelog.md).

If you have a question you can write in [gitter](https://gitter.im/tars/tars?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) or mail [[email protected]](mailto:[email protected])

Expand Down
2 changes: 1 addition & 1 deletion README_RU.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ TARS — сборщик-фреймворк, включающий в себя н

Ниже перечислена только малая часть особенностей, на самом деле их гораздо больше)

* [Jade](http://jade-lang.com/) или [Handlebars](http://handlebarsjs.com/) на выбор в качестве html-шаблонизатора. Также можно использовать обычный html. Подробности [здесь](/docs/ru/html-processing.md).
* [Jade](http://jade-lang.com/), [Pug](https://pugjs.org/api/getting-started.html) или [Handlebars](http://handlebarsjs.com/) на выбор в качестве html-шаблонизатора. Также можно использовать обычный html. Подробности [здесь](/docs/ru/html-processing.md).
* [Webpack](https://webpack.github.io) (вместе с [Hot Module Replacing](https://webpack.github.io/docs/hot-module-replacement.html)) или простая конкатинация JavaScript-кода в один файл.
* Использование json (а точнее js-объекта, который может быть описан в json) для передачи данных в шаблоны (опционально, но очень крутая штука, которая позволит избавиться от копипаста). Подробнее [тут](/docs/ru/html-processing.md#%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D0%BC%D0%BE%D0%B4%D1%83%D0%BB%D1%8F%D0%BC%D0%B8-%D0%B8-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D0%BC%D0%B8-%D0%B2-handlebars).
* [CLI-утилита](https://github.com/tars/tars-cli) и **автообновление проекта**.
Expand Down
9 changes: 9 additions & 0 deletions docs/en/changelog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ English description | <a href="../ru/changelog.md">Описание на рус

# Changelog

## Version 1.9.0

* gulp-minify-html replaced with на gulp-htmlmin.
* Add templater Pug support.
* You can pass any data to templater by using env var TARS_ENV.
* Bugfix.
* English docs fixup and full update. Thanks to [icehaunter](https://github.com/icehaunter).
* Dependencies update.

## Version 1.8.3

* Fix bug with svg2png in 2.0.0 Use 1.0.2
Expand Down
4 changes: 2 additions & 2 deletions docs/en/css-concat-processing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ Concatenation of styles will be in the following order:
* Components' styles (css is supported)
* Styles of etc.{scss,css}

Also, you can use css-files and not to include them to bundle. There is folder separate-css in static/scss, where you can store all files, which have to be included manually. There is an example of including in any template:
Also, you can use css files not including them into the bundle. There is a folder `separate-css` in `static/scss`, where you can store all files, which have to be included manually. There is an example of including in any template:

```handlebars
<link href="%=static=%css/separate-css/your-file.css" rel="stylesheet" type="text/css">
```

**%=staticPrefix=% prefixe works, but this prefixe is depricated! Use just %=static=% or \_\_static\_\_!**
**%=staticPrefix=% prefix works, but this prefix is deprecated! Use just `%=static=%`!**
Loading

0 comments on commit b970747

Please sign in to comment.