first take

CHANGELOG.md

@@ -0,0 +1,17 @@
+# v1.0.2
+## 06/22/2015
+
+1. [](#new)
+    * Added sub-topic pages
+
+# v1.0.1
+## 06/17/2015
+
+1. [](#new)
+    * Added screenshot
+
+# v1.0.0
+## 06/17/2015
+
+1. [](#new)
+    * ChangeLog started...

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Grav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,59 @@
+# RTFM Skeleton
+
+![RTFM Screenshot](assets/rtfm-screenshot.png)
+
+This is a sample skeleton site that mimics the official Grav documentation: http://learn.getgrav.org.  This skeleton uses the [learn2 theme](https://github.com/getgrav/grav-theme-learn2)
+
+# Features
+
+* Lightweight and minimal for optimal performance
+* Fully responsive with off-page mobile navigation
+* SCSS based CSS source files for easy customization
+* Built specifically for providing easy to read documentation
+* [Font Awesome](http://fontawesome.io/) icon support
+* Viewed page tracking
+* Integrated support for documentation content sourced/maintained via GitHub
+
+>> If you want more information about using Grav with GitHub, check out [part 1](http://getgrav.org/blog/developing-with-github-part-1) and [part 2](http://getgrav.org/blog/developing-with-github-part-2) of our guide called *Grav Development with Github*.
+
+# Supported Page Templates
+
+* "Docs" template
+* "Chapter" template
+* Error view template
+
+# Configuration
+
+```
+top_level_version: false
+home_url:
+github:
+    enabled: true
+    position: top
+    tree: https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/
+    commits: https://github.com/getgrav/grav-skeleton-rtfm-site/commits/develop/
+```
+
+| Setting           | Child Setting | Description                                                                                                            |
+| :-----            | :-----        | :-----                                                                                                                 |
+| top_level_version |               | When set to `true`, displays level icons and numbered lists.                                                           |
+| home_url          |               | Enables you to enter a different URL link from the logo (ex: http://google.com)                                        |
+| github            | enabled       | Can be set to `true` or `false`. When set to `true`, it generates the **Edit this page** link to GitHub for each page. |
+| github            | position      | Sets the position for the GitHub edit link. Can be set to `top` or `bottom`.                                           |
+| github            | tree          | Sets the tree by which your site's content is based. Generally the repo your site's content is pulled from.            |
+| github            | commits       | Sets the link to the commits page for the site's content repo.                                                         |
+
+## Basic Setup for a New Grav Site
+
+The simplest way to install the learn2 theme with RTFM content for Grav is to download and install the RTFM Skeleton package:
+
+1. [Download RTFM Skeleton](http://getgrav.org/downloads/skeletons#extras)
+2. Unzip the package into your web root folder.
+3. Point your browser at the folder.
+4. Job done!
+
+**TIP:** Check out the [general Grav Installation Instructions](http://learn.getgrav.org/basics/installation) for more details on this process.
+
+---
+
+

blueprints.yaml

@@ -0,0 +1,13 @@
+name: RTFM Site
+version: 1.0.2
+description: "RTFM is a sample documentation site using the `learn2` theme.  This skeleton is used as the basis for the Grav official documentation: http://learn.getgrav.org"
+icon: book
+author:
+  name: Team Grav
+  email: [email protected]
+  url: http://getgrav.org
+homepage: https://github.com/getgrav/grav-skeleton-rtfm-site
+demo: http://demo.getgrav.org/rtfm-skeleton
+keywords: rtfm, skeleton, documentation, docs
+bugs: https://github.com/getgrav/grav-skeleton-rtfm-site/issues
+license: MIT

config/plugins/anchors.yaml

@@ -0,0 +1 @@
+selectors: '#body h2, #body h3, #body h4, #body h5'

config/plugins/highlight.yaml

@@ -0,0 +1 @@
+theme: learn

config/plugins/simplesearch.yaml

@@ -0,0 +1,6 @@
+enabled: true
+built_in_css: false
+route: /search
+template: simplesearch_results
+filters:
+    category: docs

config/site.yaml

@@ -0,0 +1,8 @@
+title: Select2 - The jQuery replacement for select boxes 
+metadata:
+    description: Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and pagination (infinite scrolling) of results.
+
+taxonomies: [category,tag]
+summary:
+  size: 300
+

config/system.yaml

@@ -0,0 +1,35 @@
+home:
+  alias: '/getting-started'
+
+pages:
+  theme: site
+  markdown_extra: true
+  process:
+    markdown: true
+    twig: false
+
+cache:
+  enabled: true
+  check:
+    method: file
+  driver: auto
+  prefix: 'g'
+
+twig:
+  cache: true
+  debug: false
+  auto_reload: true
+  autoescape: false
+
+assets:
+  css_pipeline: true
+  css_minify: true
+  css_rewrite: true
+  js_pipeline: true
+  js_minify: true
+
+debugger:
+  enabled: false
+  twig: true
+  shutdown:
+    close_connection: true

localhost/config/security.yaml

@@ -0,0 +1 @@
+salt: dc7HfDXRG0WT48

localhost/config/system.yaml

@@ -0,0 +1,10 @@
+assets:
+  css_pipeline: false
+  js_pipeline: false
+
+twig:
+  cache: true
+  debug: true
+
+debugger:
+  enabled: false

pages/01.getting-started/01.installation/docs.md

@@ -0,0 +1,67 @@
+---
+title: Installation
+taxonomy:
+    category: docs
+---
+
+In order to use Select2, you must include the JavaScript and CSS file on
+your website. You can get these files built for you from many different
+locations.
+
+## Using Select2 from a CDN
+
+Select2 is hosted on both the
+<a href="https://cdnjs.com/libraries/select2">cdnjs</a> and
+<a href="https://www.jsdelivr.com/#!select2">jsDelivr</a> CDNs, allowing
+you to quickly include Select2 on your website.
+
+### Include the assets
+
+Include the following lines of code in the <code>&lt;head&gt;</code>
+section of your HTML.
+
+```
+<link href="https://cdnjs.cloudflare.com/ajax/libs/select2/4.0.3/css/select2.min.css" rel="stylesheet" />
+<script src="https://cdnjs.cloudflare.com/ajax/libs/select2/4.0.3/js/select2.min.js"></script>
+```
+
+>>> <i class="fa fa-info-circle"></i> Immediately following a new release, it takes some time for CDNs to
+  catch up and get the new versions live on the CDN.
+
+### Initialize Select2
+
+Initialize Select2 on the <code>&lt;select&gt;</code> element that you want to make awesome.
+
+```
+<script type="text/javascript">
+    $('select').select2();
+</script>
+```
+
+### Read the docs
+
+Check out the <a href="/examples">examples chapter</a> to start using the additional features of Select2.
+
+## Downloading the code locally
+
+In some situations, you can't use Select2 from a CDN and you must include the files through your own static file servers.
+
+### Download the code
+
+<a href="https://github.com/select2/select2/tags">
+  Download the code
+</a>
+from GitHub and copy the `dist` directory to your project.
+
+### Include the assets
+
+Include the following lines of code in the `<head>` section of your HTML.
+
+```
+<link href="path/to/select2.min.css" rel="stylesheet" />
+<script src="path/to/select2.min.js"></script>
+```
+
+### Read the docs
+
+Check out the <a href="/examples">examples chapter</a> to start using the additional features of Select2.

pages/01.getting-started/02.basic-usage/docs.md

@@ -0,0 +1,95 @@
+---
+title: Basic Usage
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+## Single select boxes
+
+Select2 was designed to be a replacement for the standard `<select>` box that is displayed by the browser.  By default it supports all options and operations that are available in a standard select box, but with added flexibility.
+
+Select2 can take a regular select box like this...
+
+<select class="js-states form-control"></select>
+
+and turn it into this...
+
+<div class="s2-example">
+    <select class="js-example-basic-single js-states form-control"></select>
+</div>
+
+```
+<select class="js-example-basic-single">
+  <option value="AL">Alabama</option>
+    ...
+  <option value="WY">Wyoming</option>
+</select>
+```
+
+<script type="text/javascript" class="js-code-example-basic-single">
+$(document).ready(function() {
+  $(".js-example-basic-single").select2();
+});
+</script>
+
+Select2 will register itself as a jQuery function if you use any of the distribution builds, so you can call `.select2()` on any jQuery selector where you would like to initialize Select2.
+
+```
+$('.js-example-basic-single').select2();
+```
+
+## Multi-select boxes (pillbox)
+
+Select2 also supports multi-value select boxes. The select below is declared with the `multiple` attribute.
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-basic-multiple js-states form-control" multiple="multiple"></select>
+  </p>
+</div>
+
+```
+<script type="text/javascript">
+$(".js-example-basic-multiple").select2();
+</script>
+
+<select class="js-example-basic-multiple" multiple="multiple">
+  <option value="AL">Alabama</option>
+    ...
+  <option value="WY">Wyoming</option>
+</select>
+```
+
+<script type="text/javascript">
+  $.fn.select2.amd.require([
+    "select2/core",
+    "select2/utils"
+  ], function (Select2, Utils, oldMatcher) {
+    var $basicSingle = $(".js-example-basic-single");
+    var $basicMultiple = $(".js-example-basic-multiple");
+
+    $.fn.select2.defaults.set("width", "100%");
+
+    $basicSingle.select2();
+    $basicMultiple.select2();
+
+    function formatState (state) {
+      if (!state.id) {
+        return state.text;
+      }
+      var $state = $(
+        '<span>' +
+          '<img src="vendor/images/flags/' +
+            state.element.value.toLowerCase() +
+          '.png" class="img-flag" /> ' +
+          state.text +
+        '</span>'
+      );
+      return $state;
+    };
+  });
+
+</script>

pages/01.getting-started/03.builds-and-modules/docs.md

@@ -0,0 +1,63 @@
+---
+title: Builds and modules
+taxonomy:
+    category: docs
+---
+
+## The different Select2 builds
+
+Select2 provides multiple builds that are tailored to different
+environments where it is going to be used. If you think you need to use
+Select2 in a nonstandard environment, like when you are using AMD, you
+should read over the list below.
+
+<table class="table table-bordered table-striped">
+  <thead>
+    <tr>
+      <th>Build name</th>
+      <th>When you should use it</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id="builds-standard">
+      <td>
+        Standard (<code>select2.js</code> / <code>select2.min.js</code>)
+      </td>
+      <td>
+        This is the build that most people should be using for Select2. It
+        includes the most commonly used features.
+      </td>
+    </tr>
+    <tr id="builds-full">
+      <td>
+        Full (<code>select2.full.js</code> / <code>select2.full.min.js</code>)
+      </td>
+      <td>
+        You should only use this build if you need the additional features
+        from Select2, like the
+        <a href="options.html#compatibility">compatibility modules</a> or
+        recommended includes like
+        <a href="https://github.com/jquery/jquery-mousewheel">jquery.mousewheel</a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Using Select2 with AMD or CommonJS loaders
+
+Select2 should work with most AMD- or CommonJS-compliant module loaders, including <a href="http://requirejs.org/">RequireJS</a> and <a href="https://github.com/jrburke/almond">almond</a>. Select2 ships with a modified version of the <a href="https://github.com/umdjs/umd/blob/f208d385768ed30cd0025d5415997075345cd1c0/templates/jqueryPlugin.js">UMD jQuery template</a> that supports both CommonJS and AMD environments.
+
+### Configuration
+
+For most AMD and CommonJS setups, the location of the data files used by Select2 will be automatically determined and handled without you needing to do anything.
+
+If you are using Select2 in a build environment where preexisting module names are changed during a build step, Select2 may not be able to find optional dependencies or language files. You can manually set the prefixes to use for these files using the `amdBase` and `amdLanguageBase` options.
+
+```
+$.fn.select2.defaults.set('amdBase', 'select2/');
+$.fn.select2.defaults.set('amdLanguageBase', 'select2/i18n/');
+```
+
+Select2 internally uses AMD and the r.js build tool to build the files located in the `dist` folder. These are built using the files in the `src` folder, so _you can_ just point your modules to the Select2 source and load in `jquery.select2` or `select2/core` when you want to use Select2. The files located in the `dist` folder are also AMD-compatible, so you can point to that file if you want to load in all of the default Select2 modules.
+
+>>> Due to [a bug in older versions](https://github.com/jrburke/requirejs/issues/1342) of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery.  By upgrading to version 2.1.18 or higher of the r.js build tool, you will be able to fix the issue.

pages/01.getting-started/chapter.md

@@ -0,0 +1,73 @@
+---
+title: Getting Started
+taxonomy:
+    category: docs
+---
+
+![Select2 logo](/images/logo.png)
+
+# Select2
+
+The jQuery replacement for select boxes 
+
+Select2 gives you a customizable select box with support for searching, tagging, remote data sets, infinite scrolling, and many other highly used options.
+
+<div class="s2-docs-featurette">
+    <div class="grid">
+      <div class="size-1-3 size-tablet-1-2">
+          <i class="fa fa-language fa-4x"></i>
+          <h4>In your language</h4>
+          <p>
+            Select2 comes with support for
+            <a href="examples.html#rtl">RTL environments</a>,
+            <a href="examples.html#diacritics">searching with diacritics</a> and
+            <a href="examples.html#language">over 40 languages</a> built-in.
+          </p>
+      </div>
+
+      <div class="size-1-3 size-tablet-1-2">
+          <i class="fa fa-database fa-4x"></i>
+          <h4>Remote data support</h4>
+          <p>
+            <a href="examples.html#data-ajax">Using AJAX</a> you can efficiently
+            search large lists of items.
+          </p>
+      </div>
+
+      <div class="size-1-3 size-tablet-1-2">
+          <i class="fa fa-paint-brush fa-4x"></i>
+          <h4>Theming</h4>
+          <p>
+            Fully skinnable, CSS built with Sass and an
+            <a href="https://github.com/select2/select2-bootstrap-theme">optional theme for Bootstrap 3</a>.
+          </p>
+      </div>
+    </div>
+
+    <div class="grid">
+      <div class="size-1-3 size-tablet-1-2">
+        <i class="fa fa-plug fa-4x"></i>
+        <h4>Fully extensible</h4>
+        <p>
+          The <a href="announcements-4.0.html#plugin-system">plugin system</a>
+          allows you to easily customize Select2 to work exactly how you want it
+          to.
+        </p>
+      </div>
+
+      <div class="size-1-3 size-tablet-1-2">
+        <i class="fa fa-tag fa-4x"></i>
+        <h4>Dynamic item creation</h4>
+        <p>
+          Allow users to type in a new option and
+          <a href="examples.html#tags">add it on the fly</a>.
+        </p>
+      </div>
+
+      <div class="size-1-3 size-tablet-1-2">
+        <i class="fa fa-html5 fa-4x"></i>
+        <h4>Full browser support</h4>
+        <p>Support for both modern and legacy browsers is built-in, even including Internet Explorer 8.</p>
+      </div>
+    </div>
+</div>

pages/02.configuration/01.initializing/01.data-attributes/docs.md

@@ -0,0 +1,61 @@
+---
+title: Via data-* attributes
+taxonomy:
+    category: docs
+---
+
+It is recommended that you declare your configuration options by [passing in an object](/options/initializing) when initializing Select2.  However, you may also define your configuration options by using the HTML5 `data-*` attributes, which will override any options set when initializing Select2 and any [defaults](/options/initializing/defaults).
+
+```
+<select data-placeholder="Select a state">
+  <option value="AL">Alabama</option>
+    ...
+  <option value="WY">Wyoming</option>
+</select>
+```
+
+## Nested (subkey) options
+
+Sometimes, you have options that are nested under a top-level option.  For example, the options under the `ajax` option:
+
+```
+$(".js-example-data-ajax").select2({
+  ajax: {
+    url: "http://example.org/api/test",
+    cache: false
+  }
+});
+```
+
+To write these options as `data-*` attributes, each level of nesting should be separated by two dashes (`--`):
+
+```
+<select data-ajax--url="http://example.org/api/test" data-ajax--cache="true">
+    ...
+</select>
+```
+
+The value of the option is subject to jQuery's <a href="https://api.jquery.com/data/#data-html5">parsing rules</a> for HTML5 data attributes.
+
+>>> Due to <a href="https://github.com/jquery/jquery/issues/2070">a jQuery bug</a>, nested options using <code>data-*</code> attributes <a href="https://github.com/select2/select2/issues/2969">do not work in jQuery 1.x</a>.
+
+## `camelCase` options
+
+HTML data attributes are case-insensitive, so any options which contain capital letters will be parsed as if they were all lowercase. Because Select2 has many options which are camelCase, where words are separated by uppercase letters, you must write these options out with dashes instead. So an option that would normally be called <code>allowClear</code> should instead be defined as `allow-clear`.
+
+This means that if you declare your <code>&lt;select&gt;</code> tag as...
+```
+<select data-tags="true" data-placeholder="Select an option" data-allow-clear="true">
+    ...
+</select>
+```
+
+Will be interpreted the same as initializing Select2 as...
+
+```
+$("select").select2({
+  tags: "true",
+  placeholder: "Select an option",
+  allowClear: true
+});
+```

pages/02.configuration/01.initializing/02.defaults/docs.md

@@ -0,0 +1,31 @@
+---
+title: Global defaults
+taxonomy:
+    category: docs
+---
+
+In some cases, you need to set the default options for all instances of Select2 in your web application. This is especially useful when you are migrating from past versions of Select2, or you are using non-standard options <a href="#amd">like custom AMD builds</a>. Select2 exposes the default options through <code>$.fn.select2.defaults</code>, which allows you to set them globally.
+
+When setting options globally, any past defaults that have been set will be overridden. Default options are only used when an option is requested that has not been set during initialization.
+
+You can set default options by calling `$.fn.select2.defaults.set("key", "value")`.  For example:
+
+```
+$.fn.select2.defaults.set("theme", "classic");
+```
+
+## Nested options
+
+To set a default values for cache, use the same notation used for <a href="#data-attributes">HTML <code>data-*</code> attributes</a>.  Two dashes (`--`) will be replaced by a level of nesting, and a single dash (`-`) will convert the key to a camelCase string:
+
+```
+$.fn.select2.defaults.set("ajax--cache", false);
+```
+
+## Resetting default options
+
+You can reset the default options to their initial values by calling
+
+```
+$.fn.select2.defaults.reset();
+```

pages/02.configuration/01.initializing/docs.md

@@ -0,0 +1,14 @@
+---
+title: Initializing
+taxonomy:
+    category: docs
+---
+
+
+To configure custom options, simply pass an object containing all of the options with which you would like to initialize Select2, in your call to `.select2()`:
+
+```
+$('.js-example-basic-single').select2({
+  placeholder: 'Select an option'
+});
+```

pages/02.configuration/02.deprecated/docs.md

@@ -0,0 +1,210 @@
+---
+title: Deprecated options
+taxonomy:
+    category: docs
+---
+
+<section>
+  <p>
+    Select2 offers limited backwards compatibility with the previously 3.5.x
+    release line, allowing people more efficiently transfer across releases
+    and get the latest features. For many of the larger changes, such as the
+    change in how custom data adapters work, compatibility modules were
+    created that will be used to assist in the upgrade process. It is not
+    recommended to rely on these compatibility modules, as they will not
+    always exist, but they make upgrading easier for major changes.
+  </p>
+
+  <p>
+    <strong>The compatibility modules are only included in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2</strong>. These files end in <code>.full.js</code>, and the
+    compatibility modules are prefixed with <code>select2/compat</code>.
+  </p>
+</section>
+
+<section>
+  <h2 id="compat-matcher">
+    Simplified function for matching data objects
+  </h2>
+
+  <p class="alert alert-info">
+    <a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
+    This method was added to make upgrading easier from earlier versions of
+    Select2.
+  </p>
+
+  <p>
+    During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
+    <code>matcher</code> function was changed to allow for more complex
+    matching of nested objects.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>matcher</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking a search <code>term</code> and the data object
+          <code>text</code>.
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/compat/matcher">oldMatcher</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    The <a href="examples.html#matcher">custom matcher example</a> provides a
+    guide for how to use this in your own application. For those upgrading
+    from older versions of Select2, you just need to wrap your old
+    <code>matcher</code> with this function to maintain compatibility.
+  </p>
+</section>
+
+<section>
+  <h2 id="initSelection">
+    Old initial selections with <code>initSelection</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
+    This has been replaced by another option and is only available in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2.
+  </p>
+
+  <p>
+    In the past, Select2 required an option called <code>initSelection</code>
+    that was defined whenever a custom data source was being used, allowing
+    for the initial selection for the component to be determined. This has
+    been replaced by the <code>current</code> method on the
+    <a href="#dataAdapter">data adapter</a>.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>initSelection</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking a <code>callback</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/compat/initSelection">InitSelection</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+</section>
+
+<section>
+  <h2 id="query">
+    Querying old data with <code>query</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
+    This has been replaced by another option and is only available in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2.
+  </p>
+
+  <p>
+    In the past, Select2 supported an option called <code>query</code> that
+    allowed for a custom data source to be used. This option has been replaced
+    by the <code>query</code> method on the
+    <a href="#dataAdapter">data adapter</a> and takes a very similar set of
+    parameters.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>query</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking <code>params</code> (including a <code>callback</code>)
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/compat/query">Query</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+</section>
+
+<section>
+  <h2 id="input-fallback">
+    Compatibility with <code>&lt;input type="text" /&gt;</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#hidden-input" class="alert-link">Deprecated in Select2 4.0.</a>
+    It is now encouraged to use the <code>&lt;select&gt;</code> tag instead.
+  </p>
+
+  <p>
+    In past versions of Select2, a <code>&lt;select&gt;</code> element could
+    only be used with a limited subset of options. An
+    <code>&lt;input type="hidden" /&gt;</code> was required instead, which did
+    not allow for a graceful fallback for users who did not have JavaScript
+    enabled. Select2 now supports the <code>&lt;select&gt;</code> element for
+    all options, so it is no longer required to use <code>&lt;input /&gt;</code>
+    elements with Select2.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Adapter</dt>
+    <dd>
+      <code title="select2/data/base">DataAdapter</code>
+    </dd>
+
+    <dt>Decorator</dt>
+    <dd>
+      <code title="select2/compat/inputData">InputData</code>
+    </dd>
+  </dl>
+</section>

pages/02.configuration/docs.md

@@ -0,0 +1,298 @@
+---
+title: Configuration
+taxonomy:
+    category: docs
+---
+
+Select2 has the following configuration options available. Note that this page is a work
+in progress. The <a href="http://select2.github.io/select2/#documentation">previous
+release's documentation</a> should cover the gaps here for the time being.
+
+<table class="table table-bordered table-striped">
+  <thead>
+      <tr>
+          <th>Option</th>
+          <th>Type</th>
+          <th>Description</th>
+      </tr>
+  </thead>
+  <tbody>
+    <tr id="adaptContainerCssClass">
+      <td>adaptContainerCssClass</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="adaptDropdownCssClass">
+      <td>adaptDropdownCssClass</td>
+      <td></td>
+      <td></td>
+    </tr>
+      <tr id="ajax">
+          <td>ajax</td>
+          <td></td>
+          <td></td>
+      </tr>
+      <tr id="allowClear">
+          <td>allowClear</td>
+          <td>boolean</td>
+          <td>
+              <p>When set to <strong>true</strong>, causes a clear button to appear on the select box
+        when a value is selected. Clicking the clear button will clear the selected value,
+        effectively resetting the select box back to its placeholder value.</p>
+
+              <p>Default value: <strong>false</strong></p>
+          </td>
+      </tr>
+    <tr id="amdBase">
+      <td>amdBase</td>
+      <td>string</td>
+      <td>
+        <p>The base AMD loader path to be used for select2 dependency resolution. This option
+        typically doesn't need to be changed, but is available for situations where module names
+        may change as a result of certain build environments.</p>
+
+        <p>Default value: <strong>&quot;./&quot;</strong></p>
+      </td>
+    </tr>
+    <tr id="amdLanguageBase">
+      <td>amdLanguageBase</td>
+      <td>string</td>
+      <td>
+        <p>The base AMD loader language path to be used for select2 language file resolution. This
+        option typically doesn't need to be changed, but is available for situations where module
+        names may change as a result of certain build environments.</p>
+
+        <p>Default value: <strong>&quot;./i18n/&quot;</strong></p>
+      </td>
+    </tr>
+      <tr id="closeOnSelect">
+          <td>closeOnSelect</td>
+          <td>boolean</td>
+          <td>
+              <p>When set to <strong>false</strong>, keeps the dropdown open upon selecting an option,
+        making it easy to quickly select multiple items. <em>Note that this option is only
+        applicable to multi-select controls</em>.</p>
+
+              <p>Default value: <strong>true</strong></p>
+          </td>
+      </tr>
+    <tr id="containerCss">
+      <td>containerCss</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="containerCssClass">
+      <td>containerCssClass</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="dataAdapter">
+      <td>dataAdapter</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="debug">
+      <td>debug</td>
+      <td>boolean</td>
+      <td></td>
+    </tr>
+      <tr id="dir">
+          <td>dir</td>
+          <td></td>
+          <td></td>
+      </tr>
+      <tr id="disabled">
+          <td>disabled</td>
+          <td>boolean</td>
+          <td>
+              <p>When set to <strong>true</strong>, the select control will be disabled.</p>
+
+              <p>Default value: <strong>false</strong></p>
+          </td>
+      </tr>
+    <tr id="dropdownAdapter">
+      <td>dropdownAdapter</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="dropdownAutoWidth">
+      <td>dropdownAutoWidth</td>
+      <td>boolean</td>
+      <td></td>
+    </tr>
+    <tr id="dropdownCss">
+      <td>dropdownCss</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="dropdownCssClass">
+      <td>dropdownCssClass</td>
+      <td></td>
+      <td></td>
+    </tr>
+      <tr id="dropdownParent">
+          <td>dropdownParent</td>
+          <td></td>
+          <td></td>
+      </tr>
+    <tr id="escapeMarkup">
+      <td>escapeMarkup</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="initSelection">
+      <td>initSelection</td>
+      <td></td>
+      <td></td>
+    </tr>
+      <tr id="language">
+          <td>language</td>
+          <td></td>
+          <td></td>
+      </tr>
+    <tr id="matcher">
+      <td>matcher</td>
+      <td></td>
+      <td></td>
+    </tr>
+      <tr id="maximumInputLength">
+          <td>maximumInputLength</td>
+          <td>integer</td>
+          <td>
+        <p>Maximum number of characters that may be provided for a search term.</p>
+
+        <p>Default value: <strong>0</strong></p>   
+      </td>
+      </tr>
+      <tr id="maximumSelectionLength">
+          <td>maximumSelectionLength</td>
+          <td>integer</td>
+          <td>
+        <p>The maximum number of items that may be selected in a multi-select control. If the
+        value of this option is less than 1, the number of selected items will not be limited.</p>
+
+        <p>Default value: <strong>0</strong></p>
+      </td>
+      </tr>
+      <tr id="minimumInputLength">
+          <td>minimumInputLength</td>
+          <td>integer</td>
+          <td>
+              <p>Minimum number of characters required to start a search. This options is primarily
+        useful in cases where data is loaded via the <code>ajax</code> option.</p>
+
+        <p>Default value: <strong>0</strong></p>
+          </td>
+      </tr>
+      <tr id="minimumResultsForSearch">
+          <td>minimumResultsForSearch</td>
+          <td>integer</td>
+          <td>
+              <p>The minimum number of results required in the initial population of the dropdown to
+        keep the search box. This option is useful for cases where local data is used with a small
+        result set, and the search box would simply be a waste of screen real estate. Set this
+        value to -1 to permanently hide the search box.</p>
+
+        <p>Default value: <strong>0</strong></p>
+          </td>
+      </tr>
+    <tr id="multiple">
+      <td>multiple</td>
+      <td></td>
+      <td>
+        This option enables multi-select (pillbox) mode.  Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization.
+      </td>
+    </tr>
+      <tr id="placeholder">
+          <td>placeholder</td>
+          <td></td>
+          <td></td>
+      </tr>
+    <tr id="query">
+      <td>query</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="resultsAdapter">
+      <td>resultsAdapter</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="selectionAdapter">
+      <td>selectionAdapter</td>
+      <td></td>
+      <td></td>
+    </tr>
+      <tr id="selectOnClose">
+          <td>selectOnClose</td>
+          <td>boolean</td>
+          <td>
+        <p>Default value: <strong>false</strong></p>
+      </td>
+      </tr>
+    <tr id="sorter">
+      <td>sorter</td>
+      <td>function</td>
+      <td></td>
+    </tr>
+      <tr id="tags">
+          <td>tags</td>
+          <td></td>
+          <td></td>
+      </tr>
+      <tr id="templateResult">
+          <td>templateResult</td>
+          <td>function</td>
+          <td></td>
+      </tr>
+      <tr id="templateSelection">
+          <td>templateSelection</td>
+          <td>function</td>
+          <td></td>
+      </tr>
+      <tr id="theme">
+          <td>theme</td>
+          <td>string</td>
+          <td>
+        <p>Default value: <strong>default</strong></p>
+      </td>
+      </tr>
+    <tr id="tokenizer">
+      <td>tokenizer</td>
+      <td></td>
+      <td></td>
+    </tr>
+    <tr id="tokenSeparators">
+      <td>tokenSeparators</td>
+      <td></td>
+      <td></td>
+    </tr>
+      <tr id="width">
+          <td>width</td>
+          <td>string</td>
+          <td>
+              <p>Specifies the <code>width</code> style attribute of the select2 container. The
+        following values are supported:</p>
+
+              <dl class="dl-horizontal">
+                  <dt>element</dt>
+                  <dd>Uses the computed element width from any applicable CSS rules.</dd>
+
+                  <dt>resolve</dt>
+                  <dd>Uses the <code>style</code> attribute value if available, falling
+          back to the computed element width as necessary.</dd>
+
+                  <dt>style</dt>
+                  <dd>Width is determined from the <code>select</code> element's <code>style</code>
+          attribute. If no <code>style</code> attribute is found, null is returned as the
+          width.</dd>
+
+                  <dt><em>{width_value}</em></dt>
+                  <dd>Valid CSS values can be passed as a string (i.e. <code>80%</code>).</dd>
+              </dl>
+
+              <p>Default value: <strong>resolve</strong></p>
+          </td>
+      </tr>
+  </tbody>
+</table>

pages/03.appearance/01.markup/docs.md

@@ -0,0 +1,115 @@
+---
+title: Basic markup
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+A standard `<select>` box contains any number of `<option>` elements.  Each of these is rendered as an option in the dropdown menu.  Select2 preserves this behavior when initialized on a `<select>` element that contains `<option>` elements.
+
+## Disabling a Select2 control
+
+Select2 will respond to the <code>disabled</code> attribute on `<select>` elements. You can also initialize Select2 with `disabled: true` to get the same effect.
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-disabled js-states form-control" disabled="disabled"></select>
+  </p>
+
+  <p>
+    <select class="js-example-disabled-multi js-states form-control" multiple="multiple" disabled="disabled"></select>
+  </p>
+  <div class="btn-group btn-group-sm" role="group" aria-label="Programmatic enabling and disabling">
+    <button type="button" class="js-programmatic-enable btn btn-default">
+      Enable
+    </button>
+    <button type="button" class="js-programmatic-disable btn btn-default">
+      Disable
+    </button>
+  </div>
+</div>
+
+<pre data-fill-from=".js-code-disabled"></pre>
+
+<script type="text/javascript" class="js-code-disabled">
+
+$(".js-example-disabled").select2();
+$(".js-example-disabled-multi").select2();
+  
+$(".js-programmatic-enable").on("click", function () {
+  $(".js-example-disabled").prop("disabled", false);
+  $(".js-example-disabled-multi").prop("disabled", false);
+});
+
+$(".js-programmatic-disable").on("click", function () {
+  $(".js-example-disabled").prop("disabled", true);
+  $(".js-example-disabled-multi").prop("disabled", true);
+});
+
+</script>
+
+## Labels
+
+You can, and should, use a `<label>` with Select2, just like any other `<select>` element.
+
+<div class="s2-example">
+  <p>
+    <label for="id_label_single">
+      Click this to focus the single select element
+      <select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
+    </label>
+  </p>
+  <p>
+    <label for="id_label_multiple">
+      Click this to focus the multiple select element
+      <select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
+    </label>
+  </p>
+</div>
+
+```
+<label for="id_label_single">
+  Click this to highlight the single select element
+
+  <select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
+</label>
+
+<label for="id_label_multiple">
+  Click this to highlight the multiple select element
+
+  <select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
+</label>
+```
+
+<script type="text/javascript">
+  $.fn.select2.amd.require([
+    "select2/core",
+    "select2/utils"
+  ], function (Select2, Utils, oldMatcher) {
+    var $basicSingle = $(".js-example-basic-single");
+    var $basicMultiple = $(".js-example-basic-multiple");
+
+    $.fn.select2.defaults.set("width", "100%");
+
+    $basicSingle.select2();
+    $basicMultiple.select2();
+
+    function formatState (state) {
+      if (!state.id) {
+        return state.text;
+      }
+      var $state = $(
+        '<span>' +
+          '<img src="vendor/images/flags/' +
+            state.element.value.toLowerCase() +
+          '.png" class="img-flag" /> ' +
+          state.text +
+        '</span>'
+      );
+      return $state;
+    };
+  });
+
+</script>

pages/03.appearance/02.theming/docs.md

@@ -0,0 +1,68 @@
+---
+title: Theming
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+## Theme support
+
+  <p>
+    Select2 supports custom themes using the
+    <a href="options.html#theme">theme option</a>
+    so you can style Select2 to match the rest of your application.
+  </p>
+
+  <p>
+    These are using the <code>classic</code> theme, which matches the old
+    look of Select2.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-theme-single js-states form-control">
+      </select>
+    </p>
+    <p>
+      <select class="js-example-theme-multiple js-states form-control" multiple="multiple"></select>
+    </p>
+  </div>
+
+```
+$(".js-example-theme-single").select2({
+  theme: "classic"
+});
+
+$(".js-example-theme-multiple").select2({
+  theme: "classic"
+});
+```
+
+Various display options of the Select2 component can be changed:
+You can access the <code>&lt;option&gt;</code> element
+(or <code>&lt;optgroup&gt;</code>) and any attributes on those elements
+using <code>.element</code>.
+
+## Responsive design - Percent width
+
+Select2's width can be set to a percentage of its parent to support
+responsive design. The two Select2 boxes below are styled to 50% and 75%
+width respectively.
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-responsive js-states" style="width: 50%"></select>
+  </p>
+  <p>
+    <select class="js-example-responsive js-states" multiple="multiple" style="width: 75%"></select>
+  </p>
+</div>
+
+```
+<select class="js-example-responsive" style="width: 50%"></select>
+<select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>
+```
+
+>>>> Select2 will do its best to resolve the percent width specified via a CSS class, but it is not always possible. The best way to ensure that Select2 is using a percent based width is to inline the `style` declaration into the tag.

pages/03.appearance/chapter.md

@@ -0,0 +1,11 @@
+---
+title: Appearance
+taxonomy:
+    category: docs
+---
+
+### Chapter 3
+
+# Appearance
+
+The appearance of your Select2 controls can be customized via the standard HTML attributes for `<select>` elements, as well as various [configuration options](/configuration).

pages/04.searching/docs.md

@@ -0,0 +1,80 @@
+---
+title: Search
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+The appearance and behavior of the search control can be easily customized with Select2.
+
+## Customizing how results are matched
+
+You may customize the way that Select2 matches search terms by passing a callback to the `matcher` option. This example matches results only if the term appears in the beginning of the string as opposed to anywhere:
+
+<div class="s2-example">
+    <select class="js-example-matcher-start js-states form-control"></select>
+</div>
+
+<pre data-fill-from=".js-code-example-matcher"></pre>
+
+<script type="text/javascript" class="js-code-example-matcher">
+
+function matchStart (term, text) {
+  if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
+    return true;
+  }
+
+  return false;
+}
+
+$.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
+  $(".js-example-matcher-start").select2({
+    matcher: oldMatcher(matchStart)
+  })
+});
+
+</script>
+
+>>> This custom matcher uses a [compatibility module](/configuration/deprecated) that is only bundled in the [full version of Select2](/getting-started/builds). You also have the option of using a <a href="options.html#matcher">more complex matcher</a>.
+
+## Limiting search term length
+
+You may limit the maximum length of search terms by using the `maximumInputLength` option:
+
+```
+$('select').select2({
+  maximumInputLength: 20 // only allow terms up to 20 characters long
+});
+```
+
+## Limiting display of the search box to large result sets
+
+The `minimumResultsForSearch` option determines the minimum number of results required in the initial population of the dropdown to display the search box.
+
+This option is useful for cases where local data is used with a small result set, and the search box would simply be a waste of screen real estate. Set this value to -1 to permanently hide the search box.
+
+```
+$('select').select2({
+  minimumResultsForSearch: 20 // at least 20 results must be displayed
+});
+```
+
+## Hiding the search box
+
+Select2 allows you to hide the search box depending on the number of options which are displayed. In this example, we use the value `Infinity` to tell Select2 to never display the search box.
+
+<div class="s2-example">
+    <select class="js-example-basic-hide-search js-states form-control"></select>
+</div>
+
+<pre data-fill-from=".js-code-example-basic-hide-search"></pre>
+
+<script type="text/javascript" class="js-code-example-basic-hide-search">
+
+$(".js-example-basic-hide-search").select2({
+  minimumResultsForSearch: Infinity
+});
+
+</script>

pages/05.dropdown/docs.md

@@ -0,0 +1,124 @@
+---
+title: Dropdown
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+This chapter covers the appearance and behavior of the dropdown menu.
+
+## Templating
+
+The appearance of search results in the dropdown can be customized by using the `templateResult` option:
+
+<div class="s2-example">
+    <select class="js-example-templating js-states form-control"></select>
+</div>
+
+<pre data-fill-from=".js-code-example-templating"></pre>
+
+<script type="text/javascript" class="js-code-example-templating">
+
+function formatState (state) {
+  if (!state.id) {
+    return state.text;
+  }
+  var baseUrl = "{{ url('images/flags/') }}";
+  var $state = $(
+    '<span><img src="' + baseUrl + state.element.value.toLowerCase() + '.png" class="img-flag" /> ' + state.text + '</span>'
+  );
+  return $state;
+};
+
+$(".js-example-templating").select2({
+  templateResult: formatState
+});
+
+</script>
+
+## Disabling options
+
+Select2 will correctly handle disabled options, both with data coming from a standard select (when the `disabled` attribute is set) and from remote sources, where the object has <code>disabled: true</code> set.
+
+<div class="s2-example">
+    <select class="js-example-disabled-results form-control">
+      <option value="one">First</option>
+      <option value="two" disabled="disabled">Second (disabled)</option>
+      <option value="three">Third</option>
+    </select>
+</div>
+
+<pre data-fill-from=".js-code-disabled-option"></pre>
+
+```
+<select class="js-example-disabled-results">
+  <option value="one">First</option>
+  <option value="two" disabled="disabled">Second (disabled)</option>
+  <option value="three">Third</option>
+</select>
+```
+
+<script type="text/javascript" class="js-code-disabled-option">
+
+var $disabledResults = $(".js-example-disabled-results");
+$disabledResults.select2();
+
+</script>
+
+## Automatic selection
+
+Select2 can be configured to automatically select the currently highlighted result when the dropdown is closed by using the `selectOnClose` option:
+
+```
+$('select').select2({
+  selectOnClose: true
+});
+```
+
+## Forcing the dropdown to remain open after selection
+
+You may use the `closeOnSelect` option to prevent the dropdown from closing when a result is selected:
+
+```
+$('select').select2({
+  closeOnSelect: false
+});
+```
+
+## Dropdown placement
+
+The `dropdownParent` option allows you to pick an element for the dropdown to be appended to:
+
+```
+$('select').select2({
+  dropdownParent: $('#my_amazing_modal')
+});
+```
+
+### Using a Select2 control inside a Bootstrap modal
+
+If you're having trouble using the search box inside a Bootstrap modal, trying setting the `dropdownParent` option to the modal element.
+
+## Dropdown option groups
+
+In HTML, `<option>` elements can be grouped by wrapping them with in an `<optgroup>` element:
+
+```
+<select>
+  <optgroup label="Group Name">
+    <option>Nested option</option>
+  </optgroup>
+</select>
+```
+
+Select2 will automatically pick these up and render them appropriately in the dropdown.
+
+### Hierarchical options
+
+Only a single level of nesting is allowed per the HTML specification. If you nest an `<optgroup>` within another `<optgroup>`, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.
+
+Furthermore, `<optgroup>` elements **cannot** be made selectable.  This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
+
+If you wish to create a true hierarchy of selectable options, use an `<option>` instead of an `<optgroup>` and <a href="http://stackoverflow.com/q/30820215/359284#30948247">change the style with CSS</a>.  Please note that this approach may be considered "less accessible" as it relies on CSS styling, rather than the semantic meaning of `<optgroup>`, to generate the effect.

pages/06.selections/docs.md

@@ -0,0 +1,92 @@
+---
+title: Selections
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+When a selection is made by the user, Select2 will convert the selected `<option>` element into a JSON object based on the following rules:
+
+```
+{
+  "id": "value attribute" || "option text",
+  "text": "label attribute" || "option text",
+  "element": HTMLOptionElement
+}
+```
+
+`<optgroup>` elements will be converted into data objects using the following rules:
+
+```
+{
+  "text": "label attribute",
+  "children": [ option data object, ... ],
+  "element": HTMLOptGroupElement
+}
+```
+
+By default, Select2 will then display the `text` property of the selected result.
+
+## Templating
+
+The appearance of selected results can be customized by using the `templateSelection` configuration option.  This takes a callback that transforms the selection data object into a string representation or jQuery object:
+
+<div class="s2-example">
+    <select class="js-example-templating js-states form-control"></select>
+</div>
+
+<pre data-fill-from=".js-code-example-templating"></pre>
+
+<script type="text/javascript" class="js-code-example-templating">
+
+function formatState (state) {
+  if (!state.id) {
+    return state.text;
+  }
+  var baseUrl = "{{ url('images/flags/') }}";
+  var $state = $(
+    '<span><img src="' + baseUrl + state.element.value.toLowerCase() + '.png" class="img-flag" /> ' + state.text + '</span>'
+  );
+  return $state;
+};
+
+$(".js-example-templating").select2({
+  templateSelection: formatState
+});
+
+</script>
+
+If your selection template contains HTML, you must wrap your rendered result in a jQuery object. Otherwise, Select2 will assume that your template only returns text and will escape it.  You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
+
+## Limiting the number of selections
+
+Select2 multi-value select boxes can set restrictions regarding the maximum number of options that can be selected. The select below is declared with the `multiple` attribute with `maximumSelectionLength` in the select2 options.
+
+<div class="s2-example">
+    <p>
+      <select class="js-example-basic-multiple-limit js-states form-control" multiple="multiple"></select>
+    </p>
+</div>
+
+<pre data-fill-from=".js-code-placeholder"></pre>
+
+<script type="text/javascript" class="js-code-placeholder">
+
+$(".js-example-basic-multiple-limit").select2({
+  maximumSelectionLength: 2
+});
+
+</script>
+
+## Clearable selections
+
+You can allow users to clear their current selections with the `allowClear` option when initializing Select2. Setting this option to `true` will enable an "x" icon that will reset the selection to the placeholder.
+
+```
+$('select').select2({
+  placeholder: 'This is my placeholder',
+  allowClear: true
+});
+```

pages/07.placeholders/docs.md

@@ -0,0 +1,81 @@
+---
+title: Placeholders
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+Select2 supports displaying a placeholder value using the `placeholder` configuration option. The placeholder value will be displayed until a selection is made.
+
+## Text placeholders
+
+The most common situation is to use a string of text as your placeholder value.
+
+**In order for a string placeholder value to appear**, you must have a blank `<option>` as the first option in your `<select>` control.  This is because the browser tries to select the first option by default. If your first option were non-empty, the browser would display this instead of the placeholder. Note that this issue does not apply to multiple selects.
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-placeholder-single js-states form-control">
+      <option></option>
+    </select>
+  </p>
+  <p>
+    <select class="js-example-placeholder-multiple js-states form-control" multiple="multiple"></select>
+  </p>
+</div>
+
+<pre data-fill-from=".js-code-placeholder"></pre>
+
+<script type="text/javascript" class="js-code-placeholder">
+    $(".js-example-placeholder-single").select2({
+      placeholder: "Select a state",
+      allowClear: true
+    });
+    
+    $(".js-example-placeholder-multiple").select2({
+      placeholder: "Select a state"
+    });
+</script>
+
+>>> Select2 uses the `placeholder` attribute on multiple select boxes, which requires IE 10+. You can support it in older versions with <a href="https://github.com/jamesallardice/Placeholders.js">the Placeholders.js polyfill</a>.
+
+## Default selection placeholders
+
+Alternatively, the value of the `placeholder` option can be a data object representing a default selection (`<option>`). In this case the `id` of the data object should match the `value` of the corresponding default selection.
+
+```
+$('select').select2({
+  placeholder: {
+    id: '-1', // the value of the option
+    text: 'Select an option'
+  }
+});
+```
+
+## Using placeholders with AJAX
+
+Select2 supports placeholders for all configurations, including AJAX. You will still need to add in the empty `<option>` if you are using a single select.
+
+## Customizing placeholder appearance
+
+When using Select2 **in single-selection mode**, the placeholder option will be passed through the `templateSelection` callback if specified. You can use some additional logic in this callback to check the `id` property and apply an alternative transformation to your placeholder option:
+
+```
+$('select').select2({
+  templateSelection: function (data) {
+    if (data.id === '') { // adjust for custom placeholder values
+      return 'Custom styled placeholder text';
+    }
+
+    return data.text;
+  }
+});
+```
+
+>>>>> **When multiple selections are allowed**, the placeholder will be displayed using the `placeholder` attribute on the search box. You can customize the display of this placeholder using CSS, as explained in the following Stack Overflow answer: [Change an input's HTML5 placeholder color with CSS](http://stackoverflow.com/q/2610497/359284).
+
+## Placeholders in legacy Internet Explorer versions
+
+Select2 uses the native `placeholder` attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include [Placeholders.js](https://github.com/jamesallardice/Placeholders.js) on your page, or use the full build, in order to add `placeholder` attribute support to input boxes.

pages/08.tagging/docs.md

@@ -0,0 +1,129 @@
+---
+title: Free-text entry
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+In addition to a prepopulated menu of options, Select2 can also allow free-text responses.  This feature is called "tagging".  To enable free-text responses, set the <code>tags</code> option to `true`:
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-tags form-control">
+      <option selected="selected">orange</option>
+      <option>white</option>
+      <option>purple</option>
+    </select>
+  </p>
+</div>
+
+```
+$(".js-example-tags").select2({
+  tags: true
+})
+```
+
+Note that when tagging is enabled the user can select from the pre-existing options or create a new option by picking the first choice, which is what the user has typed into the search box so far.
+
+## Tagging with multi-value select boxes
+
+Tagging can also be used in multi-value select boxes. In the example below, we set the <code>multiple="multiple"</code> attribute on a Select2 control that also has <code>tags: true</code> enabled:
+  
+<div class="s2-example">
+  <p>
+    <select class="js-example-tags form-control" multiple="multiple">
+      <option selected="selected">orange</option>
+      <option>white</option>
+      <option selected="selected">purple</option>
+    </select>
+  </p>
+</div>
+
+Try entering a value that isn't listed in the dropdown - you'll be able to add it as a new option!
+
+## Automatic tokenization into tags
+
+Select2 supports ability to add choices automatically as the user is
+typing into the search field. Try typing in the search field below and
+entering a space or a comma.
+
+The separators that should be used when tokenizing can be specified
+using the <a href="options.html#tokenSeparators">tokenSeparators</a>
+options.
+
+<div class="s2-example">
+<p>
+  <select class="js-example-tokenizer form-control" multiple="multiple">
+    <option>red</option>
+    <option>blue</option>
+    <option>green</option>
+  </select>
+</p>
+</div>
+
+```
+$(".js-example-tokenizer").select2({
+    tags: true,
+    tokenSeparators: [',', ' ']
+})
+```
+
+## Customizing tag creation
+
+### Tag properties
+
+You may add extra properties to newly created tags by defining a `createTag` callback:
+
+```
+$('select').select2({
+  createTag: function (params) {
+    var term = $.trim(params.term);
+
+    if (term === '') {
+      return null;
+    }
+
+    return {
+      id: term,
+      text: term,
+      newTag: true // add additional parameters
+    }
+  }
+});
+```
+
+### Constraining tag creation
+
+You may control when Select2 will allow the user to create a new tag, by adding some logic to `createTag` to return `null` if an invalid value is entered:
+
+```
+$('select').select2({
+  createTag: function (params) {
+    // Don't offset to create a tag if there is no @ symbol
+    if (params.term.indexOf('@') === -1) {
+      // Return null to disable tag creation
+      return null;
+    }
+
+    return {
+      id: params.term,
+      text: params.term
+    }
+  }
+});
+```
+
+## Customizing tag placement in the dropdown
+
+You may control the placement of the newly created option by defining a `insertTag` callback:
+
+```
+$('select').select2({
+  insertTag: function (data, tag) {
+    // Insert the tag at the end of the results
+    data.push(tag);
+  }
+});
+```

pages/09.data-sources/01.formats/docs.md

@@ -0,0 +1,111 @@
+---
+title: The Select2 data format
+taxonomy:
+    category: docs
+---
+
+Select2 can render programmatically supplied data from an array or remote data source (AJAX) as dropdown options. These will be rendered as actual `<option>` elements in the target `<select>` control.
+
+In order to accomplish this, Select2 expects a very specific data format.  This format consists of a JSON object containing an array of objects keyed by the `results` key.
+
+```
+{
+  "results": [
+    {
+      "id": 1,
+      "text": "Option 1"
+    },
+    {
+      "id": 2,
+      "text": "Option 2"
+    }
+  ],
+  "pagination": {
+    "more": true
+  }
+}
+```
+
+Each object should contain, _at a minimum_, an `id` and a `text` property. The `text` property will be displayed by default unless you are using `templateResult` and `templateSelection` to customize the way options and selections are rendered.
+
+The response object may also contain pagination data, if you would like to use the "infinite scroll" feature.  This should be specified under the `pagination` key.
+
+Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.
+
+## Transforming data into the required format
+
+### Generating `id` properties
+
+Select2 requires that the `id` property is used to uniquely identify the options that are displayed in the results list. If you use a property other than `id` (like `pk`) to uniquely identify an option, you need to map your old property to `id` before passing it to Select2.
+
+If you cannot do this on your server or you are in a situation where the API cannot be changed, you can do this in JavaScript before passing it to Select2:
+
+```
+var data = $.map(yourArrayData, function (obj) {
+  obj.id = obj.id || obj.pk; // replace pk with your identifier
+
+  return obj;
+});
+```
+
+### Generating `text` properties
+
+Just like with the `id` property, Select2 requires that the text that should be displayed for an option is stored in the `text` property. You can map this property from any existing property using the following JavaScript:
+
+```
+var data = $.map(yourArrayData, function (obj) {
+  obj.text = obj.text || obj.name; // replace name with the property used for the text
+
+  return obj;
+});
+```
+
+## Automatic string casting
+
+Because the `value` attribute on a `<select>` tag must be a string, and Select2 generates the `value` attribute from the `id` property of the data objects, the `id` property on each data object must also be a string.
+
+Select2 will attempt to convert anything that is not a string to a string, which will work for most situations, but it is recommended to explicitly convert your `id`s to strings ahead of time.
+
+Blank `id`s or an `id` with a value of `0` are not permitted.
+
+## Grouped options
+
+When options are to be generated in `<optgroup>` sections, options should be nested under the `children` key of each group object.  The label for the group should be specified as the `text` property on the group's corresponding data object.
+
+```
+{
+  "results": [
+    { 
+      "text": "Group 1", 
+      "children" : [
+        {
+            "id": 1,
+            "text": "Option 1.1"
+        }
+        {
+            "id": 2,
+            "text": "Option 1.2"
+        }
+      ]
+    },
+    { 
+      "text": "Group 2", 
+      "children" : [
+        {
+            "id": 3,
+            "text": "Option 2.1"
+        }
+        {
+            "id": 4,
+            "text": "Option 2.2"
+        }
+      ]
+    }
+  ],
+  "paginate": {
+    "more": true
+  }
+}
+```
+
+>>>> Because Select2 generates an `<optgroup>` when creating nested options, only [a single level of nesting is supported](/dropdown/option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.

pages/09.data-sources/02.ajax/docs.md

@@ -0,0 +1,180 @@
+---
+title: Ajax (remote data)
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API.
+
+<select class="js-example-data-ajax form-control">
+  <option value="3620194" selected="selected">select2/select2</option>
+</select>
+
+When using Select2 with remote data, the HTML required for the `select` is the same as any other Select2. If you need to provide default selections, you just need to include an `option` for each selection that contains the value and text that should be displayed.
+
+```
+<select class="js-data-example-ajax">
+  <option value="3620194" selected="selected">select2/select2</option>
+</select>
+```
+
+You can configure how Select2 searches for remote data using the `ajax` option. More information on the individual options
+that Select2 handles can be found in the [options documentation for `ajax`](/configuration).
+
+<pre data-fill-from=".js-code-placeholder"></pre>
+
+<script type="text/javascript" class="js-code-placeholder">
+
+$(".js-example-data-ajax").select2({
+  ajax: {
+    url: "https://api.github.com/search/repositories",
+    dataType: 'json',
+    delay: 250,
+    data: function (params) {
+      return {
+        q: params.term, // search term
+        page: params.page
+      };
+    },
+    processResults: function (data, params) {
+      // parse the results into the format expected by Select2
+      // since we are using custom formatting functions we do not need to
+      // alter the remote JSON data, except to indicate that infinite
+      // scrolling can be used
+      params.page = params.page || 1;
+
+      return {
+        results: data.items,
+        pagination: {
+          more: (params.page * 30) < data.total_count
+        }
+      };
+    },
+    cache: true
+  },
+  escapeMarkup: function (markup) { return markup; }, // let our custom formatter work
+  minimumInputLength: 1,
+  templateResult: formatRepo,
+  templateSelection: formatRepoSelection
+});
+
+function formatRepo (repo) {
+  if (repo.loading) return repo.text;
+
+  var markup = "<div class='select2-result-repository clearfix'>" +
+    "<div class='select2-result-repository__avatar'><img src='" + repo.owner.avatar_url + "' /></div>" +
+    "<div class='select2-result-repository__meta'>" +
+      "<div class='select2-result-repository__title'>" + repo.full_name + "</div>";
+
+  if (repo.description) {
+    markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
+  }
+
+  markup += "<div class='select2-result-repository__statistics'>" +
+    "<div class='select2-result-repository__forks'><i class='fa fa-flash'></i> " + repo.forks_count + " Forks</div>" +
+    "<div class='select2-result-repository__stargazers'><i class='fa fa-star'></i> " + repo.stargazers_count + " Stars</div>" +
+    "<div class='select2-result-repository__watchers'><i class='fa fa-eye'></i> " + repo.watchers_count + " Watchers</div>" +
+  "</div>" +
+  "</div></div>";
+
+  return markup;
+}
+
+function formatRepoSelection (repo) {
+  return repo.full_name || repo.text;
+}
+</script>
+
+Select2 will pass any options in the `ajax` object to jQuery's `$.ajax` function, or the `transport` function you specify.
+
+>>> Select2 expects results from the remote endpoint to be filtered on the **server side**. If server-side filtering is not possible, you may be interested in using Select2's <a href="examples.html#data-array">support for data arrays</a> instead.
+
+## Rate-limiting requests
+
+You can tell Select2 to wait until the user has finished typing their search term before triggering the AJAX request.  Simply use the `ajax.delay` configuration option to tell Select2 how long to wait after a user has stopped typing before sending the request:
+
+```
+$('select').select2({
+  ajax: {
+    delay: 250 // wait 250 milliseconds before triggering the request
+  }
+});
+```
+
+## Transforming response data
+
+You can use the <code>ajax.processResults</code> option to transform the data returned by your API into the format expected by Select2:
+
+```
+$('select').select2({
+  ajax: {
+    url: '/example/api',
+    processResults: function (data) {
+      return {
+        results: data.items
+      };
+    }
+  }
+});
+```
+
+## Default values
+
+You may wish to set a pre-selected default value for a Select2 control that receives its data from an AJAX request.
+
+To do this, please refer to the following Stack Overflow answer: [Select2 4.0.0 initial value with AJAX](http://stackoverflow.com/q/30316586/359284#30328989).
+
+## Additional request parameters
+
+By default, Select2 will send the search query term as well as the pagination data as query parameters in requests.
+
+Sometimes, you may need to add additional query parameters to the request.  You can modify the parameters that are sent with the request by overriding the `ajax.data` option:
+
+```
+$('select').select2({
+  ajax: {
+    data: function (params) {
+      var query = {
+        search: params.term,
+        page: params.page
+      }
+
+      // Query parameters will be ?search=[term]&page=[page]
+      return query;
+    }
+  }
+});
+```
+
+## Dynamic URLs
+
+If there isn't a single url for your search results, or you need to call a function to determine the url to use, you can specify a callback for the `ajax.url` option to generate the url. The current search query will be passed in through the `params` option:
+
+```
+$('select').select2({
+  ajax: {
+    url: function (params) {
+      return '/some/url/' + params.term;
+    }
+  }
+});
+```
+
+## Alternative transport methods
+
+Select2 uses the transport method defined in `ajax.transport` to send requests to your API. By default this transport method is `jQuery.ajax`, but it can be easily overridden:
+
+```
+$('select').select2({
+  ajax: {
+    transport: function (params, success, failure) {
+      var request = new AjaxRequest(params.url, params);
+      request.on('success', success);
+      request.on('failure', failure);
+    }
+  }
+});
+```

pages/09.data-sources/03.arrays/docs.md

@@ -0,0 +1,61 @@
+---
+title: Arrays
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+## Loading array data
+
+You may use the `data` configuration option to load dropdown options from a local array.
+
+You can provide initial selections with array data by providing the option tag for the selected values, similar to how it would be done for a standard select.
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-data-array form-control"></select>
+  </p>
+  <p>
+    <select class="js-example-data-array-selected form-control">
+      <option value="2" selected="selected">duplicate</option>
+    </select>
+  </p>
+</div>
+
+<pre data-fill-from=".js-code-placeholder"></pre>
+
+<script type="text/javascript" class="js-code-placeholder">
+
+var data = [
+    {
+        id: 0,
+        text: 'enhancement'
+    },
+    {
+        id: 1,
+        text: 'bug'
+    },
+    {
+        id: 2,
+        text: 'duplicate'
+    },
+    {
+        id: 3,
+        text: 'invalid'
+    },
+    {
+        id: 4,
+        text: 'wontfix'
+    }
+];
+
+$(".js-example-data-array").select2({
+  data: data
+})
+
+$(".js-example-data-array-selected").select2({
+  data: data
+})
+</script>

pages/09.data-sources/chapter.md

@@ -0,0 +1,11 @@
+---
+title: Data sources
+taxonomy:
+    category: docs
+---
+
+### Chapter 3
+
+# Data sources
+
+In addition to handling `<option>` elements that explicitly appear in your markup, Select2 can also retrieve the results from other data sources such as a remote JSON API or a local Javascript array.

pages/10.programmatic-control/01.methods/docs.md

@@ -0,0 +1,164 @@
+---
+title: Methods
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+Select2 supports methods that allow programmatic control of the component.  
+
+## Selecting a value
+
+To programmatically select a value for a Select2 control, use the jQuery `.val()` method:
+
+```
+$('select').val('US'); // Select the option with a value of 'US'
+$('select').trigger('change'); // Notify any JS components that the value changed
+```
+
+Select2 will listen for the `change` event on the `<select>` element that it is attached to. When you make any external changes that need to be reflected in Select2 (such as changing the value), you should trigger this event.
+
+### Limiting the scope of the `change` event
+
+It's common for other components to be listening to the `change` event, or for custom event handlers to be attached that may have side effects.  To limit the scope to **only** notify Select2 of the change, use the `.select2` event namespace:
+
+```
+$('select').val('US'); // Change the value or make some change to the internal state
+$('select').trigger('change.select2'); // Notify only Select2 of changes
+```
+
+## Retrieving the selected values
+
+There are two ways to programmatically access the selection data: using `.select2('data')`, or by using a jQuery selector.
+
+### Using the `data` method
+
+Calling `select2('data')` will return a JavaScript array of objects representing the current selection. Each object will contain all of the properties/values that were in the source data objects passed through `processResults` and `templateResult` callbacks (as in <a href="#data">Loading data from an array</a> and <a href="#ajax">Connecting to a remote data source</a>).
+
+```
+$('select').select2('data');
+```
+
+### Using a jQuery selector
+
+Selected items can also be accessed via the `:selected` jQuery selector:
+
+```
+$('select').find(':selected');
+```
+
+It is possible to extend the `<option>` elements representing selection with the HTML data-* attributes containing arbitrary data from the source data objects:
+
+```
+$('select').select2({
+  // ...
+  templateSelection: function (data, container) {
+    $(data.element).attr('data-custom-attribute', data.customValue);
+    return data.text;
+  }
+});
+
+// Retrieve custom attribute value of the first selected element
+$('select').find(':selected').attr('data-custom-attribute')
+```
+
+## Opening the dropdown
+
+Methods handled directly by Select2 can be invoked by passing the name of the method to `.select2(...)`.
+
+The `open` method will cause the dropdown menu to open, displaying the selectable options:
+
+```
+$('select').select2('open');
+```
+
+## Closing the dropdown
+
+The `close` method will cause the dropdown menu to close, hiding the selectable options:
+
+```
+$('select').select2('close');
+```
+
+## Destroying the Select2 control
+
+The `destroy` method will remove the Select2 widget from the target element.  It will revert back to a standard `select` control:
+  
+```
+$('select').select2('destroy');
+```
+
+## Clearing selections
+
+You may clear all current selections in a Select2 control by setting the value of the control to `null`:
+
+```
+$('select').val(null).trigger('change');
+```
+
+## Examples
+
+<div class="s2-example">
+
+    <label for="select2-single">Single select</label>
+    
+    <button class="js-programmatic-set-val button" aria-label="Set Select2 option">
+      Set "California"
+    </button>
+    
+    <button class="js-programmatic-open button">
+      Open
+    </button>
+    
+    <button class="js-programmatic-close button">
+      Close
+    </button>
+    
+    <button class="js-programmatic-destroy button">
+      Destroy
+    </button>
+    
+    <button class="js-programmatic-init button">
+      Re-initialize
+    </button>
+    <p>
+      <select id="select2-single" class="js-example-programmatic js-states form-control"></select>
+    </p>
+    
+    <label for="select2-multi">Multiple select</label>
+
+    <button type="button" class="js-programmatic-multi-set-val button" aria-label="Programmatically set Select2 options">
+      Set to California and Alabama
+    </button>
+    
+    <button type="button" class="js-programmatic-multi-clear button" aria-label="Programmatically clear Select2 options">
+      Clear
+    </button>
+
+    <p>
+      <select id="select2-multi" class="js-example-programmatic-multi js-states form-control" multiple="multiple"></select>
+    </p>
+
+</div>
+
+<pre data-fill-from=".js-code-programmatic"></pre>
+
+<script type="text/javascript" class="js-code-programmatic">
+
+var $example = $(".js-example-programmatic").select2();
+var $exampleMulti = $(".js-example-programmatic-multi").select2();
+
+$(".js-programmatic-set-val").on("click", function () { $example.val("CA").trigger("change"); });
+
+$(".js-programmatic-open").on("click", function () { $example.select2("open"); });
+$(".js-programmatic-close").on("click", function () { $example.select2("close"); });
+
+$(".js-programmatic-init").on("click", function () { $example.select2(); });
+$(".js-programmatic-destroy").on("click", function () { $example.select2("destroy"); });
+
+$(".js-programmatic-multi-set-val").on("click", function () { $exampleMulti.val(["CA", "AL"]).trigger("change"); });
+$(".js-programmatic-multi-clear").on("click", function () { $exampleMulti.val(null).trigger("change"); });
+
+</script>

pages/10.programmatic-control/02.events/docs.md

@@ -0,0 +1,97 @@
+---
+title: Events
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+Select2 will trigger a few different events when different actions are taken using the component, allowing you to add custom hooks and perform actions.
+
+| Event | Description |
+| ----- | ----------- |
+| `change` | Triggered whenever an option is selected or removed. |
+| `select2:closing` | Triggered before the dropdown is closed. This event can be prevented. |
+| `select2:close` | Triggered whenever the dropdown is closed. <code>select2:closing</code> is fired before this and can be prevented. |
+| `select2:opening` | Triggered before the dropdown is opened. This event can be prevented. |
+| `select2:open` | Triggered whenever the dropdown is opened. <code>select2:opening</code> is fired before this and can be prevented. |
+| `select2:selecting` | Triggered before a result is selected. This event can be prevented. |
+| `select2:select` | Triggered whenever a result is selected. <code>select2:selecting</code> is fired before this and can be prevented. |
+| `select2:unselecting` | Triggered before a selection is removed. This event can be prevented. |
+| `select2:unselect` | Triggered whenever a selection is removed. <code>select2:unselecting</code> is fired before this and can be prevented. |
+
+## Listening for events
+
+```
+$('select').on('select2:select', function (e) {
+  // Do something
+});
+```
+
+## Event data
+
+When `select2:select` is triggered, data from the selection can ba accessed via the `params.data` property:
+
+```
+$('select').on('select2:select', function (e) {
+  console.log(e.params.data)
+});
+```
+
+### What events can be prevented? How can I prevent a selection from being made?
+
+
+## Examples
+
+<div class="s2-example">
+  <p>
+    <select class="js-states js-example-events form-control"></select>
+  </p>
+  <p>
+    <select class="js-states js-example-events form-control" multiple="multiple"></select>
+  </p>
+</div>
+
+<div class="s2-event-log">
+  <ul class="js-event-log"></ul>
+</div>
+
+<pre data-fill-from=".js-code-events"></pre>
+
+<script type="text/javascript" class="js-code-events">
+var $eventLog = $(".js-event-log");
+var $eventSelect = $(".js-example-events");
+
+$eventSelect.select2();
+
+$eventSelect.on("select2:open", function (e) { log("select2:open", e); });
+$eventSelect.on("select2:close", function (e) { log("select2:close", e); });
+$eventSelect.on("select2:select", function (e) { log("select2:select", e); });
+$eventSelect.on("select2:unselect", function (e) { log("select2:unselect", e); });
+
+$eventSelect.on("change", function (e) { log("change"); });
+
+function log (name, evt) {
+  if (!evt) {
+    var args = "{}";
+  } else {
+    var args = JSON.stringify(evt.params, function (key, value) {
+      if (value && value.nodeName) return "[DOM node]";
+      if (value instanceof $.Event) return "[$.Event]";
+      return value;
+    });
+  }
+  var $e = $("<li>" + name + " -> " + args + "</li>");
+  $eventLog.append($e);
+  $e.animate({ opacity: 1 }, 10000, 'linear', function () {
+    $e.animate({ opacity: 0 }, 2000, 'linear', function () {
+      $e.remove();
+    });
+  });
+}
+</script>
+
+## Internal Select2 events
+
+Select2 has an internal event system that works independently of the DOM event system. This internal event system is only accessible from plugins and adapters that are connected to Select2.

pages/10.programmatic-control/chapter.md

@@ -0,0 +1,9 @@
+---
+title: Programmatic control
+taxonomy:
+    category: docs
+---
+
+### Chapter 3
+
+# Programmatic Control

pages/11.i18n/docs.md

@@ -0,0 +1,77 @@
+---
+title: Internationalization
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+## Multiple languages (localization)
+
+Select2 supports displaying the messages in different languages, as well
+as providing your own
+<a href="options.html#language">custom messages</a>
+that can be displayed.
+
+The language does not have to be defined when Select2 is being
+initialized, but instead can be defined in the <code>[lang]</code>
+attribute of any parent elements as <code>[lang="es"]</code>.
+
+<div class="s2-example">
+    <p>
+      <select class="js-example-language js-states form-control">
+      </select>
+    </p>
+</div>
+
+```
+$(".js-example-language").select2({
+  language: "es"
+});
+```
+
+## RTL support
+
+Select2 will work on RTL websites if the <code>dir</code> attribute is
+set on the <code>&lt;select&gt;</code> or any parents of it. You can also
+initialize Select2 with <code>dir: "rtl"</code> set.
+
+<div class="s2-example">
+    <p>
+      <select class="js-example-rtl js-states form-control" dir="rtl"></select>
+    </p>
+</div>
+
+```
+$(".js-example-rtl").select2({
+  dir: "rtl"
+});
+```
+
+## Transliteration support (diacritics)
+
+Select2's default matcher will ignore diacritics, making it easier for
+users to filter results in international selects. Type "aero" into the
+select below.
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-diacritics form-control">
+      <option>Aeróbics</option>
+      <option>Aeróbics en Agua</option>
+      <option>Aerografía</option>
+      <option>Aeromodelaje</option>
+      <option>Águilas</option>
+      <option>Ajedrez</option>
+      <option>Ala Delta</option>
+      <option>Álbumes de Música</option>
+      <option>Alusivos</option>
+      <option>Análisis de Escritura a Mano</option>
+    </select>
+  </p>
+</div>
+
+```
+$(".js-example-diacritics").select2();
+```

pages/12.advanced/adapters.html

@@ -0,0 +1,209 @@
+<section>
+  <div class="page-header">
+    <h1 id="adapters">Adapters</h1>
+  </div>
+
+  <p>
+    Select2 allows plugins to add additional functionality through the core
+    adapters. You can change almost anything involving the way Select2 works
+    to the way Select2 interacts with the page by modifying the core adapters.
+    Most third-party plugins should provide decorators (used to wrap adapters)
+    and custom adapters that you can use.
+  </p>
+
+  <p>
+    Each adapter contains a set of methods which will must always be defined.
+    Along with the global methods that all adapters must implement, these
+    methods must be implemented.
+  </p>
+
+  <h2 id="adapters-all">
+    All adapters
+  </h2>
+
+  <p>
+    All adapters must implement a set of methods that Select2 will use to
+    display them and bind any internal events.
+  </p>
+
+<pre class="prettyprint linenums">
+// The basic HTML that should be rendered by Select2. A jQuery or DOM element
+// should be returned, which will automatically be placed by Select2 within the
+// DOM.
+//
+// @returns A jQuery or DOM element that contains any elements that must be
+//   rendered by Select2.
+Adapter.render = function () {
+  return $jq;
+};
+
+// Bind to any Select2 or DOM events.
+//
+// @param container The Select2 object that is bound to the jQuery element.  You
+//   can listen to Select2 events with `on` and trigger Select2 events using the
+//   `trigger` method.
+// @param $container The jQuery DOM node that all default adapters will be
+//   rendered within.
+Adapter.bind = function (container, $container) { };
+
+// Position the DOM element within the Select2 DOM container, or in another
+// place. This allows adapters to be located outside of the Select2 DOM,
+// such as at the end of the document or in a specific place within the Select2
+// DOM node.
+//
+// Note: This method is not called on data adapters.
+//
+// @param $rendered The rendered DOM element that was returned from the call to
+//   `render`. This may have been modified by Select2, but the root element
+//   will always be the same.
+// @param $defaultContainer The default container that Select2 will typically
+//   place the rendered DOM element within. For most adapters, this is the
+//   Select2 DOM element.
+Adapter.position = function ($rendered, $defaultContainer) { };
+
+// Destroy any events or DOM elements that have been created.
+// This is called when `select2("destroy")` is called on an element.
+Adapter.destroy = function () { };
+</pre>
+
+  <h2 id="selectionAdapter">
+    Container (selection)
+  </h2>
+
+  <p>
+    The selection is what is shown to the user as a replacement of the
+    standard <code>&lt;select&gt;</code> box. It controls the display of the
+    selection option(s), as well anything else that needs to be embedded
+    within the container, such as a search box.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd>
+      <code>selectionAdapter</code>
+    </dd>
+
+    <dt>Default</dt>
+    <dd>
+      <code title="select2/selection/single">SingleSelection</code> or
+      <code title="select2/selection/multiple">MultipleSelection</code>
+    </dd>
+
+    <dt>Base</dt>
+    <dd>
+      <code title="select2/selection/base">BaseSelection</code>
+    </dd>
+  </dl>
+
+<pre class="prettyprint linenums">
+// Update the selected data.
+//
+// @param data An array of data objects that have been generated by the data
+//   adapter. If no objects should be selected, an empty array will be passed.
+//
+// Note: An array will always be passed into this method, even if Select2 is
+// attached to a source which only accepts a single selection.
+SelectionAdapter.update = function (data) { };
+</pre>
+
+  <h2 id="dataAdapter">
+    Data set
+  </h2>
+
+  <p>
+    The data set is what Select2 uses to generate the possible results that
+    can be selected, as well as the currently selected results.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd>
+      <code>dataAdapter</code>
+    </dd>
+
+    <dt>Default</dt>
+    <dd>
+      <code title="select2/data/select">SelectAdapter</code>
+    </dd>
+
+    <dt>Base</dt>
+    <dd>
+      <code title="select2/data/base">BaseAdapter</code>
+    </dd>
+  </dl>
+
+<pre class="prettyprint linenums">
+// Get the currently selected options. This is called when trying to get the
+// initial selection for Select2, as well as when Select2 needs to determine
+// what options within the results are selected.
+//
+// @param callback A function that should be called when the current selection
+//   has been retrieved. The first parameter to the function should be an array
+//   of data objects.
+DataAdapter.current = function (callback) {
+  callback(currentData);
+}
+
+// Get a set of options that are filtered based on the parameters that have
+// been passed on in.
+//
+// @param params An object containing any number of parameters that the query
+//   could be affected by. Only the core parameters will be documented.
+// @param params.term A user-supplied term. This is typically the value of the
+//   search box, if one exists, but can also be an empty string or null value.
+// @param params.page The specific page that should be loaded. This is typically
+//   provided when working with remote data sets, which rely on pagination to
+//   determine what objects should be displayed.
+// @param callback The function that should be called with the queried results.
+DataAdapter.query = function (params, callback) {
+  callback(queryiedData);
+}
+</pre>
+
+  <h2 id="dropdownAdapter">
+    Dropdown
+  </h2>
+
+  <p>
+    The dropdown adapter defines the main container that the dropdown should
+    be held in. <strong>It does not define any extra methods that can be used
+    for decorators</strong>, but it is common for decorators to attach to the
+    <code>render</code> and <code>position</code> methods to alter how the
+    dropdown is altered and positioned.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd>
+      <code>dropdownAdapter</code>
+    </dd>
+
+    <dt>Default</dt>
+    <dd>
+      <code title="select2/dropdown">DropdownAdapter</code>
+    </dd>
+  </dl>
+
+  <h2 id="resultsAdapter">
+    Results
+  </h2>
+
+  <p>
+    The results adapter controls the list of results that the user can select
+    from. While the results adapter does not define any additional methods
+    that must be implemented, it makes extensive use of the Select2 event
+    system for controlling the display of results and messages.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd>
+      <code>resultsAdapter</code>
+    </dd>
+
+    <dt>Default</dt>
+    <dd>
+      <code title="select2/results">ResultsAdapter</code>
+    </dd>
+  </dl>
+</section>

pages/12.advanced/backwards-compatibility.html

@@ -0,0 +1,200 @@
+<section>
+  <div class="page-header">
+    <h1 id="compatibility">Backwards compatibility</h1>
+  </div>
+
+  <p>
+    Select2 offers limited backwards compatibility with the previously 3.5.x
+    release line, allowing people more efficiently transfer across releases
+    and get the latest features. For many of the larger changes, such as the
+    change in how custom data adapters work, compatibility modules were
+    created that will be used to assist in the upgrade process. It is not
+    recommended to rely on these compatibility modules, as they will not
+    always exist, but they make upgrading easier for major changes.
+  </p>
+
+  <p>
+    <strong>The compatibility modules are only included in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2</strong>. These files end in <code>.full.js</code>, and the
+    compatibility modules are prefixed with <code>select2/compat</code>.
+  </p>
+
+  <h2 id="compat-matcher">
+    Simplified function for matching data objects
+  </h2>
+
+  <p class="alert alert-info">
+    <a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
+    This method was added to make upgrading easier from earlier versions of
+    Select2.
+  </p>
+
+  <p>
+    During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
+    <code>matcher</code> function was changed to allow for more complex
+    matching of nested objects.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>matcher</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking a search <code>term</code> and the data object
+          <code>text</code>.
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/compat/matcher">oldMatcher</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    The <a href="examples.html#matcher">custom matcher example</a> provides a
+    guide for how to use this in your own application. For those upgrading
+    from older versions of Select2, you just need to wrap your old
+    <code>matcher</code> with this function to maintain compatibility.
+  </p>
+
+  <h2 id="initSelection">
+    Old initial selections with <code>initSelection</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
+    This has been replaced by another option and is only available in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2.
+  </p>
+
+  <p>
+    In the past, Select2 required an option called <code>initSelection</code>
+    that was defined whenever a custom data source was being used, allowing
+    for the initial selection for the component to be determined. This has
+    been replaced by the <code>current</code> method on the
+    <a href="#dataAdapter">data adapter</a>.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>initSelection</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking a <code>callback</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/compat/initSelection">InitSelection</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <h2 id="query">
+    Querying old data with <code>query</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
+    This has been replaced by another option and is only available in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2.
+  </p>
+
+  <p>
+    In the past, Select2 supported an option called <code>query</code> that
+    allowed for a custom data source to be used. This option has been replaced
+    by the <code>query</code> method on the
+    <a href="#dataAdapter">data adapter</a> and takes a very similar set of
+    parameters.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>query</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking <code>params</code> (including a <code>callback</code>)
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/compat/query">Query</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <h2 id="input-fallback">
+    Compatibility with <code>&lt;input type="text" /&gt;</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#hidden-input" class="alert-link">Deprecated in Select2 4.0.</a>
+    It is now encouraged to use the <code>&lt;select&gt;</code> tag instead.
+  </p>
+
+  <p>
+    In past versions of Select2, a <code>&lt;select&gt;</code> element could
+    only be used with a limited subset of options. An
+    <code>&lt;input type="hidden" /&gt;</code> was required instead, which did
+    not allow for a graceful fallback for users who did not have JavaScript
+    enabled. Select2 now supports the <code>&lt;select&gt;</code> element for
+    all options, so it is no longer required to use <code>&lt;input /&gt;</code>
+    elements with Select2.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Adapter</dt>
+    <dd>
+      <code title="select2/data/base">DataAdapter</code>
+    </dd>
+
+    <dt>Decorator</dt>
+    <dd>
+      <code title="select2/compat/inputData">InputData</code>
+    </dd>
+  </dl>
+</section>

pages/12.advanced/core-options.html

@@ -0,0 +1,790 @@
+<section>
+  <h1 id="core-options" class="page-header">Core options</h1>
+
+  <p>
+    Select2 supports a small subset of options in every build that is
+    generated. Each option typically has a decorator that is required that
+    wraps an adapter, adding support for the option. This is only required
+    when a custom adapter is being used, as Select2 will build the required
+    adapters by default.
+  </p>
+
+  <p>
+    Select2 will automatically apply decorators to any adapters which have not
+    been manually overridden. The only time you need to decorate adapters is
+    when you are using third-party adapters not provided by Select2, or you
+    are using features not provided in the Select2 core. You can apply a
+    decorator to an adapter using the
+    <code title="select2/utils">Utils.Decorate</code> method provided with
+    Select2.
+  </p>
+
+<pre class="prettyprint linenums">
+$.fn.select2.amd.require(
+    ["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
+    function (Utils, SingleSelection, Placeholder) {
+  var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
+});
+</pre>
+
+  <p>
+    All core options that use decorators or adapters will clearly state it
+    in the "Decorator" or "Adapter" part of the documentation. Decorators are
+    typically only compatible with a specific type of adapter, so make sure to
+    note what adapter is given.
+  </p>
+
+  <h2 id="data-attributes">
+    Declaring configuration in the <code>data-*</code> attributes
+  </h2>
+
+  <p>
+    It is recommended that you declare your configuration options for Select2
+    when initializing Select2. You can also define your configuration options
+    by using the HTML5 <code>data-*</code> attributes, which will override
+    any options set when initializing Select2 and any defaults.
+  </p>
+
+  <p>
+    This means that if you declare your <code>&lt;select&gt;</code> tag as...
+  </p>
+
+<pre class="prettyprint">
+&lt;select data-tags="true" data-placeholder="Select an option"&gt;&lt;/select&gt;
+</pre>
+
+  <p>
+    Will be interpreted the same as initializing Select2 as...
+  </p>
+
+<pre class="prettyprint linenums">
+$("select").select2({
+  tags: "true",
+  placeholder: "Select an option"
+});
+</pre>
+
+  <p>
+    You can also define nested configurations, which are typically needed for
+    options such as AJAX. Each level of nesting should be separated by two
+    dashes (<code>--</code>) instead of one. Due to
+    <a href="https://github.com/jquery/jquery/issues/2070">a jQuery bug</a>,
+    nested options using <code>data-*</code> attributes
+    <a href="https://github.com/select2/select2/issues/2969">do not work in jQuery 1.x</a>.
+  </p>
+
+<pre class="prettyprint">
+&lt;select data-ajax--url="http://example.org/api/test" data-ajax--cache="true"&gt;&lt;/select&gt;
+</pre>
+
+  <p>
+    Which will be interpreted the same as initializing Select2 with...
+  </p>
+
+<pre class="prettyprint linenums">
+$("select").select2({
+  ajax: {
+    url: "http://example.org/api/test",
+    cache: "true"
+  }
+});
+</pre>
+
+  <p>
+    The value of the option is subject to jQuery's
+    <a href="https://api.jquery.com/data/#data-html5">parsing rules</a> for
+    HTML5 data attributes.
+  </p>
+
+  <h2 id="amd">
+    AMD compatibility
+  </h2>
+
+  <p>
+    You can find more information on how to integrate Select2 with your
+    existing AMD-based project by
+    <a href="announcements-4.0.html#builds">viewing the 4.0 release notes</a>.
+    Select2 automatically loads some modules when the adapters are being
+    automatically constructed, so those who are using Select2 with a custom
+    AMD build using their own system may need to specify the paths that are
+    generated to the Select2 modules.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>amdBase</code>
+        </dd>
+
+        <dt>Default</dt>
+        <dd>
+          <code>select2/</code>
+        </dd>
+      </dl>
+    </div>
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>amdLanguageBase</code>
+        </dd>
+
+        <dt>Default</dt>
+        <dd>
+          <code>select2/i18n/</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <h2 id="core-options-display">
+    Displaying selections
+  </h2>
+
+  <p>
+    Select2 provides options that allow you to directly affect how the
+    container that holds the current selection is displayed.
+  </p>
+
+  <h3 id="placeholder">
+    Placeholders
+  </h3>
+
+  <p>
+    Select2 can display a placeholder for a single-value select that will
+    replace an option, or be shown when no options are selected for
+    multiple-value selects. You can find an example on the
+    <a href="examples.html#placeholders">example page</a>.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>placeholder</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>string or object</dd>
+      </dl>
+
+      <hr />
+
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/selection/base">SelectionAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/selection/placeholder">Placeholder</code>
+          and
+          <code title="select2/dropdown/hidePlaceholder">HidePlaceholder</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <div class="alert alert-warning">
+        <strong>Heads up!</strong>
+        Because browsers assume that the first <code>option</code> in
+        single-value select boxes is selected, you should add an empty
+        <code>&lt;option&gt;&lt;/option&gt;</code> tag that the placeholder
+        should use or it may not work.
+      </div>
+    </div>
+  </div>
+
+  <p>
+    If the <strong>value is a string</strong>, the placeholder will be
+    displayed when a <strong>blank option</strong> is used as the placeholder.
+    The <strong>value</strong> will be the message to show to users as the
+    placeholders.
+  </p>
+
+<pre class="prettyprint">
+placeholder: "Select a repository"
+</pre>
+
+      <p>
+        If the <strong>value is an object</strong>, the object should be
+        compatible with Select2's internal objects. The <code>id</code> should
+        be the id to look for when determining if the placeholder should be
+        displayed. The <code>text</code> should be the placeholder to display
+        when that option is selected.
+      </p>
+
+<pre class="prettyprint linenums">
+placeholder: {
+  id: "-1",
+  text: "Select a repository"
+}
+</pre>
+
+  <div class="alert alert-info">
+    You should <strong>pass in an object</strong> when you are using a
+    framework that <strong>creates its own placeholder option</strong>. The
+    <strong>id</strong> should be the same as the <code>value</code>
+    attribute on the <code>option</code>.
+  </div>
+
+  <p id="allowClear">
+    You can allow a selected option to be cleared back to the placeholder by
+    enabling the <code>allowClear</code> option.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>allowClear</code></dd>
+
+        <dt>Value</dt>
+        <dd>boolean</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/selection/base">SelectionAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/selection/allowClear">AllowClear</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    This will display an "x" that the user can click to clear the current
+    selection. It is designed to be used for cases where a single selection
+    can be made.
+  </p>
+
+  <h3 id="multiple">
+    Multiple selections
+  </h3>
+
+  <p>
+    Select2 can display either a single selection or multiple selections.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd><code>multiple</code></dd>
+
+    <dt>Value</dt>
+    <dd>boolean (<code>true</code> or <code>false</code>)</dd>
+  </dl>
+
+  <p>
+    This option will determine what the <code>SelectAdapter</code> (used by
+    default) should use to set the value of the underlying <code>select</code>
+    element. It will also determine if the <code>MultipleSelection</code>
+    adapter should be used.
+  </p>
+
+  <h3 id="width">
+    Container width
+  </h3>
+
+  <p>
+    Select2 will try to match the width of the original element as closely as
+    possible. Sometimes this isn't perfect, which is what you can tell Select2
+    how to determine the width.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <table class="table table-striped table-bordered">
+        <thead>
+          <tr>
+            <th>Value</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>"element"</code></td>
+            <td>
+              Uses javascript to calculate the width of the source element.
+            </td>
+          </tr>
+          <tr>
+            <td><code>"style"</code></td>
+            <td>
+              Copies the value of the width <code>style</code> attribute set on the source element.
+            </td>
+          </tr>
+          <tr>
+            <td><code>"resolve"</code></td>
+            <td>
+              Tries to use <code>style</code> to determine the width, falling back to <code>element</code>.
+            </td>
+          </tr>
+          <tr>
+            <td>Anything else</td>
+            <td>
+              The value of the <code>width</code> option is directly set as the width of the container.
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>width</code></dd>
+
+        <dt>Value</dt>
+        <dd>string</dd>
+      </dl>
+    </div>
+  </div>
+
+  <h3 id="language">
+    Internationalization (Language support)
+  </h3>
+
+  <p>
+    Messages will be displayed to users when necessary, such as when no
+    search results were found or more characters need to be entered in order
+    for a search to be made. These messages have been
+    <a href="community.html#translations">translated into many languages</a>
+    by contributors to Select2, but you can also provide your own
+    translations.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>language</code></dd>
+
+        <dt>Value</dt>
+        <dd>object or string</dd>
+      </dl>
+
+      <hr />
+
+      <dl class="dl-horizontal">
+        <dt>Module</dt>
+        <dd>
+          <code title="select2/translation">Translation</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <p class="alert alert-warning">
+        <strong>Heads up!</strong> When using translations provided by Select2,
+        you must make sure to include the translation file in your page after
+        Select2.
+      </p>
+    </div>
+  </div>
+
+  <p>
+    When a string is passed in as the language, Select2 will try to resolve
+    it into a language file. This allows you to specify your own language
+    files, which must be defined as an AMD module. If the language file
+    cannot be found, Select2 will assume it is a language code controlled by
+    Select2, and it will try to load the translations for that language
+    instead.
+  </p>
+
+  <p>
+    You can include your own translations by providing an object similar to
+    the one below.
+  </p>
+
+<pre class="prettyprint linenums">
+language: {
+  // You can find all of the options in the language files provided in the
+  // build. They all must be functions that return the string that should be
+  // displayed.
+  inputTooShort: function () {
+    return "You must enter more characters...";
+  }
+}
+</pre>
+
+  <h3 id="templating">
+    Templating results and selections
+  </h3>
+
+  <p>
+    By default, Select2 will display the option text within the list of
+    results and when the option has been selected.  Select2 comes with options
+    that allow you to further customize the display of results and selections,
+    allowing you to display them however you want.
+  </p>
+
+  <h4 id="templateSelection">
+    Customizing the display of selections
+  </h4>
+
+  <p>
+    When an option is displayed after it has been selected, it is passed
+    through a formatting function that determines what is displayed. By
+    default, the function only returns the <code>text</code> key of the data
+    object.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd><code>templateSelection</code></dd>
+
+    <dt>Value</dt>
+    <dd>A function taking a <code>selection</code> object</dd>
+  </dl>
+
+  <div class="alert alert-info">
+    <strong>Anything rendered as a selection is templated.</strong>
+    This includes placeholders and pre-existing selections that are displayed,
+    so you must ensure that your templating functions can support them.
+  </div>
+
+  <p>
+    The <code>templateSelection</code> function should return a string
+    containing the text to be displayed, or an object (such as a jQuery
+    object) that contains the data that should be displayed.
+  </p>
+
+  <p>
+    <strong>Strings are assumed to contain only text</strong> and will be
+    passed through the <code>escapeMarkup</code> function, which strips any
+    HTML markup.
+  </p>
+
+  <p>
+    <strong>
+      Anything else will be passed
+      <a href="https://api.jquery.com/append/">directly to <code>jQuery.fn.append</code></a>
+    </strong> and will be handled directly by jQuery.  Any markup, such as
+    HTML, returned will not be escaped and it is up to you to escape any
+    malicious input provided by users.
+  </p>
+
+  <h4 id="templateResult">
+    Customizing the display of results
+  </h4>
+
+  <p>
+    When an option is displayed after it has been selected, it is passed
+    through a formatting function that determines what is displayed. By
+    default, the function only returns the <code>text</code> key of the data
+    object.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd><code>templateResult</code></dd>
+
+    <dt>Value</dt>
+    <dd>A function taking a <code>result</code> object</dd>
+  </dl>
+
+  <div class="alert alert-info">
+    <strong>Anything rendered in the results is templated.</strong>
+    This includes results such as the "Searching..." and "Loading more..."
+    text which will periodically be displayed, which allows you to add more
+    advanced formatting to these automatically generated options.
+  </div>
+
+  <p>
+    The <code>templateResult</code> function should return a string
+    containing the text to be displayed, or an object (such as a jQuery
+    object) that contains the data that should be displayed.  It can also
+    return <code>null</code>, which will prevent the option from being
+    displayed in the results list.
+  </p>
+
+  <p>
+    <strong>Strings are assumed to contain only text</strong> and will be
+    passed through the <code>escapeMarkup</code> function, which strips any
+    HTML markup.
+  </p>
+
+  <p>
+    <strong>
+      Anything else will be passed
+      <a href="https://api.jquery.com/append/">directly to <code>jQuery.fn.append</code></a>
+    </strong> and will be handled directly by jQuery.  Any markup, such as
+    HTML, returned will not be escaped and it is up to you to escape any
+    malicious input provided by users.
+  </p>
+
+  <h2 id="core-options-results">
+    Returning and displaying results
+  </h2>
+
+  <p>
+    Select2 can work on many different data sets ranging from local options,
+    the same way that a <code>&lt;select&gt;</code> typically works, from
+    remote options where a server generates the results that users can select
+    from.
+  </p>
+
+  <h3 id="data">
+    Array
+  </h3>
+
+  <p>
+    Select2 allows creating the results based on an array of data objects that
+    is included when initializing Select2.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>data</code></dd>
+
+        <dt>Value</dt>
+        <dd>array of objects</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/array">ArrayAdapter</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    The objects that the users can select from should be passed as an array
+    with each object containing <code>id</code> and <code>text</code>
+    properties.
+  </p>
+
+  <h3 id="ajax">
+    AJAX
+  </h3>
+
+  <p>
+    Select2 allows searching for results from remote data sources using AJAX
+    requests.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>ajax</code></dd>
+
+        <dt>Value</dt>
+        <dd>object</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/ajax">AjaxAdapter</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    All options passed to this option will be directly passed to the
+    <code>$.ajax</code> function that executes AJAX requests. There are a few
+    custom options that Select2 will intercept, allowing you to customize the
+    request as it is being made.
+
+<pre class="prettyprint linenums">
+ajax: {
+  // The number of milliseconds to wait for the user to stop typing before
+  // issuing the ajax request.
+  delay: 250,
+  // You can craft a custom url based on the parameters that are passed into the
+  // request. This is useful if you are using a framework which has
+  // JavaScript-based functions for generating the urls to make requests to.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @returns The url that the request should be made to.
+  url: function (params) {
+    return UrlGenerator.Random();
+  },
+  // You can pass custom data into the request based on the parameters used to
+  // make the request. For `GET` requests, the default method, these are the
+  // query parameters that are appended to the url. For `POST` requests, this
+  // is the form data that will be passed into the request. For other requests,
+  // the data returned from here should be customized based on what jQuery and
+  // your server are expecting.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @returns Data to be directly passed into the request.
+  data: function (params) {
+    var queryParameters = {
+      q: params.term
+    }
+
+    return queryParameters;
+  },
+  // You can modify the results that are returned from the server, allowing you
+  // to make last-minute changes to the data, or find the correct part of the
+  // response to pass to Select2. Keep in mind that results should be passed as
+  // an array of objects.
+  //
+  // @param data The data as it is returned directly by jQuery.
+  // @returns An object containing the results data as well as any required
+  //   metadata that is used by plugins. The object should contain an array of
+  //   data objects as the `results` key.
+  processResults: function (data) {
+    return {
+      results: data
+    };
+  },
+  // You can use a custom AJAX transport function if you do not want to use the
+  // default one provided by jQuery.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @param success A callback function that takes `data`, the results from the
+  //   request.
+  // @param failure A callback function that indicates that the request could
+  //   not be completed.
+  // @returns An object that has an `abort` function that can be called to abort
+  //   the request if needed.
+  transport: function (params, success, failure) {
+    var $request = $.ajax(params);
+
+    $request.then(success);
+    $request.fail(failure);
+
+    return $request;
+  }
+}
+</pre>
+  </p>
+
+  <h3 id="tags">
+    Tags
+  </h3>
+
+  <p>
+    Users can create their own options based on the text that they have
+    entered.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>tags</code></dd>
+
+        <dt>Value</dt>
+        <dd>boolean / array of objects</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/data/tags">Tags</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    If the <code>tags</code> option is passed into Select2, if a user types
+    anything into the search box which doesn't already exist, it will be
+    displayed at the top and the user will be able to select it.
+  </p>
+
+  <p>
+    <strong>For backwards compatibility</strong>, if an array of objects is
+    passed in with the <code>tags</code> option, the options will be
+    automatically created and the user will be able to select from them.
+    This is the <strong>same as how <a href="#data">array data</a>
+    works</strong>, and has similar limitations.
+  </p>
+
+  <h3 id="matcher">
+    Change how options are matched when searching
+  </h3>
+
+  <p>
+    When users filter down the results by entering search terms into the
+    search box, Select2 uses an internal "matcher" to match search terms to
+    results. <strong>When a remote data set is used, Select2 expects that the
+    returned results have already been filtered.</strong>
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Key</dt>
+    <dd>
+      <code>matcher</code>
+    </dd>
+
+    <dt>Value</dt>
+    <dd>
+      A function taking search <code>params</code> and the
+      <code>data</code> object.
+    </dd>
+  </dl>
+
+  <p>
+    Select2 will pass the individual data objects that have been passed back
+    from the data adapter into the <code>matcher</code> individually to
+    determine if they should be displayed. Only the first-level objects will
+    be passed in, so <strong>if you are working with nested data, you need to
+    match those individually</strong>.
+  </p>
+
+<pre class="prettyprint linenums">
+matcher: function (params, data) {
+  // If there are no search terms, return all of the data
+  if ($.trim(params.term) === '') {
+    return data;
+  }
+
+  // `params.term` should be the term that is used for searching
+  // `data.text` is the text that is displayed for the data object
+  if (data.text.indexOf(params.term) > -1) {
+    var modifiedData = $.extend({}, data, true);
+    modifiedData.text += ' (matched)';
+
+    // You can return modified objects from here
+    // This includes matching the `children` how you want in nested data sets
+    return modifiedData;
+  }
+
+  // Return `null` if the term should not be displayed
+  return null;
+}
+</pre>
+
+  <p>
+    This allows for more advanced matching when working with nested objects,
+    allowing you to handle them however you want. For those who are not
+    looking to implement highly customized matching, but instead are just
+    looking to change the matching algorithm for the text, a
+    <a href="#compat-matcher">compatibility modules</a> has been created to
+    make it easier.
+  </p>
+</section>

pages/12.advanced/dropdown.html

@@ -0,0 +1,308 @@
+<section>
+  <div class="page-header">
+    <h1 id="dropdown">Dropdown</h1>
+  </div>
+
+  <p>
+    Select2 allows you to change the way that the dropdown works, allowing you
+    to do anything from attach it to a different location in the document or
+    add a search box.
+  </p>
+
+  <h2 id="dropdownParent">
+    Attached to body
+  </h2>
+
+  <p>
+    By default, Select2 will attach the dropdown to the end of the body and
+    will absolutely position it to appear below the selection container.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>dropdownParent</code></dd>
+
+        <dt>Value</dt>
+        <dd>jQuery element or DOM node</dd>
+
+        <hr />
+
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/dropdown">DropdownAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/dropdown/attachBody">AttachBody</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <div class="alert alert-warning">
+        <strong>Heads up!</strong>
+        This will cause DOM events to be raised outside of the standard
+        Select2 DOM container. This can cause issues with
+        third-party components such as modals.
+      </div>
+    </div>
+  </div>
+
+  <p>
+    When the dropdown is attached to the body, you are not limited to just
+    displaying the dropdown below the container. Select2 will display above
+    the container if there is not enough space below the container, but there
+    is enough space above it. You are also not limited to displaying the
+    dropdown within the parent container, which means Select2 will render
+    correctly inside of modals and other small containers.
+  </p>
+
+  <h2 id="dropdown-attachContainer">
+    Attached below the container
+  </h2>
+
+  <p>
+    Select2 can place the dropdown directly after the selection container, so
+    it will appear in the same location within the DOM as the rest of Select2.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/dropdown">DropdownAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/dropdown/attachContainer">AttachContainer</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <div class="alert alert-warning">
+        <strong>Check your build.</strong> This module is only included in the
+        <a href="index.html#builds-full" class="alert-link">full builds</a> of
+        Select2.
+      </div>
+    </div>
+  </div>
+
+  <div class="alert alert-info">
+    <strong>
+      <a href="https://harvesthq.github.io/chosen/">Harvest Chosen</a>
+      migrators!
+    </strong>
+    If you are migrating to Select2 from Chosen, this option will cause
+    Select2 to position the dropdown in a similar way.
+  </div>
+
+  <h2 id="dropdown-search">
+    Search
+  </h2>
+
+  <p>
+    Users can filter down the results by typing a search term into a box that
+    is displayed at the top of the dropdown.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Adapter</dt>
+    <dd>
+      <code title="select2/dropdown">DropdownAdapter</code>
+    </dd>
+
+    <dt>Decorator</dt>
+    <dd>
+      <code title="select2/dropdown/search">DropdownSearch</code>
+    </dd>
+  </dl>
+
+  <p>
+    A search box is added to the top of the dropdown automatically for select
+    boxes where only a single option can be selected.
+  </p>
+
+  <h3 id="dropdown-minimumInputLength">
+    Minimum search term length to filter results
+  </h3>
+
+  <p>
+    Sometimes when working with large data sets, it is more efficient to start
+    filtering the results when the search term is a certain length. This is
+    very common when working with remote data sets, as allows for only
+    significant search terms to be used.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>minimumInputLength</code></dd>
+
+        <dt>Value</dt>
+        <dd>integer</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/data/minimumInputLength">MinimumInputLength</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <h3 id="dropdown-maximumInputLength">
+    Maximum search term length to filter results
+  </h3>
+
+  <p>
+    In some cases, search terms need to be limited to a certain range. Select2
+    allows you to limit the length of the search term such that it does not
+    exceed a certain length.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>maximumInputLength</code></dd>
+
+        <dt>Value</dt>
+        <dd>integer</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/data/maximumInputLength">MaximumInputLength</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <h3 id="dropdown-maximumInputLength">
+    Minimum results to display the search box
+  </h3>
+
+  <p>
+    When working with smaller data sets, the search box can take up more space
+    that is necessary, as there are not enough results for filtering to be
+    effective. Select2 allows you to only display the search box when the
+    number of search results reaches a certain threshold.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>minimumResultsForSearch</code></dd>
+
+        <dt>Value</dt>
+        <dd>integer</dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/dropdown">DropdownAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/dropdown/minimumResultsForSearch">MinimumResultsForSearch</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <h2 id="dropdown-select-on-close">
+    Select the highlighted option on close
+  </h2>
+
+  <p>
+    When users close the dropdown, the last highlighted option can be
+    automatically selected. This is commonly used in combination with
+    <a href="#tags">tagging</a> and <a href="#placeholder">placeholders</a>
+    and other situations where the user is required to select an option, or
+    they need to be able to quickly select multiple options.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Adapter</dt>
+    <dd>
+      <code title="select2/results">ResultsAdapter</code>
+    </dd>
+
+    <dt>Decorator</dt>
+    <dd>
+      <code title="select2/dropdown/selectOnClose">SelectOnClose</code>
+    </dd>
+  </dl>
+
+  <h2 id="closeOnSelect">
+    Close the dropdown when a result is selected
+  </h2>
+
+  <p>
+    Select2 will automatically close the dropdown when an element is selected,
+    similar to what is done with a normal select box.  This behavior can be
+    changed though to keep the dropdown open when results are selected,
+    allowing for multiple options to be selected quickly.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd><code>closeOnSelect</code></dd>
+
+        <dt>Default</dt>
+        <dd><code>true</code></dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/dropdown">DropdownAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/dropdown/closeOnSelect">CloseOnSelect</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    If this decorator is not used (or <code>closeOnSelect</code> is set to
+    <code>false</code>), the dropdown will not automatically close when a
+    result is selected.  The dropdown will also never close if the
+    <kbd>ctrl</kbd> key is held down when the result is selected.
+  </p>
+</section>

pages/12.advanced/events.html

@@ -0,0 +1,50 @@
+<section>
+  <div id="events" class="page-header">
+    <h1>Events</h1>
+  </div>
+
+  <p>
+    Select2 has an internal event system that is used to notify parts of the
+    component that state has changed, as well as an adapter that allows some
+    of these events to be relayed to the outside word.
+  </p>
+
+  <dl class="dl-horizontal">
+    <dt>Adapter</dt>
+    <dd>
+      <code title="select2/selection">SelectionAdapter</code>
+    </dd>
+
+    <dt>Decorator</dt>
+    <dd>
+      <code title="select2/selection/eventRelay">EventRelay</code>
+    </dd>
+  </dl>
+
+  <h2 id="events-public">
+    Public events
+  </h2>
+
+  <p>
+    All public events are relayed using the jQuery event system, and they are
+    triggered on the <code>&lt;select&gt;</code> element that Select2 is
+    attached to. You can attach to them using the
+    <a href="https://api.jquery.com/on/"><code>.on</code> method</a> provided
+    by jQuery.
+  </p>
+
+  <h2 id="events-internal">
+    Internal events
+  </h2>
+
+  <p>
+    Select2 triggers internal events using its own internal event system,
+    which allows adapters to communicate with each other. These events are not
+    accessible through the jQuery event system.
+  </p>
+
+  <p>
+    You can find more information on the public events triggered by individual
+    adapters in <a href="#adapters">the individual adapter documentation</a>.
+  </p>
+</section>

pages/12.advanced/setting-default-options.html

@@ -0,0 +1,37 @@
+<section>
+  <h1 id="setting-default-options">Setting default options</h1>
+
+  <p>
+    In some cases, you need to set the default options for all instances of
+    Select2 in your web application. This is especially useful when you are
+    migrating from past versions of Select2, or you are using non-standard
+    options <a href="#amd">like custom AMD builds</a>. Select2 exposes the
+    default options through <code>$.fn.select2.defaults</code>, which allows
+    you to set them globally.
+  </p>
+
+  <p>
+    When setting options globally, any past defaults that have been set will
+    be overriden. Default options are only used when an option is requested
+    that has not been set during initialization.
+  </p>
+
+  <p>
+    <strong>You can set default options</strong> by calling
+    <code>$.fn.select2.defaults.set("key", "value")</code>. The key that is
+    set should take the same format as keys set using
+    <a href="#data-attributes">HTML <code>data-*</code> attributes</a> which
+    means that two dashes (<code>--</code>) will be replaced by a level of
+    nesting, and a single dash (<code>-</code>) will convert it to a camelCase
+    string.
+  </p>
+
+<pre class="prettyprint">
+$.fn.select2.defaults.set("theme", "classic");
+</pre>
+
+  <p>
+    <strong>You can reset the default options</strong> by calling
+    <code>$.fn.select2.defaults.reset()</code>.
+  </p>
+</section>

plugins/anchors/CHANGELOG.md

@@ -0,0 +1,36 @@
+# v1.5.1
+## 07/14/2016
+
+1. [](#improved)
+    * Translate some blueprint options
+
+# v1.5.0
+## 01/06/2016
+
+1. [](#improved)
+    * Disable anchors in Admin
+
+# v1.4.0
+## 08/25/2015
+
+1. [](#improved)
+    * Added blueprints for Grav Admin plugin
+
+# v1.3.0
+## 07/20/2015
+
+1. [](#new)
+    * Updated `anchors.js` to version 1.2.1
+    * Added new options such as 'placement', 'visible', 'icon' and 'class'
+
+# v1.2.0
+## 03/01/2015
+
+1. [](#new)
+    * Updated `anchors.js` to version 0.3.0
+
+# v1.1.0
+## 11/30/2014
+
+1. [](#new)
+    * ChangeLog started...

plugins/anchors/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Grav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/anchors/README.md

@@ -0,0 +1,84 @@
+# Grav Anchors Plugin
+
+
+`anchors` is a [Grav](http://github.com/getgrav/grav) plugin that provides automatic header anchors via the [anchorjs](http://bryanbraun.github.io/anchorjs) jQuery plugin.
+
+# Installation
+
+## GPM Installation (Preferred)
+
+The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm).  From the root of your Grav install type:
+
+    bin/gpm install anchors
+
+## Manual Installation
+
+If for some reason you can't use GPM you can manually install this plugin. Download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `anchors`.
+
+You should now have all the plugin files under
+
+	/your/site/grav/user/plugins/anchors
+
+# Usage
+
+To best understand how Anchors works, you should read through the original [project documentation](https://github.com/bryanbraun/anchorjs).
+
+## Configuration:
+
+Simply copy the `user/plugins/breadcrumbs/anchors.yaml` into `user/config/plugins/anchors.yaml` and make your modifications.
+
+    enabled: true                 # enable or disable the plugin
+    active: true                  # active by default, if false then you must activate per-page
+    selectors: 'h1,h2,h3,h4'      # css elements to activate on.  Uses jQuery style selectors
+    placement: right              # either "left" or "right"
+    visible: hover                # Active on "hover" or "always" visible
+    icon:                         # default link or a specific character like: #, ¶, ❡, and §.
+    class:                        # adds the provided class to the anchor html
+    truncate: 64                  # truncates the generated ID to the specified character length
+
+You can override any default settings from the page headers:
+
+eg:
+
+    ---
+    title: Sample Code With Custom Theme
+    anchors:
+        active: true
+        selectors: .blog h1, .blog h2
+    ---
+
+    # Header
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas accumsan porta diam,
+    nec sagittis odio euismod nec. Etiam eu rutrum eros.
+
+    ## Sub Header
+
+    Proin commodo lobortis elementum.
+    Integer vel ultrices massa, nec ornare urna. Phasellus tincidunt rutrum dolor, vestibulum
+    faucibus ligula laoreet id. Donec hendrerit arcu vitae lacus mattis facilisis. Praesent
+    tortor nibh, pulvinar nec orci ac, rhoncus pharetra nunc.
+
+
+You can also disable anchors for a particular page if causes issues:
+
+    ---
+    title: Sample Code with Highlight disabled
+    anchors:
+        active: false
+    ---
+
+    # Header
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas accumsan porta diam,
+    nec sagittis odio euismod nec. Etiam eu rutrum eros.
+
+    ## Sub Header
+
+    Proin commodo lobortis elementum.
+    Integer vel ultrices massa, nec ornare urna. Phasellus tincidunt rutrum dolor, vestibulum
+    faucibus ligula laoreet id. Donec hendrerit arcu vitae lacus mattis facilisis. Praesent
+    tortor nibh, pulvinar nec orci ac, rhoncus pharetra nunc.
+
+
+> Note: If you want to see this plugin in action, have a look at [Grav Learn Site](http://learn.getgrav.org)