guide WIP [skip ci]

docs/guide/concept-aliases.md

@@ -7,8 +7,7 @@ For example, the alias `@yii` represents the installation path of the Yii framew
 the base URL for the currently running Web application.
 
 
-<a name="defining-aliases"></a>
-Defining Aliases
+Defining Aliases <a name="defining-aliases"></a>
 ----------------
 
 You can call [[Yii::setAlias()]] to define an alias for a given file path or URL. For example,
@@ -50,8 +49,7 @@ return [
 ```
 
 
-<a name="resolving-aliases"></a>
-Resolving Aliases
+Resolving Aliases <a name="resolving-aliases"></a>
 -----------------
 
 You can call [[Yii::getAlias()]] to resolve a root alias into the file path or URL it is representing.
@@ -83,8 +81,7 @@ Yii::getAlias('@foo/bar/file.php');   // displays: /path2/bar/file.php
 If `@foo/bar` is not defined as a root alias, the last statement would display `/path/to/foo/bar/file.php`.
 
 
-<a name="using-aliases"></a>
-Using Aliases
+Using Aliases <a name="using-aliases"></a>
 -------------
 
 Aliases are recognized in many places in Yii without the need of calling [[Yii::getAlias()]] to convert
@@ -103,8 +100,7 @@ $cache = new FileCache([
 Please pay attention to the API documentation to see if a property or method parameter supports aliases.
 
 
-<a name="predefined-aliases"></a>
-Predefined Aliases
+Predefined Aliases <a name="predefined-aliases"></a>
 ------------------
 
 Yii predefines a set of aliases to ease the need of referencing commonly used file paths and URLs.
@@ -122,8 +118,7 @@ while the rest of the aliases are defined in the application constructor when ap
 [configuration](concept-configurations.md).
 
 
-<a name="extension-aliases"></a>
-Extension Aliases
+Extension Aliases <a name="extension-aliases"></a>
 -----------------
 
 An alias is automatically defined for each [extension](structure-extensions.md) that is installed via Composer.

docs/guide/concept-autoloading.md

@@ -10,8 +10,7 @@ The autoloader is installed when you include the `Yii.php` file.
   mind that the content we are describing here applies to autoloading of interfaces and traits as well.
 
 
-<a name="using-yii-autoloader"></a>
-Using the Yii Autoloader
+Using the Yii Autoloader <a name="using-yii-autoloader"></a>
 ------------------------
 
 To make use of the Yii class autoloader, you should follow two simple rules when creating and naming your classes:
@@ -39,8 +38,7 @@ put the front-end classes under the namespace `frontend` while the back-end clas
 allow these classes to be autoloaded by the Yii autoloader.
 
 
-<a name="class-map"></a>
-Class Map
+Class Map <a name="class-map"></a>
 ---------
 
 The Yii class autoloader supports the *class map* feature which maps class names to the corresponding class file paths.
@@ -58,8 +56,7 @@ Yii::$classMap['foo\bar\MyClass'] = 'path/to/MyClass.php';
 [bootstrapping](runtime-bootstrapping.md) process so that the map is ready before your classes are used.
 
 
-<a name="using-other-autoloaders"></a>
-Using Other Autoloaders
+Using Other Autoloaders <a name="using-other-autoloaders"></a>
 -----------------------
 
 Because Yii embraces Composer as a package dependency manager, it is recommended that you also install
@@ -85,8 +82,7 @@ to be autoloadable.
   and include it in your [entry script](structure-entry-scripts.md).
 
 
-<a name="autoloading-extension-classes"></a>
-Autoloading Extension Classes
+Autoloading Extension Classes <a name="autoloading-extension-classes"></a>
 -----------------------------
 
 The Yii autoloader is capable of autoloading [extension](structure-extensions.md) classes. The sole requirement

docs/guide/concept-behaviors.md

@@ -10,8 +10,7 @@ can respond to the [events](concept-events.md) triggered by the component so tha
 code execution of the component.
 
 
-<a name="using-behaviors"></a>
-Using Behaviors
+Using Behaviors <a name="using-behaviors"></a>
 ---------------
 
 To use a behavior, you first need to attach it to a [[yii\base\Component|component]]. We will describe how to
@@ -55,8 +54,7 @@ $behaviors = $component->getBehaviors();
 ```
 
 
-<a name="attaching-behaviors"></a>
-Attaching Behaviors
+Attaching Behaviors <a name="attaching-behaviors"></a>
 -------------------
 
 You can attach a behavior to a [[yii\base\Component|component]] either statically or dynamically. The former
@@ -132,8 +130,7 @@ You may also attach behaviors through [configurations](concept-configurations.md
 refer to the [Configurations](concept-configurations.md#configuration-format) section.
 
 
-<a name="detaching-behaviors"></a>
-Detaching Behaviors
+Detaching Behaviors <a name="detaching-behaviors"></a>
 -------------------
 
 To detach a behavior, you can call [[yii\base\Component::detachBehavior()]] with the name associated with the behavior:
@@ -149,8 +146,7 @@ $component->detachBehaviors();
 ```
 
 
-<a name="defining-behaviors"></a>
-Defining Behaviors
+Defining Behaviors <a name="defining-behaviors"></a>
 ------------------
 
 To define a behavior, create a class by extending from [[yii\base\Behavior]] or its child class. For example,
@@ -235,8 +231,7 @@ function ($event) {
 ```
 
 
-<a name="using-timestamp-behavior"></a>
-Using `TimestampBehavior`
+Using `TimestampBehavior` <a name="using-timestamp-behavior"></a>
 -------------------------
 
 To wrap up, let's take a look at [[yii\behaviors\TimestampBehavior]] - a behavior that supports automatically
@@ -294,8 +289,7 @@ $user->touch('login_time');
 ```
 
 
-<a name="comparison-with-traits"></a>
-Comparison with Traits
+Comparison with Traits <a name="comparison-with-traits"></a>
 ----------------------
 
 While behaviors are similar to [traits](http://www.php.net/traits) in that they both "inject" their
@@ -322,8 +316,7 @@ Name conflict caused by different traits requires you to manually resolve it by
 properties or methods.
 
 
-<a name="pros-for-traits"></a>
-### Pros for Traits
+### Pros for Traits <a name="pros-for-traits"></a>
 
 Traits are much more efficient than behaviors because behaviors are objects which take both time and memory.
 

docs/guide/concept-configurations.md

@@ -35,8 +35,7 @@ Yii::configure($object, $config);
 Note that in this case, the configuration should not contain the `class` element.
 
 
-<a name="configuration-format"></a>
-Configuration Format
+Configuration Format <a name="configuration-format"></a>
 --------------------
 
 The format of a configuration can be formally described as follows,
@@ -80,17 +79,15 @@ Below is an example showing a configuration with property initial values, event
 ```
 
 
-<a name="using-configurations"></a>
-Using Configurations
+Using Configurations <a name="using-configurations"></a>
 --------------------
 
 Configurations are used in many places in Yii. At the beginning of this section, we have shown how to use
 create an object according to a configuration by using [[Yii::createObject()]]. In this subsection, we will
 describe application configurations and widget configurations - two major usages of configurations.
 
 
-<a name="application-configurations"></a>
-### Application Configurations
+### Application Configurations <a name="application-configurations"></a>
 
 Configuration for an [application](structure-applications.md) is probably one of the most complex configurations.
 This is because the [[yii\web\Application|application]] class has a lot of configurable properties and events.
@@ -141,8 +138,7 @@ For more details about configuring the `components` property of an application c
 in the [Applications](structure-applications.md) section and the [Service Locator](concept-service-locator.md) section.
 
 
-<a name="widget-configurations"></a>
-### Widget Configurations
+### Widget Configurations <a name="widget-configurations"></a>
 
 When using [widgets](structure-widgets.md), you often need to use configurations to customize the widget properties.
 Both of the [[yii\base\Widget::widget()]] and [[yii\base\Widget::beginWidget()]] methods can be used to create
@@ -167,8 +163,7 @@ The `items` property is also configured with menu items to be displayed.
 Note that because the class name is already given, the configuration array should NOT have the `class` key.
 
 
-<a name="configuration-files"></a>
-Configuration Files
+Configuration Files <a name="configuration-files"></a>
 -------------------
 
 When a configuration is very complex, a common practice is to store it in one or multiple PHP files, known as
@@ -222,8 +217,7 @@ $config = require('path/to/web.php');
 ```
 
 
-<a name="default-configurations"></a>
-Default Configurations
+Default Configurations <a name="default-configurations"></a>
 ----------------------
 
 The [[Yii::createObject()]] method is implemented based on a [dependency injection container](concept-di-container.md).
@@ -244,8 +238,7 @@ Without using default configurations, you would have to configure `maxButtonCoun
 link pagers.
 
 
-<a name="environment-constants"></a>
-Environment Constants
+Environment Constants <a name="environment-constants"></a>
 ---------------------
 
 Configurations often vary according to the environment in which an application runs. For example,

docs/guide/concept-di-container.md

@@ -6,8 +6,7 @@ all their dependent objects. [Martin's article](http://martinfowler.com/articles
 explained why DI container is useful. Here we will mainly explain the usage of the DI container provided by Yii.
 
 
-<a name="dependency-injection"></a>
-Dependency Injection
+Dependency Injection <a name="dependency-injection"></a>
 --------------------
 
 Yii provides the DI container feature through the class [[yii\di\Container]]. It supports the following kinds of
@@ -18,8 +17,7 @@ dependency injection:
 * PHP callable injection.
 
 
-<a name="constructor-injection"></a>
-### Constructor Injection
+### Constructor Injection <a name="constructor-injection"></a>
 
 The DI container supports constructor injection with the help of type hints for constructor parameters.
 The type hints tell the container which classes or interfaces are dependent when it is used to create a new object.
@@ -41,8 +39,7 @@ $foo = new Foo($bar);
 ```
 
 
-<a name="setter-and-property-injection"></a>
-### Setter and Property Injection
+### Setter and Property Injection <a name="setter-and-property-injection"></a>
 
 Setter and property injection is supported through [configurations](concept-configurations.md).
 When registering a dependency or when creating a new object, you can provide a configuration which
@@ -76,8 +73,7 @@ $container->get('Foo', [], [
 ```
 
 
-<a name="php-callable-injection"></a>
-### PHP Callable Injection
+### PHP Callable Injection <a name="php-callable-injection"></a>
 
 In this case, the container will use a registered PHP callable to build new instances of a class.
 The callable is responsible to resolve the dependencies and inject them appropriately to the newly
@@ -92,8 +88,7 @@ $foo = $container->get('Foo');
 ```
 
 
-<a name="registering-dependencies"></a>
-Registering Dependencies
+Registering Dependencies <a name="registering-dependencies"></a>
 ------------------------
 
 You can use [[yii\di\Container::set()]] to register dependencies. The registration requires a dependency name
@@ -162,8 +157,7 @@ $container->setSingleton('yii\db\Connection', [
 ```
 
 
-<a name="resolving-dependencies"></a>
-Resolving Dependencies
+Resolving Dependencies <a name="resolving-dependencies"></a>
 ----------------------
 
 Once you have registered dependencies, you can use the DI container to create new objects,
@@ -252,9 +246,8 @@ $lister = new UserLister($finder);
 ```
 
 
-<a name="practical-usages"></a>
-Practical Usages
-----------------
+Practical Usage <a name="practical-usage"></a>
+---------------
 
 Yii creates a DI container when you include the `Yii.php` file in the [entry script](structure-entry-scripts.md)
 of your application. The DI container is accessible via [[Yii::$container]]. When you call [[Yii::createObject()]],
@@ -315,8 +308,7 @@ Now if you access the controller again, an instance of `app\components\BookingSe
 created and injected as the 3rd parameter to the controller's constructor.
 
 
-<a name="when-to-register-dependencies"></a>
-When to Register Dependencies
+When to Register Dependencies <a name="when-to-register-dependencies"></a>
 -----------------------------
 
 Because dependencies are needed when new objects are being created, their registration should be done
@@ -328,8 +320,7 @@ as early as possible. The followings are the recommended practices:
   in the bootstrap class of the extension.
 
 
-<a name="summary"></a>
-Summary
+Summary <a name="summary"></a>
 -------
 
 Both dependency injection and [service locator](concept-service-locator.md) are popular design patterns

docs/guide/concept-events.md

@@ -10,8 +10,7 @@ Yii introduces a base class called [[yii\base\Component]] to support events. If
 events, it should extend from [[yii\base\Component]] or its child class.
 
 
-<a name="triggering-events"></a>
-Triggering Events
+Triggering Events <a name="triggering-events"></a>
 -----------------
 
 Events are triggered by calling the [[yii\base\Component::trigger()]] method. The method requires an *event name*
@@ -77,8 +76,7 @@ When the [[yii\base\Component::trigger()]] method is called, it will call handle
 the named event.
 
 
-<a name="event-handlers"></a>
-Event Handlers
+Event Handlers <a name="event-handlers"></a>
 --------------
 
 An event handler is a [PHP callback](http://www.php.net/manual/en/language.types.callable.php) that gets executed
@@ -104,8 +102,7 @@ Through the `$event` parameter, an event handler may get the following informati
 - [[yii\base\Event::data|custom data]]: the data that is provided when attaching the event handler (to be explained shortly).
 
 
-<a name="attaching-event-handlers"></a>
-Attaching Event Handlers
+Attaching Event Handlers <a name="attaching-event-handlers"></a>
 ------------------------
 
 You can attach a handler to an event by calling the [[yii\base\Component::on()]] method. For example,
@@ -166,8 +163,7 @@ $foo->on(Foo::EVENT_HELLO, function ($event) {
 ```
 
 
-<a name="detaching-event-handlers"></a>
-Detaching Event Handlers
+Detaching Event Handlers <a name="detaching-event-handlers"></a>
 ------------------------
 
 To detach a handler from an event, call the [[yii\base\Component::off()]] method. For example,
@@ -197,8 +193,7 @@ $foo->off(Foo::EVENT_HELLO);
 ```
 
 
-<a name="class-level-event-handlers"></a>
-Class-Level Event Handlers
+Class-Level Event Handlers <a name="class-level-event-handlers"></a>
 --------------------------
 
 In the above subsections, we have described how to attach a handler to an event at *instance level*.
@@ -256,8 +251,7 @@ Event::off(Foo::className(), Foo::EVENT_HELLO);
 ```
 
 
-<a name="global-events"></a>
-Global Events
+Global Events <a name="global-events"></a>
 -------------
 
 The so-called *global event* is actually a trick based on the event mechanism described above.