Merge pull request #288 from vithar/docs-anchors

Docs: custom anchors replaced with github-generated, links to bem.info replaced with links to github, BEM-XJST -> bem-xjst

docs/en/1-about.md

@@ -1,12 +1,15 @@
-# About BEM-XJST
+# About bem-xjst
 
-## What is BEM-XJST?
-bem-xjst is a template engine for web development using the BEM methodology. Starting with version 5.0.0, it contains two engines:
+## What is bem-xjst?
 
-1. BEMHTML — for transforming BEMJSON to HTML.
-1. BEMTREE — for transforming BEMJSON with data to BEMJSON with a BEM tree for further transformation using BEMHTML.
+bem-xjst is a template engine for web development using the BEM methodology.
 
-The template engine is based on the declarative principles of [XSLT](https://www.w3.org/TR/xslt) (eXtensible Stylesheet Language Transformations).. The name XJST (eXtensible JavaScript Transformations) was also created as an analogy to XSLT.
+It contains two engines:
+
+1. **BEMHTML** — for transforming BEMJSON to HTML.
+1. **BEMTREE** — for transforming BEMJSON with data to BEMJSON with a BEM tree for further transformation using BEMHTML.
+
+The template engine is based on the declarative principles of [XSLT](https://www.w3.org/TR/xslt) (eXtensible Stylesheet Language Transformations). The name XJST (eXtensible JavaScript Transformations) was also created as an analogy to XSLT.
 
 Before using the template engine, you should review:
 
@@ -15,16 +18,16 @@ Before using the template engine, you should review:
 1. [Processes for selecting and applying templates](7-runtime.md)
 
 ## Features
+
 1. Templates are extensible: they can be redefined or extended.
-1. Templates are written using [pattern matching](7-runtime.md#matching) for the values and structure of input data.
+1. Templates are written using [pattern matching](7-runtime.md#how-templates-are-selected-and-applied) for the values and structure of input data.
 1. Traverses input data by default.
 1. Built-in rendering behavior is used by default, even if the user didn’t add templates.
 1. Written in JavaScript, so the entire JavaScript infrastructure is available for checking code quality and conforming to best practices.
 1. Doesn’t require compiling templates.
 1. API provided for adding templates in runtime.
 1. Runs on a server and client.
 
-
 ***
 
 Read next: [Quick Start](2-quick-start.md)

docs/en/2-quick-start.md

@@ -4,12 +4,17 @@
 
 To use bem-xjst, you need [Node.js](https://nodejs.org/) v0.10 or later, and [npm](https://www.npmjs.com/).
 
-Install: `npm install bem-xjst`
+Install:
+
+```bash
+npm install bem-xjst
+```
 
 ## Basic example
 
 ```js
 var bemxjst = require('bem-xjst');
+
 // bem-xjst contains two engines, BEMHTML and BEMTREE (starting from v5.0.0)
 // Choose the BEMHTML engine
 var bemhtml = bemxjst.bemhtml;
@@ -30,11 +35,15 @@ var html = templates.apply(bemjson);
 ```
 
 The resulting `html` contains this string:
+
 ```html
 <span class="text">First</span><span class="text">Second</span>
 ```
+
 ***
 
 [Online demo](https://bem.github.io/bem-xjst/).
 
+***
+
 Read next: [API](3-api.md)

docs/en/3-api.md

@@ -1,18 +1,19 @@
 # API
 
-* [Choosing an engine, compiling and applying templates](#choose-engine)
-* [Adding templates](#add-templates)
+* [Choosing an engine, compiling and applying templates](#choosing-an-engine-compiling-and-applying-templates)
+* [Adding templates](#adding-templates)
 * [Settings](#settings)
+ - [Delimiters in names of BEM entities](#delimiters-in-names-of-bem-entities)
+ - [Support JS-instances for elements (bem-core v4+)](#support-js-instances-for-elements-bem-core-v4)
+ - [XHTML option](#xhtml-option)
  - [Escaping](#escaping)
- - [Delimiters in names of BEM entities](#naming)
- - [Support JS-instances for elements (bem-core v4+)](#elemjs)
- - [XHTML option](#xhtml)
- - [Extending BEMContext](#bemcontext)
-* [Bundling](#bundle)
+ - [Extending BEMContext](#extending-bemcontext)
+* [Bundling](#bundling)
 
-## <a name="choose-engine"></a>Choosing an engine, compiling and applying templates
+## Choosing an engine, compiling and applying templates
 
 ### BEMHTML engine
+
 ```js
 var bemxjst = require('bem-xjst');
 var bemhtml = bemxjst.bemhtml;
@@ -30,11 +31,13 @@ var html = templates.apply(bemjson);
 ```
 
 The resulting `html` contains the string:
+
 ```html
 <q class="quote">I came, I saw, I templated.</q>
 ```
 
 ### BEMTREE engine
+
 ```js
 var bemxjst = require('bem-xjst');
 var bemtree = bemxjst.bemtree;
@@ -75,10 +78,10 @@ var result = templates.apply(bemjson);
 ]
 ```
 
-
-## <a name="add-templates"></a>Adding templates
+## Adding templates
 
 To add templates to the `templates` instance, use the `compile` method.
+
 ```js
 var bemxjst = require('bem-xjst');
 
@@ -103,73 +106,11 @@ html = templates.apply(bemjson);
 // html: '<h2 class="header">Documentation</h2>'
 ```
 
-If you need to [bundle](https://en.bem.info/method/build/#build-results) all the templates, the most efficient way is to use the [generate](#generate) method.
+If you need to [bundle](https://en.bem.info/methodology/build/#build-results) all the templates, the most efficient way is to use the [generate](#bundling) method.
 
-## <a name="settings"></a>Settings
+## Settings
 
-### <a name="escaping"></a>Escaping
-
-You can set `escapeContent` option to `true` to escape string values of `content` field with [`xmlEscape`](6-templates-context.md#xmlescape).
-
-Example:
-
-```js
-var bemxjst = require('bem-xjst');
-var templates = bemxjst.bemhtml.compile(function() {
- // In this example we will add no templates.
- // Default behaviour is used for HTML rendering.
- }, {
- // Turn on content escaping
- escapeContent: true
- });
-
-var bemjson = {
- block: 'danger',
- // Danger UGC content
- content: '&nbsp;<script src="alert()"></script>'
-};
-
-var html = templates.apply(bemjson);
-```
-
-Result:
-```html
-<div class="danger">&amp;nbsp;&lt;script src="alert()"&gt;&lt;/script&gt;</div>
-```
-
-If you want avoid escaping in content [use special value](4-data#content): `{ html: '…' }`.
-
-Example:
-
-```js
-var bemxjst = require('bem-xjst');
-var templates = bemxjst.bemhtml.compile(function() {
- // In this example we will add no templates.
- // Default behaviour is used for HTML rendering.
- }, {
- // Turn on content escaping
- escapeContent: true
- });
-
-var bemjson = {
- block: 'trusted',
- // Trusted and safe content
- content: {
- html: 'I <3 you!'
- }
-};
-
-var html = templates.apply(bemjson);
-```
-
-In this case `content.html` will be rendered as is:
-```html
-<div class="trusted">I <3 you!</div>
-```
-
-Notice that in `content.html` expected only string type.
-
-### <a name="naming"></a>Delimiters in names of BEM entities
+### Delimiters in names of BEM entities
 
 ```js
 var bemxjst = require('bem-xjst');
@@ -195,16 +136,18 @@ var bemjson = {
 
 var html = templates.apply(bemjson);
 ```
+
 The resulting `html` contains the string:
+
 ```html
 <div class="page page_theme_gray"><div class="page__head page__head_type_short"></div></div>
 ```
-You can find more information about [naming conventions](https://en.bem.info/method/naming-convention/) on bem.info.
 
+You can find more information in [naming conventions](https://en.bem.info/methodology/naming-convention/) article.
 
-### <a name="elemjs"></a>Support JS-instances for elements (bem-core v4+)
+### Support JS-instances for elements (bem-core v4+)
 
-bem-xjst have `elemJsInstances` option for support JS instances for elems (bem-core v4+).
+bem-xjst have `elemJsInstances` option for support JS instances for elems ([bem-core](https://en.bem.info/libs/bem-core/) v4+).
 
 ```js
 var bemxjst = require('bem-xjst');
@@ -226,19 +169,20 @@ var html = templates.apply(bemjson);
 ```
 
 Result with v6.2.x:
+
 ```html
 <div class="b__e" data-bem='{"b__e":{}}'></div>
 ```
 
 Result with v6.3.0:
+
 ```html
 <div class="b__e i-bem" data-bem='{"b__e":{}}'></div>
 ```
 
 Notice that `i-bem` was added.
 
-
-### <a name="xhtml"></a>XHTML option
+### XHTML option
 
 `xhtml` option allow you to ommit closing slash in void HTML elements (only have a start tag).
 
@@ -261,21 +205,88 @@ var html = templates.apply(bemjson);
 ```
 
 Result:
+
 ```html
 <br>
 ```
 
-### <a name="bemcontext"></a>Extending `BEMContext`
+### Escaping
+
+You can set `escapeContent` option to `true` to escape string values of `content` field with [`xmlEscape`](6-templates-context.md#xmlescape).
+
+Example:
+
+```js
+var bemxjst = require('bem-xjst');
+var templates = bemxjst.bemhtml.compile(function() {
+ // In this example we will add no templates.
+ // Default behaviour is used for HTML rendering.
+ }, {
+ // Turn on content escaping
+ escapeContent: true
+ });
+
+var bemjson = {
+ block: 'danger',
+ // Danger UGC content
+ content: '&nbsp;<script src="alert()"></script>'
+};
+
+var html = templates.apply(bemjson);
+```
+
+Result:
+
+```html
+<div class="danger">&amp;nbsp;&lt;script src="alert()"&gt;&lt;/script&gt;</div>
+```
+
+If you want avoid escaping in content [use special value](4-data#content): `{ html: '…' }`.
+
+Example:
+
+```js
+var bemxjst = require('bem-xjst');
+var templates = bemxjst.bemhtml.compile(function() {
+ // In this example we will add no templates.
+ // Default behaviour is used for HTML rendering.
+ }, {
+ // Turn on content escaping
+ escapeContent: true
+ });
+
+var bemjson = {
+ block: 'trusted',
+ // Trusted and safe content
+ content: {
+ html: 'I <3 you!'
+ }
+};
+
+var html = templates.apply(bemjson);
+```
+
+In this case `content.html` will be rendered as is:
+
+```html
+<div class="trusted">I <3 you!</div>
+```
+
+Notice that in `content.html` expected only string type.
+
+### Extending BEMContext
 
 You can extend `BEMContext` in order to use user-defined functions in the template body.
 
 ```js
 var bemxjst = require('bem-xjst');
 var templates = bemxjst.bemhtml.compile('');
+
 // Extend the context prototype
 templates.BEMContext.prototype.hi = function(name) {
  return 'Hello, ' + username;
 };
+
 // Add templates
 templates.compile(function() {
  block('b').content()(function() {
@@ -291,14 +302,16 @@ var html = templates.apply(bemjson);
 ```
 
 The resulting `html` contains the string:
+
 ```html
 <div class="b">Hello, templates</div>
 ```
 
+## Bundling
 
-## <a name="bundle"></a>Bundling
+The `generate` method generates JavaScript code that can be passed and run in the
+browser to get the `templates` object.
 
-The `generate` method generates JavaScript code that can be passed and run in the browser to get the `templates` object. Example:
 ```js
 var bemxjst = require('bem-xjst');
 var bundle = bemxjst.bemhtml.generate(function() {