Merge pull request #3376 from select2/docs-improvements

New documentation theme

.gitignore

@@ -1,2 +1,3 @@
 node_modules
 dist/js/i18n/build.txt
+.sass-cache

docs/_includes/examples/basics.html

@@ -0,0 +1,65 @@
+<section>
+
+  <h1 id="basics" class="page-header">The basics</h1>
+
+  <h2 id="single">Single select boxes</h2>
+
+  <p>
+    Select2 can take a regular select box like this...
+  </p>
+
+  <p>
+    <select class="js-states form-control"></select>
+  </p>
+
+  <p>
+    and turn it into this...
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-basic-single js-states form-control"></select>
+    </p>
+  </div>
+
+  <pre class="code" data-fill-from=".js-code-basic"></pre>
+
+<script type="text/x-example-code" class="js-code-basic">
+$(document).ready(function() {
+  $(".js-example-basic-single").select2();
+});
+
+<select class="js-example-basic-single">
+  <option value="AL">Alabama</option>
+    ...
+  <option value="WY">Wyoming</option>
+</select>
+</script>
+
+  <h2 id="multiple">Multiple select boxes</h2>
+
+  <p>
+    Select2 also supports multi-value select boxes. The select below is declared with the <code>multiple</code> attribute.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-basic-multiple js-states form-control" multiple="multiple"></select>
+    </p>
+  </div>
+
+  <pre data-fill-from=".js-code-multiple"></pre>
+
+<script type="text/x-example-code" class="js-code-multiple">
+$(".js-example-basic-multiple").select2();
+
+<select class="js-example-basic-multiple" multiple="multiple">
+  <option value="AL">Alabama</option>
+    ...
+  <option value="WY">Wyoming</option>
+</select>
+</script>
+
+</section>
+
+</section>

docs/_includes/examples/data.html

@@ -0,0 +1,128 @@
+<section>
+
+  <h1 id="data" class="page-header">
+    Data sources
+  </h1>
+
+  <p>In addition to handling options from a standard <code>&lt;select&gt;</code>, Select2 can also retrieve the results from other data sources.</p>
+
+  <h2 id="data-array" >Loading array data</h2>
+
+  <p>
+    Select2 provides a way to load the data 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.
+  </p>
+
+  <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-data-array"></pre>
+
+<script type="text/x-example-code" class="js-code-data-array">
+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
+})
+
+<select class="js-example-data-array"></select>
+
+<select class="js-example-data-array-selected">
+  <option value="2" selected="selected">duplicate</option>
+</select>
+</script>
+
+  <h2 id="data-ajax" >Loading remote data</h2>
+
+  <p>
+    Select2 comes with AJAX support built in, using jQuery's AJAX methods.
+    In this example, we can search for repositories using GitHub's API.
+  </p>
+
+  <p>
+    <select class="js-example-data-ajax form-control">
+      <option value="3620194" selected="selected">select2/select2</option>
+    </select>
+  </p>
+
+  <p>
+    When using Select2 with remote data, the HTML required for the
+    <code>select</code> is the same as any other Select2. If you need to
+    provide default selections, you just need to include an
+    <code>option</code> for each selection that contains the value and text
+    that should be displayed.
+  </p>
+
+  <pre data-fill-from=".js-code-data-ajax-html"></pre>
+
+  <p>
+    You can configure how Select2 searches for remote data using the
+    <code>ajax</code> option. More information on the individual options
+    that Select2 handles can be found in the
+    <a href="options.html#ajax">options documentation for <code>ajax</code></a>.
+  </p>
+
+  <pre data-fill-from=".js-code-data-ajax"></pre>
+
+  <p>
+    Select2 will pass any options in the <code>ajax</code> object to
+    jQuery's <code>$.ajax</code> function, or the <code>transport</code>
+    function you specify.
+  </p>
+
+<script type="text/x-example-code" class="js-code-data-ajax">
+$(".js-data-example-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, // omitted for brevity, see the source of this page
+  templateSelection: formatRepoSelection // omitted for brevity, see the source of this page
+});
+</script>
+
+<script type="text/x-example-code" class="js-code-data-ajax-html">
+<select class="js-data-example-ajax">
+  <option value="3620194" selected="selected">select2/select2</option>
+</select>
+</script>
+
+</section>

docs/_includes/examples/disabled-mode.html

@@ -0,0 +1,43 @@
+<section>
+
+  <h1 id="disabled">Disabled mode</h1>
+
+  <p>
+    Select2 will response the <code>disabled</code> attribute on
+    <code>&lt;select&gt;</code> elements. You can also initialize Select2
+    with <code>disabled: true</code> to get the same effect.
+  </p>
+
+  <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-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>
+
+</section>

docs/_includes/examples/disabled-results.html

@@ -0,0 +1,32 @@
+<section>
+
+  <h1 id="disabled-results">Disabled results</h1>
+
+  <p>
+    Select2 will correctly handled disabled results, both with data coming
+    from a standard select (when the <code>disabled</code> attribute is set)
+    and from remote sources, where the object has
+    <code>disabled: true</code> set.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <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>
+    </p>
+  </div>
+
+  <pre data-fill-from=".js-code-disabled-results"></pre>
+
+<script type="text/x-example-code" class="js-code-disabled-results">
+<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>
+
+</section>

docs/_includes/examples/hide-search.html

@@ -0,0 +1,25 @@
+<section>
+
+  <h1 id="hide-search">Hiding the search box</h1>
+
+  <p>
+    Select2 allows you to hide the search box depending on the number of
+    options which are displayed. In this example, we use the value
+    <code>Infinity</code> to tell Select2 to never display the search box.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-basic-hide-search js-states form-control"></select>
+    </p>
+  </div>
+
+  <pre data-fill-from=".js-code-hide-search"></pre>
+
+<script type="text/x-example-code" class="js-code-hide-search">
+$(".js-example-basic-hide-search").select2({
+  minimumResultsForSearch: Infinity
+});
+</script>
+
+</section>

docs/_includes/examples/localization-rtl-diacritics.html

@@ -0,0 +1,90 @@
+<section>
+
+  <h1 id="localization-rtl-diacritics" class="page-header">
+    Localization, RTL and diacritics support
+  </h1>
+
+  <h2 id="language">Multiple languages</h2>
+
+  <p>
+    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.
+  </p>
+
+  <p>
+    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>.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-language js-states form-control">
+      </select>
+    </p>
+  </div>
+
+  <pre data-fill-from=".js-code-language"></pre>
+
+<script type="text/x-example-code" class="js-code-language">
+$(".js-example-language").select2({
+  language: "es"
+});
+</script>
+
+  <h2 id="rtl">RTL support</h2>
+
+  <p>
+    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.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-rtl js-states form-control" dir="rtl"></select>
+    </p>
+  </div>
+
+  <pre data-fill-from=".js-code-rtl"></pre>
+
+<script type="text/x-example-code" class="js-code-rtl">
+$(".js-example-rtl").select2({
+  dir: "rtl"
+});
+</script>
+
+  <h2 id="diacritics">Diacritics support</h2>
+
+  <p>
+    Select2's default matcher will ignore diacritics, making it easier for
+    users to filter results in international selects. Type "aero" into the
+    select below.
+  </p>
+
+  <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>
+
+  <pre data-fill-from=".js-code-diacritics"></pre>
+
+<script type="text/x-example-code" class="js-code-diacritics">
+$(".js-example-diacritics").select2();
+</script>
+
+</section>

docs/_includes/examples/matcher.html

@@ -0,0 +1,43 @@
+<section>
+
+  <h1 id="matcher">Customizing how results are matched</h1>
+
+  <p>
+    Unlike other dropdowns on this page, this one matches options only if
+    the term appears in the beginning of the string as opposed to anywhere:
+  </p>
+
+  <p>
+    This custom matcher uses a
+    <a href="options.html#compat-matcher">compatibility module</a> that is
+    only bundled in the
+    <a href="index.html#builds-full">full version of Select2</a>. You also
+    have the option of using a
+    <a href="options.html#matcher">more complex matcher</a>.
+  </p>
+
+  <div class="s2-example">
+    <p>
+      <select class="js-example-matcher-start js-states form-control"></select>
+    </p>
+  </div>
+
+  <pre data-fill-from=".js-code-matcher-start"></pre>
+
+<script type="text/x-example-code" class="js-code-matcher-start">
+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>
+
+</section>

docs/_includes/examples/multiple-max.html

@@ -0,0 +1,28 @@
+<section>
+
+  <h1 id="multiple-max">
+    Limiting the number of selections
+  </h1>
+
+  <p>
+    Select2 multi-value select boxes can set restrictions regarding the
+    maximum number of options selected. The select below is declared with
+    the <code>multiple</code> attribute with <code>maxSelectionLength</code>
+    in the select2 options.
+  </p>
+
+  <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-multiple-limit"></pre>
+
+<script type="text/x-example-code" class="js-code-multiple-limit">
+$(".js-example-basic-multiple-limit").select2({
+  maximumSelectionLength: 2
+});
+</script>
+
+</section>

docs/_includes/examples/placeholders.html

@@ -0,0 +1,37 @@
+<section>
+
+  <h1 id="placeholders">Placeholders</h1>
+
+  <p>
+    A placeholder value can be defined and will be displayed until a
+    selection is made. Select2 uses the <code>placeholder</code> 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>.
+  </p>
+
+  <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>
+
+</section>

docs/_includes/examples/programmatic-control.html

@@ -0,0 +1,156 @@
+<section>
+
+  <h1 id="programmatic-control" class="page-header">
+    Programmatic control
+  </h1>
+
+  <h2 id="events">DOM events</h2>
+
+  <p>
+    Select2 will trigger some events on the original select element,
+    allowing you to integrate it with other components. You can find more
+    information on events
+    <a href="options.html#events">on the options page</a>.
+  </p>
+
+  <p>
+    <code>change</code> is fired whenever an option is selected or removed.
+  </p>
+
+  <p>
+    <code>select2:open</code> is fired whenever the dropdown is opened.
+    <code>select2:opening</code> is fired before this and can be prevented.
+  </p>
+
+  <p>
+    <code>select2:close</code> is fired whenever the dropdown is closed.
+    <code>select2:closing</code> is fired before this and can be prevented.
+  </p>
+
+  <p>
+    <code>select2:select</code> is fired whenever a result is selected.
+    <code>select2:selecting</code> is fired before this and can be prevented.
+  </p>
+
+  <p>
+    <code>select2:unselect</code> is fired whenever a result is unselected.
+    <code>select2:unselecting</code> is fired before this and can be prevented.
+  </p>
+
+  <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.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>
+
+  <h2 id="programmatic">Programmatic access</h2>
+
+  <p>
+    Select2 supports methods that allow programmatic control of the
+    component.
+  </p>
+
+  <div class="s2-example">
+
+    <p>
+      <select class="js-example-programmatic js-states form-control"></select>
+    </p>
+
+    <div class="btn-toolbar" role="toolbar" aria-label="Programmatic control">
+      <div class="btn-group btn-group-sm" aria-label="Set Select2 option">
+        <button class="js-programmatic-set-val btn btn-default">
+          Set "California"
+        </button>
+      </div>
+      <div class="btn-group btn-group-sm" role="group" aria-label="Open and close">
+        <button class="js-programmatic-open btn btn-default">
+          Open
+        </button>
+        <button class="js-programmatic-close btn btn-default">
+          Close
+        </button>
+      </div>
+      <div class="btn-group btn-group-sm" role="group" aria-label="Initialize and destroy">
+        <button class="js-programmatic-init btn btn-default">
+          Init
+        </button>
+        <button class="js-programmatic-destroy btn btn-default">
+          Destroy
+        </button>
+      </div>
+    </div>
+
+    <p>
+      <select class="js-example-programmatic-multi js-states form-control" multiple="multiple"></select>
+    </p>
+
+    <div class="btn-group btn-group-sm" role="group" aria-label="Programmatic setting and clearing Select2 options">
+      <button type="button" class="js-programmatic-multi-set-val btn btn-default">
+        Set to California and Alabama
+      </button>
+      <button type="button" class="js-programmatic-multi-clear btn btn-default">
+        Clear
+      </button>
+    </div>
+
+  </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>
+
+</section>

docs/_includes/examples/tags.html

@@ -0,0 +1,33 @@
+<section>
+
+  <h1 id="tags">Tagging support</h1>
+
+  <p>
+    Select2 can be used to quickly set up fields used for tagging.
+  </p>
+
+  <p>
+    Note that when tagging is enabled the user can select from pre-existing
+    options or create a new tag by picking the first choice, which is what
+    the user has typed into the search box so far.
+  </p>
+
+  <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>
+
+  <pre data-fill-from=".js-code-tags"></pre>
+
+<script type="text/x-example-code" class="js-code-tags">
+$(".js-example-tags").select2({
+  tags: true
+})
+</script>
+
+</section>

docs/_includes/examples/themes-templating-responsive-design.html

@@ -0,0 +1,111 @@
+<section>
+
+  <h1 id="themes-templating-responsive-design" class="page-header">
+    Themes, templating and responsive design
+  </h1>
+
+  <h2 id="themes">Theme support</h2>
+
+  <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>
+
+  <pre data-fill-from=".js-code-theme"></pre>
+
+<script type="text/x-example-code" class="js-code-theme">
+$(".js-example-theme-single").select2({
+  theme: "classic"
+});
+
+$(".js-example-theme-multiple").select2({
+  theme: "classic"
+});
+</script>
+
+<h2 id="templating">Templating</h2>
+
+<p>
+  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>.
+</p>
+
+<p>
+  Templating is primarily controlled by the
+  <a href="options.html#templateResult"><code>templateResult</code></a>
+  and <a href="options.html#templateSelection"><code>templateSelection</code></a>
+  options.
+</p>
+
+<div class="s2-example">
+  <p>
+    <select class="js-example-templating js-states form-control"></select>
+  </p>
+</div>
+
+<pre data-fill-from=".js-code-templating"></pre>
+
+<script type="text/x-example-code" class="js-code-templating">
+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;
+};
+
+$(".js-example-templating").select2({
+  templateResult: formatState
+});
+</script>
+
+<h2 id="responsive">Responsive design - Percent width</h2>
+
+<p>
+  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.
+</p>
+
+<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>
+
+<pre data-fill-from=".js-code-responsive"></pre>
+
+<div class="alert alert-warning">
+  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
+  <code>style</code> declaration into the tag.
+</div>
+
+<script type="text/x-example-code" class="js-code-responsive">
+<select class="js-example-responsive" style="width: 50%"></select>
+<select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>
+</script>
+
+</section>

docs/_includes/examples/tokenizer.html

@@ -0,0 +1,36 @@
+<section>
+
+  <h1 id="tokenizer">Automatic tokenization</h1>
+
+  <p>
+    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.
+  </p>
+
+  <p>
+    The separators that should be used when tokenizing can be specified
+    using the <a href="options.html#tokenSeparators">tokenSeparators</a>
+    options.
+  </p>
+
+  <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>
+
+  <pre data-fill-from=".js-code-tokenizer"></pre>
+
+<script type="text/x-example-code" class="js-code-tokenizer">
+$(".js-example-tokenizer").select2({
+  tags: true,
+  tokenSeparators: [',', ' ']
+})
+</script>
+
+</section>

docs/_includes/footer.html

@@ -1,11 +1,20 @@
-<footer>
-  Select2 is licensed under the
-  <a href="https://github.com/select2/select2/blob/master/LICENSE.md">
-    MIT license.
-  </a>
-  The documentation is licensed under
-  <a href="https://creativecommons.org/licenses/by/3.0/">CC BY 3.0.</a>
-  Maintained by
-  <a href="https://github.com/kevin-brown">Kevin Brown</a> and
-  <a href="https://github.com/ivaynberg">Igor Vaynberg</a>.
+<footer class="s2-docs-footer" role="contentinfo">
+  <div class="container">
+    {% include social-buttons.html %}
+    <p>
+      Select2 is licensed under <a href="https://github.com/select2/select2/blob/master/LICENSE.md">MIT</a>, documentation under <a href="https://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.
+    </p>
+    <p>
+      Maintained by <a href="https://github.com/kevin-brown">Kevin Brown</a> and <a href="https://github.com/ivaynberg">Igor Vaynberg</a> with the help of <a href="https://github.com/select2/select2/graphs/contributors">our contributors</a>.
+    </p>
+    <ul class="s2-docs-footer-links">
+      <li>Currently v4.0.0</li>
+      <li><a href="https://github.com/select2/select2">GitHub</a></li>
+      <li><a href="./examples.html">Examples</a></li>
+      <li><a href="./options.html">Options</a></li>
+      <li><a href="http://select2.github.io/select2/">v3.5.2 docs</a></li>
+      <li><a href="https://github.com/select2/select2/issues">Issues</a></li>
+      <li><a href="https://github.com/select2/select2/releases">Releases</a></li>
+    </ul>
+  </div>
 </footer>

docs/_includes/ga.html

@@ -0,0 +1,9 @@
+<script type="text/javascript">
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+  ga('create', 'UA-57144786-2', 'auto');
+  ga('send', 'pageview');
+</script>

docs/_includes/head.html

@@ -10,15 +10,11 @@
 <script type="text/javascript" src="dist/js/select2.full.js"></script>
 <script type="text/javascript" src="vendor/js/bootstrap.min.js"></script>
 <script type="text/javascript" src="vendor/js/prettify.min.js"></script>
+<script type="text/javascript" src="vendor/js/anchor.min.js"></script>
 
 <link href="vendor/css/bootstrap.min.css" type="text/css" rel="stylesheet" />
 <link href="dist/css/select2.min.css" type="text/css" rel="stylesheet" />
 
 <link href="vendor/css/font-awesome.min.css" type="text/css" rel="stylesheet" />
-<link href="vendor/css/prettify.css" type="text/css" rel="stylesheet" />
-
-<style type="text/css">
-  body { font-size: 16px; }
-  footer { background-color: #eee; margin-top: 1em; padding: 1em; text-align: center; }
-  .navbar-inverse .navbar-brand { color: #fff; }
-</style>
+<link href="vendor/css/anchor.css" type="text/css" rel="stylesheet" />
+<link href="css/s2-docs.css" type="text/css" rel="stylesheet" >

docs/_includes/js-source-states.html

@@ -0,0 +1,62 @@
+<select class="js-source-states">
+  <optgroup label="Alaskan/Hawaiian Time Zone">
+    <option value="AK">Alaska</option>
+    <option value="HI">Hawaii</option>
+  </optgroup>
+  <optgroup label="Pacific Time Zone">
+    <option value="CA">California</option>
+    <option value="NV">Nevada</option>
+    <option value="OR">Oregon</option>
+    <option value="WA">Washington</option>
+  </optgroup>
+  <optgroup label="Mountain Time Zone">
+    <option value="AZ">Arizona</option>
+    <option value="CO">Colorado</option>
+    <option value="ID">Idaho</option>
+    <option value="MT">Montana</option>
+    <option value="NE">Nebraska</option>
+    <option value="NM">New Mexico</option>
+    <option value="ND">North Dakota</option>
+    <option value="UT">Utah</option>
+    <option value="WY">Wyoming</option>
+  </optgroup>
+  <optgroup label="Central Time Zone">
+    <option value="AL">Alabama</option>
+    <option value="AR">Arkansas</option>
+    <option value="IL">Illinois</option>
+    <option value="IA">Iowa</option>
+    <option value="KS">Kansas</option>
+    <option value="KY">Kentucky</option>
+    <option value="LA">Louisiana</option>
+    <option value="MN">Minnesota</option>
+    <option value="MS">Mississippi</option>
+    <option value="MO">Missouri</option>
+    <option value="OK">Oklahoma</option>
+    <option value="SD">South Dakota</option>
+    <option value="TX">Texas</option>
+    <option value="TN">Tennessee</option>
+    <option value="WI">Wisconsin</option>
+  </optgroup>
+  <optgroup label="Eastern Time Zone">
+    <option value="CT">Connecticut</option>
+    <option value="DE">Delaware</option>
+    <option value="FL">Florida</option>
+    <option value="GA">Georgia</option>
+    <option value="IN">Indiana</option>
+    <option value="ME">Maine</option>
+    <option value="MD">Maryland</option>
+    <option value="MA">Massachusetts</option>
+    <option value="MI">Michigan</option>
+    <option value="NH">New Hampshire</option>
+    <option value="NJ">New Jersey</option>
+    <option value="NY">New York</option>
+    <option value="NC">North Carolina</option>
+    <option value="OH">Ohio</option>
+    <option value="PA">Pennsylvania</option>
+    <option value="RI">Rhode Island</option>
+    <option value="SC">South Carolina</option>
+    <option value="VT">Vermont</option>
+    <option value="VA">Virginia</option>
+    <option value="WV">West Virginia</option>
+  </optgroup>
+</select>

docs/_includes/nav/announcements-4.0.html

@@ -0,0 +1,26 @@
+<nav class="s2-docs-sidebar hidden-print hidden-xs hidden-sm">
+  <ul class="nav s2-docs-sidenav">
+    <li>
+      <a href="#select2-400">Select2 4.0.0</a>
+      <ul class="nav">
+        <li><a href="#new-features">New features</a></li>
+        <li><a href="#plugin-system">Plugin system</a></li>
+        <li><a href="#amd-based-build-system">AMD-based build system</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#migrating-from-select2-35">Migrating from Select2 3.5</a>
+      <ul class="nav">
+        <li><a href="#hidden-input">No more hidden input tags</a></li>
+        <li><a href="#new-matcher">Advanced matching of searches</a></li>
+        <li><a href="#flexible-placeholders">More flexible placeholders</a></li>
+        <li><a href="#value-ordering">Display reflects the actual order of the values</a></li>
+        <li><a href="#changed-options">Changed method and option names</a></li>
+        <li><a href="#removed-methods">Deprecated and removed methods</a></li>
+      </ul>
+    </li>
+  </ul>
+  <a class="back-to-top" href="#top">
+    Back to top
+  </a>
+</nav>

docs/_includes/nav/examples.html

@@ -0,0 +1,96 @@
+<nav class="s2-docs-sidebar hidden-print hidden-xs hidden-sm">
+  <ul class="nav s2-docs-sidenav">
+    <li>
+      <a href="#basics">The basics</a>
+      <ul class="nav">
+        <li>
+          <a href="#single">Single select boxes</a>
+        </li>
+        <li>
+          <a href="#multiple">Multiple select boxes</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#placeholders">Placeholders</a>
+    </li>
+    <li>
+      <a href="#data">
+        Data sources
+      </a>
+      <ul class="nav">
+        <li>
+          <a href="#data-array">Loading array data</a>
+        </li>
+        <li>
+          <a href="#data-ajax">Loading remote data</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#disabled">Disabled mode</a>
+    </li>
+    <li>
+      <a href="#disabled-results">Disabled results</a>
+    </li>
+    <li>
+      <a href="#multiple-max">Limiting the number of selections</a>
+    </li>
+    <li>
+      <a href="#hide-search">Hiding the search box</a>
+    </li>
+    <li>
+      <a href="#programmatic-control">Programmatic control</a>
+      <ul class="nav">
+        <li>
+          <a href="#events">DOM events</a>
+        </li>
+        <li>
+          <a href="#programmatic">Programmatic access</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#tags">Tagging support</a>
+    </li>
+    <li>
+      <a href="#tokenizer">Automatic tokenization</a>
+    </li>
+    <li>
+      <a href="#matcher">Customizing how results are matched</a>
+    </li>
+    <li>
+      <a href="#localization-rtl-diacritics">Localization, RTL and diacritics support</a>
+      <ul class="nav">
+        <li>
+          <a href="#language">Multiple languages</a>
+        </li>
+        <li>
+          <a href="#rtl">RTL support</a>
+        </li>
+        <li>
+          <a href="#diacritics">Diacritics support</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#themes-templating-responsive-design">
+        Themes, templating and responsive design
+      </a>
+      <ul class="nav">
+        <li>
+          <a href="#themes">Theme support</a>
+        </li>
+        <li>
+          <a href="#templating">Templating</a>
+        </li>
+        <li>
+          <a href="#responsive">Responsive design</a>
+        </li>
+      </ul>
+    </li>
+  </ul>
+  <a class="back-to-top" href="#top">
+    Back to top
+  </a>
+</nav>

docs/_includes/nav/options.html

@@ -0,0 +1,55 @@
+<nav class="s2-docs-sidebar hidden-print hidden-xs hidden-sm">
+  <ul class="nav s2-docs-sidenav">
+    <li>
+      <a href="#core-options">Core Options</a>
+      <ul class="nav">
+        <li><a href="#data-attributes">Declaring configuration in the <code>data-*</code> attributes</a></li>
+        <li><a href="#amd">AMD compatibility</a></li>
+        <li><a href="#core-options-display">Displaying selections</a></li>
+        <li><a href="#core-options-results">Returning and displaying results</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#dropdown">Dropdown</a>
+      <ul class="nav">
+        <li><a href="#dropdownParent">Attached to body</a></li>
+        <li><a href="#dropdown-attachContainer">Attached below the container</a></li>
+        <li><a href="#dropdown-search">Search</a></li>
+        <li><a href="#dropdown-select-on-close">Select the highlighted option on close</a></li>
+        <li><a href="#closeOnSelect">Close the dropdown when a result is selected</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#events">Events</a>
+      <ul class="nav">
+        <li><a href="#events-public">Public events</a></li>
+        <li><a href="#events-internal">Internal events</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#adapters">The plugin system (adapters)</a>
+      <ul class="nav">
+        <li><a href="#adapters-all">All adapters</a></li>
+        <li><a href="#selectionAdapter">Container (selection)</a></li>
+        <li><a href="#dataAdapter">Data set</a></li>
+        <li><a href="#dropdownAdapter">Dropdown</a></li>
+        <li><a href="#resultsAdapter">Results</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#setting-default-options">Setting default options</a>
+    </li>
+    <li>
+      <a href="#backwards-compatibility">Backwards compatibility</a>
+      <ul class="nav">
+        <li><a href="#compat-matcher">Simplified function for matching data objects</a></li>
+        <li><a href="#initSelection">Old initial selections with <code>initSelection</code></a></li>
+        <li><a href="#query">Querying old data with <code>query</code></a></li>
+        <li><a href="#input-fallback">Compatibility with <code>&lt;input type="text" /&gt;</code></a></li>
+      </ul>
+    </li>
+  </ul>
+  <a class="back-to-top" href="#top">
+    Back to top
+  </a>
+</nav>

docs/_includes/navigation.html

@@ -1,40 +1,38 @@
-<header class="navbar navbar-inverse navbar-static-top" id="top" role="banner">
+<header class="s2-docs-nav navbar navbar-default navbar-static-top" id="top" role="banner">
   <div class="container">
     <div class="navbar-header">
       <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target=".select2-navbar-collapse">
         <span class="sr-only">Toggle navigation</span>
-        <span class="icon-bar"></span>
-        <span class="icon-bar"></span>
-        <span class="icon-bar"></span>
+        <span class="icon-bar top-bar"></span>
+        <span class="icon-bar middle-bar"></span>
+        <span class="icon-bar bottom-bar"></span>
       </button>
-      <a href="./" class="navbar-brand">Select2</a>
+      <a href="./" class="navbar-brand"><img src="/images/logo.png" height="20px"> Select2</a>
     </div>
 
     <nav class="collapse navbar-collapse select2-navbar-collapse" role="navigation">
       <ul class="nav navbar-nav">
-        <li{% if page.slug == "home" %} class="active"{% endif %}>
-          <a href="./">Home</a>
-        </li>
         <li{% if page.slug == "examples" %} class="active"{% endif %}>
           <a href="./examples.html">Examples</a>
         </li>
         <li{% if page.slug == "options" %} class="active"{% endif %}>
           <a href="./options.html">Options</a>
         </li>
-        <li class="dropdown">
+        <li class="dropdown{% if page.slug == "announcements-4.0" %} active{% endif %}">
           <a href="#" class="dropdown-toggle" data-toggle="dropdown">
             Topics
             <span class="caret"></span>
           </a>
           <ul class="dropdown-menu">
+            <li{% if page.slug == "announcements-4.0" %} class="active"{% endif %}>
+              <a href="./announcements-4.0.html">4.0 Announcement</a>
+            </li>
+            <li class="divider"></li>
             <li>
               <a href="https://github.com/select2/select2/releases">
                 Release notes
               </a>
             </li>
-            <li{% if page.slug == "announcements-4.0" %} class="active"{% endif %}>
-              <a href="./announcements-4.0.html">4.0 Announcement</a>
-            </li>
           </ul>
         </li>
         <li{% if page.slug == "community" %} class="active"{% endif %}>

docs/_includes/notice-previous.html

@@ -0,0 +1,7 @@
+<section class="notice-previous">
+  <div class="container text-center">
+    <a href="http://select2.github.io/select2/">Looking for the Select2 3.5.2 docs?</a>
+    We have moved them to a new location
+    <a href="announcements-4.0.html">while we push forward with Select2 4.0</a>.
+  </div>
+</section>

docs/_includes/options/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>

docs/_includes/options/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>

docs/_includes/options/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>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 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>

docs/_includes/options/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>

docs/_includes/options/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>

docs/_includes/options/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>

docs/_includes/social-buttons.html

@@ -0,0 +1,10 @@
+<div class="s2-docs-social">
+  <ul class="s2-docs-social-buttons">
+    <li>
+      <iframe class="github-btn" src="https://ghbtns.com/github-btn.html?user=select2&amp;repo=select2&amp;type=watch&amp;count=true" width="100" height="20" title="Star on GitHub"></iframe>
+    </li>
+    <li>
+      <iframe class="github-btn" src="https://ghbtns.com/github-btn.html?user=select2&amp;repo=select2&amp;type=fork&amp;count=true" width="102" height="20" title="Fork on GitHub"></iframe>
+    </li>
+  </ul>
+</div>

docs/_layouts/default.html

@@ -1,23 +1,56 @@
 <!doctype html>
 <html>
-    <head>
-        {% include head.html %}
-    </head>
-    <body>
-        {% include navigation.html %}
-
-        {{ content }}
-
-        {% include footer.html %}
-
-        <script type="text/javascript">
-        (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
-            (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
-        })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-
-        ga('create', 'UA-57144786-2', 'auto');
-        ga('send', 'pageview');
-        </script>
-    </body>
+  <head>
+    {% include head.html %}
+  </head>
+  <body>
+    {% include navigation.html %}
+
+    {{ content }}
+
+    {% include footer.html %}
+
+    <script>
+      (function ($) {
+        'use strict';
+
+        $(function () {
+          var $window = $(window);
+          var $body = $(document.body);
+          var $sidebar = $('.s2-docs-sidebar');
+
+          $body.scrollspy({
+            target: '.s2-docs-sidebar',
+            offset: 40
+          });
+
+          $window.on('load', function () {
+            $body.scrollspy('refresh');
+          });
+
+          $sidebar.affix({
+            offset: {
+              top: function () {
+                var offsetTop = $sidebar.offset().top;
+                var navOuterHeight = $('.s2-docs-nav').height();
+
+                return (this.top = offsetTop - navOuterHeight);
+              },
+              bottom: function () {
+                return (this.bottom = $('.s2-docs-footer').outerHeight(true));
+              }
+            }
+          });
+        });
+      })(jQuery);
+
+      (function () {
+        'use strict';
+
+        addAnchors('.s2-docs-container h1, .s2-docs-container h2, .s2-docs-container h3, .s2-docs-container h4, .s2-docs-container h5');
+      })();
+    </script>
+
+    {% include ga.html %}
+  </body>
 </html>

docs/_layouts/home.html

@@ -1,30 +1,23 @@
 <!doctype html>
-<html>
-    <head>
-        {% include head.html %}
+<html class="s2-docs-home">
+  <head>
+    {% include head.html %}
+  </head>
+  <body>
+    {% include navigation.html %}
 
-        <style type="text/css">
-          .navbar, .jumbotron { margin-bottom: 0; }
-          .jumbotron-side { padding-top: 2em; }
-          .notice-previous { background-color: #d9edf7; border-top: 1px solid #bce8f1; border-bottom: 1px solid #bce8f1; color: #31708f; padding: 0.5em; margin-bottom: 1em; text-align: center; }
-          .notice-previous a { font-weight: bold; }
-        </style>
-    </head>
-    <body>
-        {% include navigation.html %}
+    {{ content }}
 
-        {{ content }}
+    {% include footer.html %}
 
-        {% include footer.html %}
+    <script>
+      (function () {
+        'use strict';
 
-        <script type="text/javascript">
-        (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
-            (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
-        })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+        prettyPrint();
+      })();
+    </script>
 
-        ga('create', 'UA-57144786-2', 'auto');
-        ga('send', 'pageview');
-        </script>
-    </body>
+    {% include ga.html %}
+  </body>
 </html>

docs/_sass/_alert.scss

@@ -0,0 +1,47 @@
+// Alerts
+//
+// Modify Bootstrap's default alert styles to mimick
+// the `.bs-callout` styles from Bootstrap's docs.
+//
+// @see https://github.com/twbs/bootstrap/blob/master/docs/assets/css/src/docs.css#L711
+// @see https://github.com/twbs/bootstrap/blob/master/less/alerts.less
+
+.alert {
+  background: #fff;
+  border: 1px solid #eee;
+  border-left-width: 5px;
+  border-radius: 3px;
+  color: #333;
+  margin: 20px 0;
+  padding: 20px;
+
+  h4 {
+    font-size: 18px;
+    margin-top: 0;
+    margin-bottom: 5px;
+  }
+
+  &-danger {
+    border-left-color: #ce4844;
+
+    h4 {
+      color: #ce4844;
+    }
+  }
+
+  &-info {
+    border-left-color: #1b809e;
+
+    h4 {
+      color: #1b809e;
+    }
+  }
+
+  &-warning {
+    border-left-color: #aa6708;
+
+    h4 {
+      color: #aa6708;
+    }
+  }
+}

docs/_sass/_anchorjs.scss

@@ -0,0 +1,43 @@
+// AnchorJS Styles
+//
+// Styles for AnchorJS elements following the Bootstrap docs styles.
+//
+// @see https://github.com/twbs/bootstrap/blob/master/docs/assets/css/src/docs.css#L1599
+
+.anchorjs-link {
+  float: left;
+  width: 1em;
+  height: 1em;
+  margin-left: -1.2em;
+  opacity: 0;
+  color: inherit;
+  text-align: center;
+
+  &:link,
+  &:visited {
+    text-decoration: none;
+    color: inherit;
+  }
+
+  @media (max-width: 480px) {
+    display: none;
+  }
+}
+
+*:hover > .anchorjs-link {
+  opacity: .5;
+  -webkit-transition: all .16s linear;
+       -o-transition: all .16s linear;
+          transition: all .16s linear;
+}
+
+*:hover > .anchorjs-link:hover,
+.anchorjs-link:focus {
+  opacity: 1;
+}
+
+.anchorjs-icon {
+  font-size: 60%;
+  vertical-align: .2em;
+}
+

docs/_sass/_buttons.scss

@@ -0,0 +1,20 @@
+// Buttons
+
+.btn-outline-inverse {
+  color: #428BCA;
+  background-color: transparent;
+  border-color: #428BCA;
+  padding: 15px 30px;
+  font-size: 20px;
+  transition: all .1s ease-in-out;
+
+  &:hover {
+    color: #fff;
+    border-color: #428BCA;
+    background-color: #428BCA;
+  }
+}
+
+.btn-toolbar {
+  margin-bottom: 20px;
+}

docs/_sass/_code.scss

@@ -0,0 +1,16 @@
+// Code (inline and block)
+
+// Inline code within headings retain the heading's background-color
+h2 code,
+h3 code,
+h4 code {
+  background-color: inherit;
+}
+
+// Modify Bootstrap's styles for blocks of code
+pre {
+  padding: 9px 14px;
+  margin-bottom: 14px;
+  background-color: #f7f7f9;
+  border: 1px solid #e1e1e8;
+}

docs/_sass/_examples.scss

@@ -0,0 +1,90 @@
+// Examples
+//
+// Styles for the Select2 examples, largely copied
+// from Bootstrap's docs styles.
+//
+// @see https://github.com/twbs/bootstrap/blob/master/docs/assets/css/src/docs.css#L533
+
+.s2-example {
+  position: relative;
+  padding: 45px 15px 15px;
+  margin: 0 -15px 15px;
+  background-color: #fafafa;
+  box-shadow: inset 0 3px 6px rgba(0, 0, 0, 0.05);
+  border-color: #e5e5e5 #eee #eee;
+  border-style: solid;
+  border-width: 1px 0;
+
+  &:after {
+    content: "Example";
+    position: absolute;
+    top: 15px;
+    left: 15px;
+    font-size: 12px;
+    font-weight: bold;
+    color: #bbb;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+  }
+
+  @media (min-width: 768px) {
+    margin-left: 0;
+    margin-right: 0;
+    background-color: #fff;
+    border-width: 1px;
+    border-color: #eee;
+    border-radius: 4px 4px 0 0;
+    box-shadow: none;
+  }
+}
+
+// styles for the event log in the "DOM events" section of the docs
+.s2-event-log {
+  background: #002451;
+	color: white;
+  font-family: Menlo, 'Bitstream Vera Sans Mono', 'DejaVu Sans Mono', Monaco, Consolas, monospace;
+  margin: 0 -15px 15px;
+  padding: 45px 15px 15px;
+	position: relative;
+
+  &:after {
+    content: "Event Log";
+    position: absolute;
+    top: 15px;
+    left: 15px;
+    font-size: 12px;
+    font-weight: bold;
+    color: #BBB;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+  }
+
+  @media (min-width: 768px) {
+    margin-left: 0;
+    margin-right: 0;
+    margin-top: -15px;
+    border-width: 1px;
+    border-color: #eee;
+    box-shadow: none;
+  }
+}
+
+.s2-example + pre,
+.s2-event-log + pre {
+  margin: -15px -15px 15px;
+  border-radius: 0;
+  border-width: 0 0 1px;
+
+  @media (min-width: 768px) {
+    margin-top: -16px;
+    margin-left: 0;
+    margin-right: 0;
+    border-width: 1px;
+    border-bottom-left-radius: 4px;
+    border-bottom-right-radius: 4px;
+  }
+}
+
+.s2-example + .s2-event-log {
+  margin-top: -15px;
+}

docs/_sass/_featurette.scss

@@ -0,0 +1,16 @@
+// Homepage featurettes
+
+.s2-docs-featurette {
+  color: #777;
+  padding: 15px 0;
+  text-align: center;
+
+  h4 {
+    margin: 30px 0 15px;
+  }
+
+  .fa {
+    font-size: 28px;
+    color: #777;
+  }
+}

docs/_sass/_footer.scss

@@ -0,0 +1,42 @@
+// Footer
+
+.s2-docs-footer {
+  border-top: 1px solid #eee;
+  color: #767676;
+  padding-top: 40px;
+  padding-bottom: 40px;
+  margin-top: 100px;
+  text-align: center;
+
+  &-links {
+    padding-left: 0;
+    margin-top: 20px;
+  }
+
+  &-links li {
+    display: inline;
+    padding: 0 2px;
+
+    &:after {
+      content: "·";
+      padding-left: 8px;
+    }
+
+    &:first-child {
+      padding-left: 0;
+    }
+
+    &:last-child:after {
+      content: "";
+      padding-left: 0;
+    }
+  }
+
+  @media (min-width: 768px) {
+    p {
+      margin-bottom: 0;
+    }
+  }
+}
+
+

docs/_sass/_hamburger.scss

@@ -0,0 +1,49 @@
+// Animated hamburger icon
+//
+// Add an animation to Bootstrap's `.navbar-toggle` hamburger icon,
+// courtesy of Julien Melissas.
+//
+// @see http://codepen.io/JulienMelissas/pen/LEBGLj
+// @see http://julienmelissas.com/animated-x-icon-for-the-bootstrap-navbar-toggle/
+
+.navbar-toggle {
+  border: none;
+  background: transparent !important;
+
+  &:hover {
+    background: transparent !important;
+  }
+
+  .icon-bar {
+    width: 22px;
+    transition: all 0.2s;
+  }
+
+  .top-bar {
+    transform: rotate(45deg);
+    transform-origin: 10% 10%;
+  }
+
+  .middle-bar {
+    opacity: 0;
+  }
+
+  .bottom-bar {
+    transform: rotate(-45deg);
+    transform-origin: 10% 90%;
+  }
+
+  &.collapsed {
+    .top-bar {
+      transform: rotate(0);
+    }
+
+    .middle-bar {
+      opacity: 1;
+    }
+
+    .bottom-bar {
+      transform: rotate(0);
+    }
+  }
+}

docs/_sass/_home.scss

@@ -0,0 +1,31 @@
+// Homepage-specific styles
+
+.s2-docs-home {
+  .jumbotron {
+    margin-bottom: 0;
+    color: #000;
+
+    h1 {
+      color: #000;
+      margin-top: 20px;
+    }
+  }
+
+  .lead {
+    text-align: center;
+    max-width: 800px;
+    margin: 0 auto 40px;
+  }
+
+  .notice-previous {
+    background: #f6f6f6;
+    color: #666;
+    border-bottom: 1px solid #eee;
+    padding: 15px 20px;
+  }
+
+  .half-rule {
+    width: 100px;
+    margin: 40px auto;
+  }
+}

docs/_sass/_jumbotron.scss

@@ -0,0 +1,24 @@
+// Jumbotron
+//
+// Modify Bootstrap's default `.jumbotron` styles.
+
+.jumbotron {
+  background-color: #F6F6F6;
+  border-bottom: 1px solid #eee;
+  color: #777;
+  padding-left: 0;
+  padding-right: 0;
+
+  h1 {
+    color: #777;
+    font-size: 36px;
+    margin-top: 10px;
+  }
+
+  .version {
+    color: #999;
+    font-size: 14px;
+    font-weight: normal;
+    margin-bottom: 30px;
+  }
+}

docs/_sass/_layout.scss

@@ -0,0 +1,14 @@
+// Layout
+
+.s2-docs-container {
+  line-height: 1.6;
+}
+
+section {
+  margin-bottom: 40px;
+}
+
+.page-header {
+  padding-bottom: 19px;
+  margin-bottom: 29px;
+}

docs/_sass/_nav.scss

@@ -0,0 +1,58 @@
+// Main navigation
+//
+// Styles for the top `.navbar` and its dropdowns.
+
+.s2-docs-nav {
+  margin-bottom: 0;
+  border-color: #eee;
+  background-color: #f6f6f6;
+
+  .navbar-brand {
+    font-weight: 500;
+    img {
+      margin-right: 4px;
+    }
+  }
+
+  .navbar-nav > .active > a,
+  .navbar-nav > .active > a:hover,
+  .navbar-nav > .active > a:focus {
+    background-color: #f0f0f0;
+    color: #000;
+  }
+
+  @media (min-width: 768px) {
+
+    .navbar-nav > li > .dropdown-menu:before {
+      position: absolute;
+      top: -21px;
+      left: 24px;
+      display: block;
+      width: 0;
+      height: 0;
+      border-color: rgba(0, 0, 0, 0) rgba(0, 0, 0, 0) rgba(0, 0, 0, 0.1);
+      border-style: solid;
+      border-width: 10px;
+      content: "";
+    }
+
+    .navbar-nav > li > .dropdown-menu:after {
+      position: absolute;
+      top: -20px;
+      left: 24px;
+      display: block;
+      width: 0;
+      height: 0;
+      border-color: rgba(0, 0, 0, 0) rgba(0, 0, 0, 0) #FFF;
+      border-style: solid;
+      border-width: 10px;
+      content: '';
+    }
+
+    .navbar-nav .dropdown-menu {
+      border-radius: 4px;
+      border-color: #ddd;
+      margin-top: -1px;
+    }
+  }
+}

docs/_sass/_prettify.scss

@@ -0,0 +1,51 @@
+// Google Code Prettify styles
+
+.com {
+  color: #999;
+}
+.lit {
+  color: #195f91;
+}
+.pun, .opn, .clo {
+  color: #93a1a1;
+}
+.fun {
+  color: #dc322f;
+}
+.str, .atv {
+  color: #C7254E;
+}
+.kwd, .prettyprint .tag {
+  color: #2F6F9F;
+}
+.typ, .atn, .dec, .var {
+  /*color: teal;*/
+  color: #428BCA;
+}
+.pln {
+  color: #333;
+}
+
+.prettyprint {
+  padding: 9px 14px;
+  margin-bottom: 20px;
+  margin-top: 20px;
+  border: 1px solid #eee;
+
+  &.linenums {
+    -webkit-box-shadow: inset 40px 0 0 #fbfbfb, inset 41px 0 0 #f6f6f6;
+       -moz-box-shadow: inset 40px 0 0 #fbfbfb, inset 41px 0 0 #f6f6f6;
+            box-shadow: inset 40px 0 0 #fbfbfb, inset 41px 0 0 #f6f6f6;
+  }
+}
+
+// Specify class=linenums on a pre to get line numbering
+ol.linenums {
+  margin: 0 0 0 -12px;
+
+  li {
+    padding-left: 12px;
+    color: #bebebe;
+    line-height: 18px;
+  }
+}

docs/_sass/_result-repository.scss

@@ -0,0 +1,62 @@
+// Styles accompanying the "Loading remote data" example `templateResult
+
+.select2-result-repository {
+  padding-top: 4px;
+  padding-bottom: 3px;
+
+  &__avatar {
+    float: left;
+    width: 60px;
+    margin-right: 10px;
+
+    img {
+      width: 100%;
+      height: auto;
+      border-radius: 2px;
+    }
+  }
+
+  &__meta {
+    margin-left: 70px;
+  }
+
+  &__title {
+    color: black;
+    font-weight: bold;
+    word-wrap: break-word;
+    line-height: 1.1;
+    margin-bottom: 4px;
+  }
+
+  &__forks,
+  &__stargazers {
+    margin-right: 1em;
+  }
+
+  &__forks,
+  &__stargazers,
+  &__watchers {
+    display: inline-block;
+    color: #aaa;
+    font-size: 11px;
+  }
+
+  &__description {
+    font-size: 13px;
+    color: #777;
+    margin-top: 4px;
+  }
+
+  .select2-results__option--highlighted & {
+    &__title {
+      color: white;
+    }
+
+    &__forks,
+    &__stargazers,
+    &__description,
+    &__watchers {
+      color: mix(#428BCA, white, 30%);
+    }
+  }
+}

docs/_sass/_sidenav.scss

@@ -0,0 +1,152 @@
+// Side navigation
+//
+// Scrollspy and affixed enhanced navigation to
+// highlight sections and secondary sections of docs content`.
+
+// First level of nav
+.s2-docs-sidenav {
+  margin-top: 20px;
+  margin-bottom: 20px;
+
+  // By default it is not affixed in mobile views, so undo that
+  &.affix {
+    position: static;
+  }
+
+  @media (min-width: 768px) {
+    padding-left: 20px;
+  }
+}
+
+// All levels of nav
+.s2-docs-sidebar .nav {
+  > li > a {
+    margin-left: -1px;
+    display: block;
+    padding: 4px 20px;
+    font-size: 13px;
+    font-weight: 500;
+    color: #767676;
+    border-left: 1px solid transparent;
+    transition: color .2s, border-color .2s, border-width .2s;
+  }
+
+  > li > a code {
+    background-color: inherit;
+    color: inherit;
+  }
+
+  > li > a:hover,
+  > li > a:focus {
+    padding-left: 19px;
+    color: #428BCA;
+    text-decoration: none;
+    background-color: transparent;
+    border-left-color: #428BCA;
+  }
+
+  > .active > a,
+  > .active:hover > a,
+  > .active:focus > a {
+    padding-left: 18px;
+    font-weight: bold;
+    color: #428BCA;
+    background-color: transparent;
+    border-left: 2px solid #428BCA;
+  }
+
+  // Nav: second level (shown on .active)
+  .nav {
+    display: none; // Hide by default, but at >768px, show it
+    padding-bottom: 10px;
+  }
+
+  .nav > li > a {
+    padding-top: 1px;
+    padding-bottom: 1px;
+    padding-left: 30px;
+    font-size: 12px;
+    font-weight: normal;
+  }
+
+  .nav > li > a:hover,
+  .nav > li > a:focus {
+    padding-left: 30px;
+  }
+
+  .nav > .active > a,
+  .nav > .active:hover > a,
+  .nav > .active:focus > a {
+    padding-left: 30px;
+    font-weight: 400;
+  }
+}
+
+// Show and affix the side nav when space allows it
+@media (min-width: 992px) {
+  .s2-docs-sidebar .s2-docs-sidenav {
+    padding-top: 40px;
+    transition: border-color .2s;
+    border-left: 1px solid transparent;
+  }
+
+  .s2-docs-sidebar.affix .s2-docs-sidenav {
+    border-left-color: #eee;
+  }
+
+  .s2-docs-sidebar .nav > .active > ul {
+    display: block;
+  }
+
+  // Widen the fixed sidebar
+  .s2-docs-sidebar.affix,
+  .s2-docs-sidebar.affix-bottom {
+    width: 213px;
+  }
+
+  // Undo the static from mobile first approach
+  .s2-docs-sidebar.affix {
+
+    position: fixed;
+    top: 0px;
+  }
+
+  // Undo the static from mobile first approach
+  .s2-docs-sidebar.affix-bottom {
+    position: absolute;
+  }
+
+  .s2-docs-sidebar.affix-bottom .s2-docs-sidenav,
+  .s2-docs-sidebar.affix .s2-docs-sidenav {
+    margin-top: 0;
+    margin-bottom: 0;
+  }
+}
+
+@media (min-width: 1200px) {
+  // Widen the fixed sidebar again
+  .s2-docs-sidebar.affix-bottom,
+  .s2-docs-sidebar.affix {
+    width: 263px;
+  }
+}
+
+/* Back to top (hidden on mobile) */
+.back-to-top {
+  display: none;
+  padding: 4px 10px;
+  margin-top: 10px;
+  margin-left: 10px;
+  font-size: 12px;
+  font-weight: 400;
+  color: #999;
+
+  &:hover {
+    color: #428BCA;
+    text-decoration: none;
+  }
+
+  @media (min-width: 768px) {
+    display: block;
+  }
+}

docs/_sass/_social.scss

@@ -0,0 +1,35 @@
+// Social buttons
+//
+// Twitter and GitHub social action buttons.
+
+.s2-docs-social {
+  margin-bottom: 20px;
+  text-align: center;
+}
+
+.s2-docs-social-buttons {
+  display: inline-block;
+  padding-left: 0;
+  margin-bottom: 0;
+  list-style: none;
+
+  li {
+    display: inline-block;
+    padding: 5px 8px;
+    line-height: 1;
+  }
+
+  .twitter-follow-button {
+    width: 225px !important;
+  }
+
+  .twitter-share-button {
+    width: 98px !important;
+  }
+}
+
+// Style the GitHub buttons via CSS instead of inline attributes
+.github-btn {
+  overflow: hidden;
+  border: 0;
+}

docs/_sass/_typography.scss

@@ -0,0 +1,6 @@
+// Typography
+
+h1[id] {
+  padding-top: 20px;
+  margin-top: 0;
+}

docs/announcements-4.0.html

@@ -3,156 +3,164 @@ layout: default
 title: Select2 4.0.0 Released
 slug: announcements-4.0
 ---
-
-<div class="container">
-  <section id="release">
-    <h1>Select2 4.0.0</h1>
-
-    <p>
-      The 4.0 release of Select2 is the result of three years of working on the
-      code base and watching where it needs to go. At the core, it is a full
-      rewrite that addresses many of the extensibility and usability problems
-      that could not be addressed in previous versions.
-    </p>
-
-    <p>
-      This release contains many breaking changes, but easy-upgrade paths have
-      been created as well as helper modules that will allow for backwards
-      compatibility to be maintained with past versions of Select2. Upgrading
-      <em>will</em> require you to read the release notes carefully, but the
-      migration path should be relatively straightforward. You can view a list
-      of the most common changes that you will need to make
-      <a href="https://github.com/select2/select2/releases">in the release notes</a>.
-    </p>
-
-    <p>
-      Below is an in-depth review of what is new in Select2, as well as some of
-      the major changes that have been made.
-    </p>
-  </section>
-
-  <section id="new">
-    <h2>New features</h2>
-
-    <p>
-      The notable features of this new release include:
-    </p>
-
-    <ul>
-      <li>
-        A more flexible plugin framework that allows you to override Select2 to
-        behave exactly how you want it to.
-      </li>
-      <li>
-        Consistency with standard <code>&lt;select&gt;</code> elements for all
-        data adapters, removing the need for hidden <code>&lt;input&gt;</code>
-        elements.
-      </li>
-      <li>
-        A new build system that uses AMD to keep everything organized.
-      </li>
-      <li>
-        Less specific selectors allowing for Select2 to be styled to fit the
-        rest of your application.
-      </li>
-    </ul>
-  </section>
-
-  <section id="plugins">
-    <h2>Plugin system</h2>
-
-    <p>
-      Select2 now provides interfaces that allow for it to be easily extended,
-      allowing for anyone to create a plugin that changes the way Select2 works.
-      This is the result of Select2 being broken into four distinct sections,
-      each of which can be extended and used together to create your unique
-      Select2.
-    </p>
-
-    <p>
-      The adapters implement a consistent interface that is documented in the
-      <a href="options.html#adapters">options section for adapters</a>, allowing
-      you to customize Select2 to do exactly what you are looking for. Select2
-      is designed such that you can mix and match plugins, with most of the core
-      options being built as decorators that wrap the standard adapters.
-    </p>
-  </section>
-
-  <section id="amd-builds">
-    <h2>AMD-based build system</h2>
-
-    <p>
-      Select2 now uses an
-      <a href="https://en.wikipedia.org/wiki/Asynchronous_module_definition">AMD-based build system</a>,
-      allowing for builds that only require the parts of Select2 that you need.
-      While a custom build system has not yet been created, Select2 is open
-      source and will gladly accept a pull request for one.
-    </p>
-
-    <p>
-      Select2 includes the minimal <a href="https://github.com/jrburke/almond">almond</a>
-      AMD loader, but a custom <code>select2.amd.js</code> build is available
-      if you already use an AMD loader. The code base (available in the
-      <code>src</code> directory) also uses AMD, allowing you to include Select2
-      in your own build system and generate your own builds alongside your
-      existing infrastructure.
-    </p>
-
-    <p>
-      The AMD methods used by Select2 are available as
-      <code>jQuery.fn.select2.amd.define()/require()</code>, allowing you to use the
-      included almond loader. These methods are primarily used by the
-      translations, but they are the recommended way to access custom modules
-      that Select2 provides.
-    </p>
-  </section>
-
-  <section id="migrating">
-    <h1>Migrating from Select2 3.5</h1>
-
-    <p>
-      There are a few breaking changes that migrators should be aware of when
-      they are coming from older versions of Select2.
-    </p>
-
-    <p>
-      If you use the full build of Select2 (<code>select2.full.js</code>), you
-      will be automatically notified of the major breaking changes, and
-      compatibility modules will be used in some cases to ensure that your code
-      still behaves how you were expecting.
-    </p>
-
-    <h2 id="hidden-input">No more hidden input tags</h2>
-
-    <p>
-      In past versions of Select2, an <code>&lt;input type="hidden" /&gt;</code>
-      tag was recommended if you wanted to do anything advanced with Select2,
-      such as work with remote data sources or allow users to add their own
-      tags. This had the unfortunate side-effect of servers not receiving the
-      data from Select2 as an array, like a standard <code>&lt;select&gt;</code>
-      element does, but instead sending a string containing the comma-separated
-      strings. The code base ended up being littered with special cases for the
-      hidden input, and libraries using Select2 had to work around the
-      differences it caused.
-    </p>
-
-    <p>
-      In Select2 4.0, the <code>&lt;select&gt;</code> element supports all core
-      options, and support for the old
-      <code>&lt;input type="hidden" /&gt;</code> has been deprecated. This means
-      that if you previously declared an AJAX field with some pre-selected
-      options that looked like...
-    </p>
+<section id="pre-release" class="jumbotron">
+  <div class="container">
+    <h1>Announcing Select2 4.0.0</h1>
+  </div>
+</section>
+
+<div class="container s2-docs-container">
+  <div class="row">
+    <div class="col-md-9" role="main">
+
+      <section id="release">
+        <h1 class="page-header">Select2 4.0.0</h1>
+
+        <p class="lead">
+          The 4.0 release of Select2 is the result of three years of working on the
+          code base and watching where it needs to go. At the core, it is a full
+          rewrite that addresses many of the extensibility and usability problems
+          that could not be addressed in previous versions.
+        </p>
+
+        <p>
+          This release contains many breaking changes, but easy-upgrade paths have
+          been created as well as helper modules that will allow for backwards
+          compatibility to be maintained with past versions of Select2. Upgrading
+          <em>will</em> require you to read the release notes carefully, but the
+          migration path should be relatively straightforward. You can view a list
+          of the most common changes that you will need to make
+          <a href="https://github.com/select2/select2/releases">in the release notes</a>.
+        </p>
+
+        <p>
+          Below is an in-depth review of what is new in Select2, as well as some of
+          the major changes that have been made.
+        </p>
+      </section>
+
+      <section id="new">
+        <h2>New features</h2>
+
+        <p>
+          The notable features of this new release include:
+        </p>
+
+        <ul>
+          <li>
+            A more flexible plugin framework that allows you to override Select2 to
+            behave exactly how you want it to.
+          </li>
+          <li>
+            Consistency with standard <code>&lt;select&gt;</code> elements for all
+            data adapters, removing the need for hidden <code>&lt;input&gt;</code>
+            elements.
+          </li>
+          <li>
+            A new build system that uses AMD to keep everything organized.
+          </li>
+          <li>
+            Less specific selectors allowing for Select2 to be styled to fit the
+            rest of your application.
+          </li>
+        </ul>
+      </section>
+
+      <section id="plugins">
+        <h2>Plugin system</h2>
+
+        <p>
+          Select2 now provides interfaces that allow for it to be easily extended,
+          allowing for anyone to create a plugin that changes the way Select2 works.
+          This is the result of Select2 being broken into four distinct sections,
+          each of which can be extended and used together to create your unique
+          Select2.
+        </p>
+
+        <p>
+          The adapters implement a consistent interface that is documented in the
+          <a href="options.html#adapters">options section for adapters</a>, allowing
+          you to customize Select2 to do exactly what you are looking for. Select2
+          is designed such that you can mix and match plugins, with most of the core
+          options being built as decorators that wrap the standard adapters.
+        </p>
+      </section>
+
+      <section id="amd-builds">
+        <h2>AMD-based build system</h2>
+
+        <p>
+          Select2 now uses an
+          <a href="https://en.wikipedia.org/wiki/Asynchronous_module_definition">AMD-based build system</a>,
+          allowing for builds that only require the parts of Select2 that you need.
+          While a custom build system has not yet been created, Select2 is open
+          source and will gladly accept a pull request for one.
+        </p>
+
+        <p>
+          Select2 includes the minimal <a href="https://github.com/jrburke/almond">almond</a>
+          AMD loader, but a custom <code>select2.amd.js</code> build is available
+          if you already use an AMD loader. The code base (available in the
+          <code>src</code> directory) also uses AMD, allowing you to include Select2
+          in your own build system and generate your own builds alongside your
+          existing infrastructure.
+        </p>
+
+        <p>
+          The AMD methods used by Select2 are available as
+          <code>jQuery.fn.select2.amd.define()/require()</code>, allowing you to use the
+          included almond loader. These methods are primarily used by the
+          translations, but they are the recommended way to access custom modules
+          that Select2 provides.
+        </p>
+      </section>
+
+      <section id="migrating">
+        <h1>Migrating from Select2 3.5</h1>
+
+        <p>
+          There are a few breaking changes that migrators should be aware of when
+          they are coming from older versions of Select2.
+        </p>
+
+        <p>
+          If you use the full build of Select2 (<code>select2.full.js</code>), you
+          will be automatically notified of the major breaking changes, and
+          compatibility modules will be used in some cases to ensure that your code
+          still behaves how you were expecting.
+        </p>
+
+        <h2 id="hidden-input">No more hidden input tags</h2>
+
+        <p>
+          In past versions of Select2, an <code>&lt;input type="hidden" /&gt;</code>
+          tag was recommended if you wanted to do anything advanced with Select2,
+          such as work with remote data sources or allow users to add their own
+          tags. This had the unfortunate side-effect of servers not receiving the
+          data from Select2 as an array, like a standard <code>&lt;select&gt;</code>
+          element does, but instead sending a string containing the comma-separated
+          strings. The code base ended up being littered with special cases for the
+          hidden input, and libraries using Select2 had to work around the
+          differences it caused.
+        </p>
+
+        <p>
+          In Select2 4.0, the <code>&lt;select&gt;</code> element supports all core
+          options, and support for the old
+          <code>&lt;input type="hidden" /&gt;</code> has been deprecated. This means
+          that if you previously declared an AJAX field with some pre-selected
+          options that looked like…
+        </p>
 
 <pre class="prettyprint linenums">
 &lt;input type="hidden" name="select-boxes" value="1,2,4,6" /&gt;
 </pre>
 
-    <p>
-      It will need to be recreated as a <code>&lt;select&gt;</code> element with
-      some <code>&lt;option&gt;</code> tags that have <code>value</code>
-      attributes that match the old value.
-    </p>
+        <p>
+          It will need to be recreated as a <code>&lt;select&gt;</code> element with
+          some <code>&lt;option&gt;</code> tags that have <code>value</code>
+          attributes that match the old value.
+        </p>
 
 <pre class="prettyprint linenums">
 &lt;select name="select-boxes" multiple="multiple"&gt;
@@ -163,44 +171,44 @@ slug: announcements-4.0
 &lt;/select&gt;
 </pre>
 
-    <p>
-      The options that you create should have <code>selected="selected"</code>
-      set so Select2 and the browser knows that they should be selected. The
-      <code>value</code> attribute of the option should also be set to the value
-      that will be returned from the server for the result, so Select2 can
-      highlight it as selected in the dropdown. The text within the option
-      should also reflect the value that should be displayed by default for the
-      option.
-    </p>
-
-    <h2 id="new-matcher">Advanced matching of searches</h2>
-
-    <p>
-      In past versions of Select2, when matching search terms to individual
-      options, which limited the control that you had when displaying results,
-      especially in cases where there was nested data. The <code>matcher</code>
-      function was only given the individual option, even if it was a nested
-      options, without any context.
-    </p>
-
-    <p>
-      With the new matcher function, only the root-level options are matched and
-      matchers are expected to limit the results of any children options that
-      they contain. This allows developers to customize how options within
-      groups can be displayed, and modify how the results are returned.
-    </p>
-
-    <p>
-      A function has been created that allows old-style matcher functions to be
-      converted to the new style. You can retrieve the function from the
-      <code>select2/compat/matcher</code> module, which should just wrap the old
-      matcher function.
-    </p>
-
-    <p>
-      So if your old code used a matcher that only displayed options if they
-      started with the term that was entered, it would look something like...
-    </p>
+        <p>
+          The options that you create should have <code>selected="selected"</code>
+          set so Select2 and the browser knows that they should be selected. The
+          <code>value</code> attribute of the option should also be set to the value
+          that will be returned from the server for the result, so Select2 can
+          highlight it as selected in the dropdown. The text within the option
+          should also reflect the value that should be displayed by default for the
+          option.
+        </p>
+
+        <h2 id="new-matcher">Advanced matching of searches</h2>
+
+        <p>
+          In past versions of Select2, when matching search terms to individual
+          options, which limited the control that you had when displaying results,
+          especially in cases where there was nested data. The <code>matcher</code>
+          function was only given the individual option, even if it was a nested
+          options, without any context.
+        </p>
+
+        <p>
+          With the new matcher function, only the root-level options are matched and
+          matchers are expected to limit the results of any children options that
+          they contain. This allows developers to customize how options within
+          groups can be displayed, and modify how the results are returned.
+        </p>
+
+        <p>
+          A function has been created that allows old-style matcher functions to be
+          converted to the new style. You can retrieve the function from the
+          <code>select2/compat/matcher</code> module, which should just wrap the old
+          matcher function.
+        </p>
+
+        <p>
+          So if your old code used a matcher that only displayed options if they
+          started with the term that was entered, it would look something like…
+        </p>
 
 <pre class="prettyprint linenums">
 function matchStart (term, text) {
@@ -216,11 +224,11 @@ $("select").select2({
 })
 </pre>
 
-    <p>
-      Then in Select2 4.0, you would need to wrap the <code>matchStart</code>
-      method (or the name of the matcher you created) with a
-      <code>oldMatcher</code> method that we have created.
-    </p>
+        <p>
+          Then in Select2 4.0, you would need to wrap the <code>matchStart</code>
+          method (or the name of the matcher you created) with a
+          <code>oldMatcher</code> method that we have created.
+        </p>
 
 <pre class="prettyprint linenums">
 function matchStart (term, text) {
@@ -238,39 +246,39 @@ $.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
 });
 </pre>
 
-    <p>
-      This will work for any matchers that only took in the search term and the
-      text of the option as parameters. If your matcher relied on the third
-      parameter containing the jQuery element representing the original
-      <code>&lt;option&gt;</code> tag, then you may need to slightly change
-      your matcher to expect the full JavaScript data object being passed in
-      instead. You can still retrieve the jQuery element from the data object
-      using the <code>data.element</code> property.
-    </p>
-
-    <h2 id="flexible-placeholders">More flexible placeholders</h2>
-
-    <p>
-      In the most recent versions of Select2, placeholders could only be
-      applied to the first (typically the default) option in a
-      <code>&lt;select&gt;</code> if it was blank. The
-      <code>placeholderOption</code> option was added to Select2 to allow users
-      using the <code>select</code> tag to select a different option, typically
-      an automatically generated option with a different value.
-    </p>
-
-    <p>
-      The <code>placeholder</code> option can now take an object as well as just
-      a string. This replaces the need for the old
-      <code>placeholderOption</code>, as now the <code>id</code> of the object
-      can be set to the <code>value</code> attribute of the
-      <code>&lt;option&gt;</code> tag.
-    </p>
-
-    <p>
-      For a select that looks like the following, where the first option (with a
-      value of <code>-1</code>) is the placeholder option...
-    </p>
+        <p>
+          This will work for any matchers that only took in the search term and the
+          text of the option as parameters. If your matcher relied on the third
+          parameter containing the jQuery element representing the original
+          <code>&lt;option&gt;</code> tag, then you may need to slightly change
+          your matcher to expect the full JavaScript data object being passed in
+          instead. You can still retrieve the jQuery element from the data object
+          using the <code>data.element</code> property.
+        </p>
+
+        <h2 id="flexible-placeholders">More flexible placeholders</h2>
+
+        <p>
+          In the most recent versions of Select2, placeholders could only be
+          applied to the first (typically the default) option in a
+          <code>&lt;select&gt;</code> if it was blank. The
+          <code>placeholderOption</code> option was added to Select2 to allow users
+          using the <code>select</code> tag to select a different option, typically
+          an automatically generated option with a different value.
+        </p>
+
+        <p>
+          The <code>placeholder</code> option can now take an object as well as just
+          a string. This replaces the need for the old
+          <code>placeholderOption</code>, as now the <code>id</code> of the object
+          can be set to the <code>value</code> attribute of the
+          <code>&lt;option&gt;</code> tag.
+        </p>
+
+        <p>
+          For a select that looks like the following, where the first option (with a
+          value of <code>-1</code>) is the placeholder option…
+        </p>
 
 <pre class="prettyprint linenums">
 &lt;select&gt;
@@ -279,11 +287,11 @@ $.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
 &lt;/select&gt;
 </pre>
 
-    <p>
-      You would have previously had to get the placeholder option through the
-      <code>placeholderOption</code>, but now you can do it through the
-      <code>placeholder</code> option by setting an <code>id</code>.
-    </p>
+        <p>
+          You would have previously had to get the placeholder option through the
+          <code>placeholderOption</code>, but now you can do it through the
+          <code>placeholder</code> option by setting an <code>id</code>.
+        </p>
 
 <pre class="prettyprint linenums">
 $("select").select2({
@@ -294,62 +302,62 @@ $("select").select2({
 })
 </pre>
 
-    <p>
-      And Select2 will automatically display the placeholder when the value of
-      the select is <code>-1</code>, which it will be by default. This does not
-      break the old functionality of Select2 where the placeholder option was
-      blank by default.
-    </p>
-
-    <h2 id="value-ordering">Display reflects the actual order of the values</h2>
-
-    <p>
-      In past versions of Select2, choices were displayed in the order that
-      they were selected. In cases where Select2 was used on a
-      <code>&lt;select&gt;</code> element, the order that the server received
-      the selections did not always match the order that the choices were
-      displayed, resulting in confusion in situations where the order is
-      important.
-    </p>
-
-    <p>
-      Select2 will now order selected choices in the same order that will be
-      sent to the server.
-    </p>
-
-    <h2 id="changed-options">Changed method and option names</h2>
-
-    <p>
-      When designing the future option set for Select2 4.0, special care was
-      taken to ensure that the most commonly used options were brought over.
-      For the most part, the commonly used options of Select2 can still be
-      referenced under their previous names, but there were some changes which
-      have been noted.
-    </p>
-
-    <h3 id="removed-initselection">
-      Removed the requirement of <code>initSelection</code>
-    </h3>
-
-    <p>
-      In the past, whenever you wanted to use a custom data adapter, such as
-      AJAX or tagging, you needed to help Select2 out in determining the initial
-      values that were selected. This was typically done through the
-      <code>initSelection</code> option, which took the underlying data of the
-      input and converted it into data objects that Select2 could use.
-    </p>
-
-    <p>
-      This is now handled by
-      <a href="options.html#dataAdapter">the data adapter</a> in the
-      <code>current</code> method, which allows Select2 to convert the currently
-      selected values into data objects that can be displayed. The default
-      implementation converts the text and value of <code>option</code> elements
-      into data objects, and is probably suitable for most cases. An example of
-      the old <code>initSelection</code> option is included below, which
-      converts the value of the selected options into a data object with both
-      the <code>id</code> and <code>text</code> matching the selected value.
-    </p>
+        <p>
+          And Select2 will automatically display the placeholder when the value of
+          the select is <code>-1</code>, which it will be by default. This does not
+          break the old functionality of Select2 where the placeholder option was
+          blank by default.
+        </p>
+
+        <h2 id="value-ordering">Display reflects the actual order of the values</h2>
+
+        <p>
+          In past versions of Select2, choices were displayed in the order that
+          they were selected. In cases where Select2 was used on a
+          <code>&lt;select&gt;</code> element, the order that the server received
+          the selections did not always match the order that the choices were
+          displayed, resulting in confusion in situations where the order is
+          important.
+        </p>
+
+        <p>
+          Select2 will now order selected choices in the same order that will be
+          sent to the server.
+        </p>
+
+        <h2 id="changed-options">Changed method and option names</h2>
+
+        <p>
+          When designing the future option set for Select2 4.0, special care was
+          taken to ensure that the most commonly used options were brought over.
+          For the most part, the commonly used options of Select2 can still be
+          referenced under their previous names, but there were some changes which
+          have been noted.
+        </p>
+
+        <h3 id="removed-initselection">
+          Removed the requirement of <code>initSelection</code>
+        </h3>
+
+        <p>
+          In the past, whenever you wanted to use a custom data adapter, such as
+          AJAX or tagging, you needed to help Select2 out in determining the initial
+          values that were selected. This was typically done through the
+          <code>initSelection</code> option, which took the underlying data of the
+          input and converted it into data objects that Select2 could use.
+        </p>
+
+        <p>
+          This is now handled by
+          <a href="options.html#dataAdapter">the data adapter</a> in the
+          <code>current</code> method, which allows Select2 to convert the currently
+          selected values into data objects that can be displayed. The default
+          implementation converts the text and value of <code>option</code> elements
+          into data objects, and is probably suitable for most cases. An example of
+          the old <code>initSelection</code> option is included below, which
+          converts the value of the selected options into a data object with both
+          the <code>id</code> and <code>text</code> matching the selected value.
+        </p>
 
 <pre class="prettyprint linenums">
 initSelection : function (element, callback) {
@@ -361,19 +369,20 @@ initSelection : function (element, callback) {
 }
 </pre>
 
-    <p>
-      When using the new <code>current</code> method of the custom data adapter,
-      <strong>this method is called any time Select2 needs a list</strong> of
-      the currently selected options. This is different from the old
-      <code>initSelection</code> in that it was only called once, so it could
-      suffer from being relatively slow to process the data (such as from a
-      remote data source).
-    </p>
+        <p>
+          When using the new <code>current</code> method of the custom data adapter,
+          <strong>this method is called any time Select2 needs a list</strong> of
+          the currently selected options. This is different from the old
+          <code>initSelection</code> in that it was only called once, so it could
+          suffer from being relatively slow to process the data (such as from a
+          remote data source).
+        </p>
 
 <pre class="prettyprint linenums">
-$.fn.select2.amd.require(
-['select2/data/array', 'select2/utils'],
-function (ArrayData, Utils) {
+$.fn.select2.amd.require([
+  'select2/data/array',
+  'select2/utils'
+], function (ArrayData, Utils) {
   function CustomData ($element, options) {
     CustomData.__super__.constructor.call(this, $element, options);
   }
@@ -404,28 +413,28 @@ function (ArrayData, Utils) {
 }
 </pre>
 
-    <p>
-      The new <code>current</code> method of the data adapter works in a similar
-      way to the old <code>initSelection</code> method, with three notable
-      differences. The first, and most important, is that <strong>it is called
-      whenever the current selections are needed</strong> to ensure that Select2
-      is always displaying the most accurate and up to date data. No matter
-      what type of element Select2 is attached to, whether it supports a
-      single or multiple selections, the data passed to the callback
-      <strong>must be an array, even if it contains one selection</strong>.
-      The last is that there is only one parameter, the callback to be
-      executed with the latest data, and the current element that Select2 is
-      attached to is available on the class itself as
-      <code>this.$element</code>.
-    </p>
-
-    <p>
-      If you only need to load in the initial options once, and otherwise will
-      be letting Select2 handle the state of the selections, you don't need to
-      use a custom data adapter. You can just create the
-      <code>&lt;option&gt;</code> tags on your own, and Select2 will pick up
-      the changes.
-    </p>
+        <p>
+          The new <code>current</code> method of the data adapter works in a similar
+          way to the old <code>initSelection</code> method, with three notable
+          differences. The first, and most important, is that <strong>it is called
+          whenever the current selections are needed</strong> to ensure that Select2
+          is always displaying the most accurate and up to date data. No matter
+          what type of element Select2 is attached to, whether it supports a
+          single or multiple selections, the data passed to the callback
+          <strong>must be an array, even if it contains one selection</strong>.
+          The last is that there is only one parameter, the callback to be
+          executed with the latest data, and the current element that Select2 is
+          attached to is available on the class itself as
+          <code>this.$element</code>.
+        </p>
+
+        <p>
+          If you only need to load in the initial options once, and otherwise will
+          be letting Select2 handle the state of the selections, you don't need to
+          use a custom data adapter. You can just create the
+          <code>&lt;option&gt;</code> tags on your own, and Select2 will pick up
+          the changes.
+        </p>
 
 <pre class="prettyprint linenums">
 var $element = $('select').select2(); // the select element you are working with
@@ -453,30 +462,30 @@ $request.then(function (data) {
 });
 </pre>
 
-    <h3 id="query-to-data-adapter">
-      Custom data adapters instead of <code>query</code>
-    </h3>
-
-    <p>
-      <a href="http://select2.github.io/select2/#data">In the past</a>, any time
-      you wanted to hook Select2 up to a different data source you would be
-      required to implement custom <code>query</code> and
-      <code>initSelection</code> methods. This allowed Select2 to determine the
-      initial selection and the list of results to display, and it would handle
-      everything else internally, which was fine more most people.
-    </p>
-
-    <p>
-      The custom <code>query</code> and <code>initSelection</code> methods have
-      been replaced by
-      <a href="options.html#dataAdapter">custom data adapters</a> that handle
-      how Select2 stores and retrieves the data that will be displayed to the
-      user. An example of the old <code>query</code> option is provided below,
-      which is
-      <a href="http://select2.github.io/select2/#data">the same as the old example</a>,
-      and it generates results that contain the search term repeated a certain
-      number of times.
-    </p>
+        <h3 id="query-to-data-adapter">
+          Custom data adapters instead of <code>query</code>
+        </h3>
+
+        <p>
+          <a href="http://select2.github.io/select2/#data">In the past</a>, any time
+          you wanted to hook Select2 up to a different data source you would be
+          required to implement custom <code>query</code> and
+          <code>initSelection</code> methods. This allowed Select2 to determine the
+          initial selection and the list of results to display, and it would handle
+          everything else internally, which was fine more most people.
+        </p>
+
+        <p>
+          The custom <code>query</code> and <code>initSelection</code> methods have
+          been replaced by
+          <a href="options.html#dataAdapter">custom data adapters</a> that handle
+          how Select2 stores and retrieves the data that will be displayed to the
+          user. An example of the old <code>query</code> option is provided below,
+          which is
+          <a href="http://select2.github.io/select2/#data">the same as the old example</a>,
+          and it generates results that contain the search term repeated a certain
+          number of times.
+        </p>
 
 <pre class="prettyprint linenums">
 query: function (query) {
@@ -490,16 +499,17 @@ query: function (query) {
 }
 </pre>
 
-    <p>
-      This has been replaced by custom data adapters which define a similarly
-      named <code>query</code> method. The comparable data adapter is provided
-      below as an example.
-    </p>
+        <p>
+          This has been replaced by custom data adapters which define a similarly
+          named <code>query</code> method. The comparable data adapter is provided
+          below as an example.
+        </p>
 
 <pre class="prettyprint linenums">
-$.fn.select2.amd.require(
-['select2/data/array', 'select2/utils'],
-function (ArrayData, Utils) {
+$.fn.select2.amd.require([
+  'select2/data/array',
+  'select2/utils'
+], function (ArrayData, Utils) {
   function CustomData ($element, options) {
     CustomData.__super__.constructor.call(this, $element, options);
   }
@@ -533,64 +543,64 @@ function (ArrayData, Utils) {
 }
 </pre>
 
-    <p>
-      The new <code>query</code> method of the data adapter is very similar to
-      the old <code>query</code> option that was passed into Select2 when
-      initializing it. The old <code>query</code> argument is mostly the same as
-      the new <code>params</code> that are passed in to query on, and the
-      callback that should be used to return the results is now passed in as the
-      second parameter.
-    </p>
-
-    <h3 id="changed-templating">Renamed templating options</h3>
-
-    <p>
-      Select2 previously provided multiple options for formatting the results
-      list and selected options, commonly referred to as "formatters", using the
-      <code>formatSelection</code> and <code>formatResult</code> options. As the
-      "formatters" were also used for things such as localization,
-      <a href="#changed-translations">which has also changed</a>, they have been
-      renamed to <code>templateSelection</code> and <code>templateResult</code>
-      and their signatures have changed as well.
-    </p>
-
-    <p>
-      You should refer to the updated
-      <a href="options.html#templating">documentation on templates</a> when
-      migrating from previous versions of Select2.
-    </p>
-
-    <h3 id="changed-id">
-      The <code>id</code> and <code>text</code> properties are strictly enforced
-    </h3>
-
-    <p>
-      When working with array and AJAX data in the past, Select2 allowed a
-      custom <code>id</code> function or attribute to be set in various places,
-      ranging from the initialization of Select2 to when the remote data was
-      being returned. This allowed Select2 to better integrate with existing
-      data sources that did not necessarily use the <code>id</code> attribute to
-      indicate the unique identifier for an object.
-    </p>
-
-    <p>
-      Select2 no longer supports a custom <code>id</code> or <code>text</code>
-      to be used, but provides integration points for converting incorrect data
-      to the expected format.
-    </p>
-
-    <h4>
-      When working with array data
-    </h4>
-
-    <p>
-      Select2 previously supported defining array data as an object that matched
-      the signature of an AJAX response. A <code>text</code> property could be
-      specified that would map the given property to the <code>text</code>
-      property on the individual objects. You can now do this when initializing
-      Select2 by using the following jQuery code to map the old
-      <code>text</code> and <code>id</code> properties to the new ones.
-    </p>
+        <p>
+          The new <code>query</code> method of the data adapter is very similar to
+          the old <code>query</code> option that was passed into Select2 when
+          initializing it. The old <code>query</code> argument is mostly the same as
+          the new <code>params</code> that are passed in to query on, and the
+          callback that should be used to return the results is now passed in as the
+          second parameter.
+        </p>
+
+        <h3 id="changed-templating">Renamed templating options</h3>
+
+        <p>
+          Select2 previously provided multiple options for formatting the results
+          list and selected options, commonly referred to as "formatters", using the
+          <code>formatSelection</code> and <code>formatResult</code> options. As the
+          "formatters" were also used for things such as localization,
+          <a href="#changed-translations">which has also changed</a>, they have been
+          renamed to <code>templateSelection</code> and <code>templateResult</code>
+          and their signatures have changed as well.
+        </p>
+
+        <p>
+          You should refer to the updated
+          <a href="options.html#templating">documentation on templates</a> when
+          migrating from previous versions of Select2.
+        </p>
+
+        <h3 id="changed-id">
+          The <code>id</code> and <code>text</code> properties are strictly enforced
+        </h3>
+
+        <p>
+          When working with array and AJAX data in the past, Select2 allowed a
+          custom <code>id</code> function or attribute to be set in various places,
+          ranging from the initialization of Select2 to when the remote data was
+          being returned. This allowed Select2 to better integrate with existing
+          data sources that did not necessarily use the <code>id</code> attribute to
+          indicate the unique identifier for an object.
+        </p>
+
+        <p>
+          Select2 no longer supports a custom <code>id</code> or <code>text</code>
+          to be used, but provides integration points for converting incorrect data
+          to the expected format.
+        </p>
+
+        <h4>
+          When working with array data
+        </h4>
+
+        <p>
+          Select2 previously supported defining array data as an object that matched
+          the signature of an AJAX response. A <code>text</code> property could be
+          specified that would map the given property to the <code>text</code>
+          property on the individual objects. You can now do this when initializing
+          Select2 by using the following jQuery code to map the old
+          <code>text</code> and <code>id</code> properties to the new ones.
+        </p>
 
 <pre class="prettyprint linenums">
 var data = $.map([
@@ -610,125 +620,133 @@ var data = $.map([
 });
 </pre>
 
-    <p>
-      This will result in an array of data objects that have the <code>id</code>
-      properties that match the existing <code>pk</code> properties and
-      <code>text</code> properties that match the existing <code>word</code>
-      properties.
-    </p>
-
-    <h4>
-      When working with remote data
-    </h4>
-
-    <p>
-      The same code that was given above can be used in the
-      <code>processResults</code> method of an AJAX call to map properties there
-      as well.
-    </p>
-
-    <h3 id="changed-translations">Renamed translation options</h3>
-
-    <p>
-      In previous versions of Select2, the default messages provided to users
-      could be localized to fit the language of the website that it was being
-      used on. Select2 only comes with the English language by default, but
-      provides
-      <a href="options.html#language">community-contributed translations</a> for
-      many common languages. Many of the formatters have been moved to the
-      <code>language</code> option and the signatures of the formatters have
-      been changed to handle future additions.
-    </p>
-
-    <h3 id="changed-data">
-      Declaring options using <code>data-*</code> attributes
-    </h3>
-
-    <p>
-      In the past, Select2 has only supported declaring a subset of options
-      using <code>data-*</code> attributes. Select2 now supports declaring all
-      options using the attributes, using
-      <a href="options.html#data-attributes">the format specified in the documentation</a>.
-    </p>
-
-    <p>
-      You could previously declare the URL that was used for AJAX requests using
-      the <code>data-ajax-url</code> attribute. While Select2 still allows for
-      this, the new attribute that should be used is the
-      <code>data-ajax--url</code> attribute. Support for the old attribute will
-      be removed in Select2 4.1.
-    </p>
-
-    <p>
-      Although it was not documented, a list of possible tags could also be
-      provided using the <code>data-select2-tags</code> attribute and passing in
-      a JSON-formatted array of objects for tags. As the method for specifying
-      tags has changed in 4.0, you should now provide the array of objects using
-      the <code>data-data</code> attribute, which maps to
-      <a href="options.html#data">the array data</a> option. You should also
-      enable tags by setting <code>data-tags="true"</code> on the object, to
-      maintain the ability for users to create their own options as well.
-    </p>
-
-    <p>
-      If you previously declared the list of tags as...
-    </p>
+        <p>
+          This will result in an array of data objects that have the <code>id</code>
+          properties that match the existing <code>pk</code> properties and
+          <code>text</code> properties that match the existing <code>word</code>
+          properties.
+        </p>
+
+        <h4>
+          When working with remote data
+        </h4>
+
+        <p>
+          The same code that was given above can be used in the
+          <code>processResults</code> method of an AJAX call to map properties there
+          as well.
+        </p>
+
+        <h3 id="changed-translations">Renamed translation options</h3>
+
+        <p>
+          In previous versions of Select2, the default messages provided to users
+          could be localized to fit the language of the website that it was being
+          used on. Select2 only comes with the English language by default, but
+          provides
+          <a href="options.html#language">community-contributed translations</a> for
+          many common languages. Many of the formatters have been moved to the
+          <code>language</code> option and the signatures of the formatters have
+          been changed to handle future additions.
+        </p>
+
+        <h3 id="changed-data">
+          Declaring options using <code>data-*</code> attributes
+        </h3>
+
+        <p>
+          In the past, Select2 has only supported declaring a subset of options
+          using <code>data-*</code> attributes. Select2 now supports declaring all
+          options using the attributes, using
+          <a href="options.html#data-attributes">the format specified in the documentation</a>.
+        </p>
+
+        <p>
+          You could previously declare the URL that was used for AJAX requests using
+          the <code>data-ajax-url</code> attribute. While Select2 still allows for
+          this, the new attribute that should be used is the
+          <code>data-ajax--url</code> attribute. Support for the old attribute will
+          be removed in Select2 4.1.
+        </p>
+
+        <p>
+          Although it was not documented, a list of possible tags could also be
+          provided using the <code>data-select2-tags</code> attribute and passing in
+          a JSON-formatted array of objects for tags. As the method for specifying
+          tags has changed in 4.0, you should now provide the array of objects using
+          the <code>data-data</code> attribute, which maps to
+          <a href="options.html#data">the array data</a> option. You should also
+          enable tags by setting <code>data-tags="true"</code> on the object, to
+          maintain the ability for users to create their own options as well.
+        </p>
+
+        <p>
+          If you previously declared the list of tags as…
+        </p>
 
 <pre class="prettyprint linenums">
 &lt;select data-select2-tags="[{id: '1', text: 'One', id: '2', text: 'Two'}]"&gt;&lt;/select&gt;
 </pre>
 
-    <p>
-      ...then you should now delare it as...
-    </p>
+        <p>
+          …then you should now declare it as…
+        </p>
 
 <pre class="prettyprint linenums">
 &lt;select data-data="[{id: '1', text: 'One', id: '2', text: 'Two'}]" data-tags="true"&gt;&lt;/select&gt;
 </pre>
 
-    <h2 id="removed-methods">Deprecated and removed methods</h2>
+        <h2 id="removed-methods">Deprecated and removed methods</h2>
 
-    <p>
-      As Select2 now uses a <code>&lt;select&gt;</code> element for all data
-      sources, a few methods that were available by calling
-      <code>.select2()</code> are no longer required.
-    </p>
+        <p>
+          As Select2 now uses a <code>&lt;select&gt;</code> element for all data
+          sources, a few methods that were available by calling
+          <code>.select2()</code> are no longer required.
+        </p>
 
-    <h3>.select2("val")</h3>
+        <h3>.select2("val")</h3>
 
-    <p>
-      The <code>"val"</code> method has been deprecated and will be removed in
-      Select2 4.1. The deprecated method no longer includes the
-      <code>triggerChange</code> parameter.
-    </p>
+        <p>
+          The <code>"val"</code> method has been deprecated and will be removed in
+          Select2 4.1. The deprecated method no longer includes the
+          <code>triggerChange</code> parameter.
+        </p>
 
-    <p>
-      You should directly call <code>.val</code> on the underlying
-      <code>&lt;select&gt;</code> element instead. If you needed the second
-      parameter (<code>triggerChange</code>), you should also call
-      <code>.trigger("change")</code> on the element.
-    </p>
+        <p>
+          You should directly call <code>.val</code> on the underlying
+          <code>&lt;select&gt;</code> element instead. If you needed the second
+          parameter (<code>triggerChange</code>), you should also call
+          <code>.trigger("change")</code> on the element.
+        </p>
 
 <pre class="prettyprint linenums">
 $("select").val("1").trigger("change"); // instead of $("select").select2("val", "1");
 </pre>
 
-    <h3>.select2("enable")</h3>
+        <h3>.select2("enable")</h3>
 
-    <p>
-      Select2 will respect the <code>disabled</code> property of the underlying
-      select element. In order to enable or disable Select2, you should call
-      <code>.prop('disabled', true/false)</code> on the
-      <code>&lt;select&gt;</code> element. Support for the old methods will be
-      completely removed in Select2 4.1.
-    </p>
+        <p>
+          Select2 will respect the <code>disabled</code> property of the underlying
+          select element. In order to enable or disable Select2, you should call
+          <code>.prop('disabled', true/false)</code> on the
+          <code>&lt;select&gt;</code> element. Support for the old methods will be
+          completely removed in Select2 4.1.
+        </p>
 
 <pre class="prettyprint linenums">
 $("select").prop("disabled", true); // instead of $("select").enable(false);
 </pre>
-  </section>
+
+      </section>
+    </div>
+    <div class="col-md-3" role="complementary">
+
+      {% include nav/announcements-4.0.html %}
+
+    </div>
+  </div>
 </div>
 
 <script type="text/javascript">
-prettyPrint();
+  prettyPrint();
 </script>

docs/community.html

@@ -1,5 +1,5 @@
 ---
-layout: home
+layout: default
 title: Community - Select2
 slug: community
 ---
@@ -7,17 +7,15 @@ slug: community
 <section class="jumbotron">
   <div class="container">
     <h1>
-      <i class="fa fa-comments"></i>
       Community
     </h1>
+    <p class="lead">
+      Select2 has an active community that enjoys helping each other out.
+    </p>
   </div>
 </section>
 
 <div class="container">
-  <p class="lead">
-    Select2 has an active community that enjoys helping each other out.
-  </p>
-
   <section id="support">
     <div class="page-header">
       <h1>Getting support</h1>
@@ -147,7 +145,7 @@ slug: community
     </div>
 
     <p>
-      You can find more information on triaging tickets in the
+      You can find more information on getting involved with Select2 in the
       <a href="https://github.com/select2/select2/blob/master/CONTRIBUTING.md#triaging-issues-and-pull-requests">
         contributing guide.
       </a>

docs/css/s2-docs.scss

@@ -0,0 +1,19 @@
+---
+---
+@import "result-repository";
+@import "sidenav";
+@import "hamburger";
+@import "code";
+@import "featurette";
+@import "layout";
+@import "nav";
+@import "footer";
+@import "alert";
+@import "home";
+@import "examples";
+@import "social";
+@import "buttons";
+@import "anchorjs";
+@import "jumbotron";
+@import "prettify";
+@import "typography"

docs/examples.html

@@ -8,1139 +8,247 @@ slug: examples
 <script type="text/javascript" src="dist/js/i18n/es.js"></script>
 
 <style type="text/css">
-.img-flag {
-  height: 15px;
-  width: 18px;
-}
+  .img-flag {
+    height: 15px;
+    width: 18px;
+  }
 </style>
 
-<div class="container">
-  <section id="basic" class="row">
-    <div class="col-md-4">
-      <h1>The basics</h1>
-
-      <p>
-        Select2 can take a regular select box like this...
-      </p>
-
-      <p>
-        <select class="js-states form-control"></select>
-      </p>
-
-      <p>
-        and turn it into this...
-      </p>
-
-      <p>
-        <select class="js-example-basic-single js-states form-control"></select>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre class="code" data-fill-from=".js-code-basic"></pre>
-
-<script type="text/x-example-code" class="js-code-basic">
-$(document).ready(function() {
-  $(".js-example-basic-single").select2();
-});
-
-<select class="js-example-basic-single">
-  <option value="AL">Alabama</option>
-    ...
-  <option value="WY">Wyoming</option>
-</select>
-</script>
-    </div>
-  </section>
-
-  <section id="multiple" class="row">
-    <div class="col-md-4">
-      <h1>Multiple select boxes</h1>
-
-      <p>
-        Select2 also supports multi-value select boxes. The select below is declared with the <code>multiple</code> attribute.
-      </p>
-
-      <p>
-        <select class="js-example-basic-multiple js-states form-control" multiple="multiple"></select>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-multiple"></pre>
-
-<script type="text/x-example-code" class="js-code-multiple">
-$(".js-example-basic-multiple").select2();
-
-<select class="js-example-basic-multiple" multiple="multiple">
-  <option value="AL">Alabama</option>
-    ...
-  <option value="WY">Wyoming</option>
-</select>
-</script>
-    </div>
-  </section>
-
-  <section id="placeholders" class="row">
-    <div class="col-md-4">
-      <h1>Placeholders</h1>
-
-      <p>
-        A placeholder value can be defined and will be displayed until a selection is made.
-      </p>
-
-      <p>
-        <select class="js-example-placeholder-single js-states form-control">
-          <option></option>
-        </select>
-      </p>
-
-      <p>
-        Select2 uses the <code>placeholder</code> 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>.
-      </p>
-
-      <p>
-        <select class="js-example-placeholder-multiple js-states form-control" multiple="multiple"></select>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <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>
-    </div>
-  </section>
-
-  <section id="templating" class="row">
-    <div class="col-md-4">
-      <h1>Templating</h1>
-
-      <p>
-        Various display options of the Select2 component can be changed
-      </p>
-
-      <p>
-        <select class="js-example-templating js-states form-control"></select>
-      </p>
-
-      <p>
-        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>.
-      </p>
-
-      <p>
-        Templating is primarily controlled by the
-        <a href="options.html#templateResult"><code>templateResult</code></a>
-        and <a href="options.html#templateSelection"><code>templateSelection</code></a>
-        options.
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-templating"></pre>
-
-<script type="text/x-example-code" class="js-code-templating">
-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;
-};
-
-$(".js-example-templating").select2({
-  templateResult: formatState
-});
-</script>
-    </div>
-  </section>
-
-  <section id="data-array" class="row">
-    <div class="col-md-4">
-      <h1>Loading array data</h1>
-
-      <p>
-        Select2 provides a way to load the data from a local array.
-      </p>
-
-      <p>
-        <select class="js-example-data-array form-control"></select>
-      </p>
-
-      <p>
-        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.
-      </p>
-
-      <p>
-        <select class="js-example-data-array-selected form-control">
-          <option value="2" selected="selected">duplicate</option>
-        </select>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-data-array"></pre>
-
-<script type="text/x-example-code" class="js-code-data-array">
-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
-})
-
-<select class="js-example-data-array"></select>
-
-<select class="js-example-data-array-selected">
-  <option value="2" selected="selected">duplicate</option>
-</select>
-</script>
-    </div>
-  </section>
-
-  <section id="data-ajax" class="row">
-    <div class="col-md-12">
-      <h1>Loading remote data</h1>
-
-      <p>
-        Select2 comes with AJAX support built in, using jQuery's AJAX methods.
-        In this example, we can search for repositories using GitHub's API.
-      </p>
-
-      <p>
-        <select class="js-example-data-ajax form-control">
-          <option value="3620194" selected="selected">select2/select2</option>
-        </select>
-      </p>
-
-      <p>
-        When using Select2 with remote data, the HTML required for the
-        <code>select</code> is the same as any other Select2. If you need to
-        provide default selections, you just need to include an
-        <code>option</code> for each selection that contains the value and text
-        that should be displayed.
-      </p>
-
-      <pre data-fill-from=".js-code-data-ajax-html"></pre>
-
-      <p>
-        You can configure how Select2 searches for remote data using the
-        <code>ajax</code> option. More information on the individual options
-        that Select2 handles can be found in the
-        <a href="options.html#ajax">options documentation for <code>ajax</code></a>.
-      </p>
-
-      <pre data-fill-from=".js-code-data-ajax"></pre>
-
-      <p>
-        Select2 will pass any options in the <code>ajax</code> object to
-        jQuery's <code>$.ajax</code> function, or the <code>transport</code>
-        function you specify.
-      </p>
-
-<script type="text/x-example-code" class="js-code-data-ajax">
-$(".js-data-example-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, // omitted for brevity, see the source of this page
-  templateSelection: formatRepoSelection // omitted for brevity, see the source of this page
-});
-</script>
-
-<script type="text/x-example-code" class="js-code-data-ajax-html">
-<select class="js-data-example-ajax">
-  <option value="3620194" selected="selected">select2/select2</option>
-</select>
-</script>
-    </div>
-  </section>
-
-  <section id="responsive" class="row">
-    <div class="col-md-4">
-      <h1>Responsive design - Percent width</h1>
-
-      <p>
-        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.
-      </p>
-
-      <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>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-responsive"></pre>
-
-      <div class="alert alert-warning">
-        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
-        <code>style</code> declaration into the tag.
-      </div>
-
-<script type="text/x-example-code" class="js-code-responsive">
-<select class="js-example-responsive" style="width: 50%"></select>
-<select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>
-</script>
-    </div>
-  </section>
-
-  <section id="disabled" class="row">
-    <div class="col-md-4">
-      <h1>Disabled mode</h1>
-
-      <p>
-        Select2 will response the <code>disabled</code> attribute on
-        <code>&lt;select&gt;</code> elements. You can also initialize Select2
-        with <code>disabled: true</code> to get the same effect.
-      </p>
-
-      <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>
-
-      <p>
-        <button class="js-programmatic-enable btn btn-primary">
-          Enable
-        </button>
-        <button class="js-programmatic-disable btn btn-warning">
-          Disable
-        </button>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-disabled"></pre>
-
-<script type="text/javascript" class="js-code-disabled">
-$(".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>
-    </div>
-  </section>
-
-  <section id="disabled-results" class="row">
-    <div class="col-md-4">
-      <h1>Disabled results</h1>
-
-      <p>
-        Select2 will correctly handled disabled results, both with data coming
-        from a standard select (when the <code>disabled</code> attribute is set)
-        and from remote sources, where the object has
-        <code>disabled: true</code> set.
-      </p>
-
-      <p>
-        <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>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-disabled-results"></pre>
-
-<script type="text/x-example-code" class="js-code-disabled-results">
-<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>
-    </div>
-  </section>
-
-  <section id="programmatic" class="row">
-    <div class="col-md-4">
-      <h1>Programmatic access</h1>
-
-      <p>
-        Select2 supports methods that allow programmatic control of the
-        component.
-      </p>
-
-      <p>
-        <button class="js-programmatic-set-val btn btn-primary">
-          Set to California
-        </button>
-
-        <button class="js-programmatic-open btn btn-success">
-          Open
-        </button>
-
-        <button class="js-programmatic-close btn btn-success">
-          Close
-        </button>
-
-        <button class="js-programmatic-init btn btn-danger">
-          Init
-        </button>
-
-        <button class="js-programmatic-destroy btn btn-danger">
-          Destroy
-        </button>
-      </p>
-
-      <p>
-        <select class="js-example-programmatic js-states form-control"></select>
-      </p>
-
-      <p>
-        <button class="js-programmatic-multi-set-val btn btn-primary">
-          Set to California and Alabama
-        </button>
-
-        <button class="js-programmatic-multi-clear btn btn-primary">
-          Clear
-        </button>
-      </p>
-
-      <p>
-        <select class="js-example-programmatic-multi js-states form-control" multiple="multiple"></select>
-      </p>
-
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-programmatic"></pre>
-
-<script type="text/javascript" class="js-code-programmatic">
-var $example = $(".js-example-programmatic");
-var $exampleMulti = $(".js-example-programmatic-multi");
-
-$(".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>
-    </div>
-  </section>
-
-  <section id="multiple-max" class="row">
-    <div class="col-md-4">
-      <h1>Limiting the number of selections</h1>
-      <p>Select2 multi-value select boxes can set restrictions regarding the maximum number of options selected.
-        The select below is declared with the <code>multiple</code> attribute with <code>maxSelectionLength</code> in the select2 options</p>
-
-      <p>
-        <select class="js-example-basic-multiple-limit js-states form-control" multiple="multiple"></select>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-multiple-limit"></pre>
-
-<script type="text/x-example-code" class="js-code-multiple-limit">
-$(".js-example-basic-multiple-limit").select2({
-  maximumSelectionLength: 2
-});
-</script>
-    </div>
-  </section>
+<section class="jumbotron">
+  <div class="container">
+    <h1>
+      Examples
+    </h1>
+  </div>
+</section>
 
-  <section id="hide-search" class="row">
-    <div class="col-md-4">
-      <h1>Hiding the search box</h1>
+<div class="container s2-docs-container">
+  <div class="row">
+    <div class="col-md-9" role="main">
 
-      <p>
-        Select2 allows you to hide the search box depending on the number of
-        options which are displayed. In this example, we use the value
-        <code>Infinity</code> to tell Select2 to never display the search box.
-      </p>
+      {% include examples/basics.html %}
+      {% include examples/placeholders.html %}
+      {% include examples/data.html %}
+      {% include examples/disabled-mode.html %}
+      {% include examples/disabled-results.html %}
+      {% include examples/multiple-max.html %}
+      {% include examples/hide-search.html %}
+      {% include examples/programmatic-control.html %}
+      {% include examples/tags.html %}
+      {% include examples/tokenizer.html %}
+      {% include examples/matcher.html %}
+      {% include examples/localization-rtl-diacritics.html %}
+      {% include examples/themes-templating-responsive-design.html %}
 
-      <p>
-        <select class="js-example-basic-hide-search js-states form-control"></select>
-      </p>
     </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
+    <div class="col-md-3" role="complementary">
 
-      <pre data-fill-from=".js-code-hide-search"></pre>
+      {% include nav/examples.html %}
 
-<script type="text/x-example-code" class="js-code-hide-search">
-$(".js-example-basic-hide-search").select2({
-  minimumResultsForSearch: Infinity
-});
-</script>
     </div>
-  </section>
-
-  <section id="events" class="row">
-    <div class="col-md-4">
-      <h1>Events</h1>
-
-      <p>
-        Select2 will trigger some events on the original select element,
-        allowing you to integrate it with other components. You can find more
-        information on events
-        <a href="options.html#events">on the options page</a>.
-      </p>
-
-      <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>
-
-      <p>
-        <code>change</code> is fired whenever an option is selected or removed.
-      </p>
-
-      <p>
-        <code>select2:open</code> is fired whenever the dropdown is opened.
-        <code>select2:opening</code> is fired before this and can be prevented.
-      </p>
-
-      <p>
-        <code>select2:close</code> is fired whenever the dropdown is closed.
-        <code>select2:closing</code> is fired before this and can be prevented.
-      </p>
-
-      <p>
-        <code>select2:select</code> is fired whenever a result is selected.
-        <code>select2:selecting</code> is fired before this and can be prevented.
-      </p>
+  </div>
+</div>
 
-      <p>
-        <code>select2:unselect</code> is fired whenever a result is unselected.
-        <code>select2:unselecting</code> is fired before this and can be prevented.
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
+{% include js-source-states.html %}
 
-      <ul class="js-event-log"></ul>
+<script type="text/javascript">
+  var $states = $(".js-source-states");
+  var statesOptions = $states.html();
+  $states.remove();
 
-      <pre data-fill-from=".js-code-events"></pre>
+  $(".js-states").append(statesOptions);
 
-<script type="text/javascript" class="js-code-events">
-var $eventLog = $(".js-event-log");
-var $eventSelect = $(".js-example-events");
+  $("[data-fill-from]").each(function () {
+    var $this = $(this);
 
-$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); });
+    var codeContainer = $this.data("fill-from");
+    var $container = $(codeContainer);
 
-$eventSelect.on("change", function (e) { log("change"); });
+    var code = $.trim($container.html());
 
-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();
-    });
+    $this.text(code);
+    $this.addClass("prettyprint linenums");
   });
-}
-</script>
-    </div>
-  </section>
-
-  <section id="tags" class="row">
-    <div class="col-md-4">
-      <h1>Tagging support</h1>
-
-      <p>
-        Select2 can be used to quickly set up fields used for tagging.
-      </p>
-
-      <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>
-
-      <p>
-        Note that when tagging is enabled the user can select from pre-existing
-        options or create a new tag by picking the first choice, which is what
-        the user has typed into the search box so far.
-      </p>
-
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-tags"></pre>
-
-<script type="text/x-example-code" class="js-code-tags">
-$(".js-example-tags").select2({
-  tags: true
-})
-</script>
-    </div>
-  </section>
 
-  <section id="tokenizer" class="row">
-    <div class="col-md-4">
-      <h1>Automatic tokenization</h1>
+  prettyPrint();
 
-      <p>
-        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.
-      </p>
+  $.fn.select2.amd.require([
+    "select2/core",
+    "select2/utils",
+    "select2/compat/matcher"
+  ], function (Select2, Utils, oldMatcher) {
+    var $basicSingle = $(".js-example-basic-single");
+    var $basicMultiple = $(".js-example-basic-multiple");
+    var $limitMultiple = $(".js-example-basic-multiple-limit");
 
-      <p>
-        <select class="js-example-tokenizer form-control" multiple="multiple">
-          <option>red</option>
-          <option>blue</option>
-          <option>green</option>
-        </select>
-      </p>
+    var $dataArray = $(".js-example-data-array");
+    var $dataArraySelected = $(".js-example-data-array-selected");
 
-      <p>
-        The separators that should be used when tokenizing can be specified
-        using the <a href="options.html#tokenSeparators">tokenSeparators</a>
-        options.
-      </p>
+    var data = [
+      { id: 0, text: 'enhancement' },
+      { id: 1, text: 'bug' },
+      { id: 2, text: 'duplicate' },
+      { id: 3, text: 'invalid' },
+      { id: 4, text: 'wontfix' }
+    ];
 
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
+    var $ajax = $(".js-example-data-ajax");
 
-      <pre data-fill-from=".js-code-tokenizer"></pre>
+    var $disabledResults = $(".js-example-disabled-results");
 
-<script type="text/x-example-code" class="js-code-tokenizer">
-$(".js-example-tokenizer").select2({
-  tags: true,
-  tokenSeparators: [',', ' ']
-})
-</script>
-    </div>
-  </section>
+    var $tags = $(".js-example-tags");
 
-  <section id="matcher" class="row">
-    <div class="col-md-4">
-      <h1>Custom matcher</h1>
+    var $matcherStart = $('.js-example-matcher-start');
 
-      <p>
-        Unlike other dropdowns on this page, this one matches options only if
-        the term appears in the beginning of the string as opposed to anywhere:
-      </p>
+    var $diacritics = $(".js-example-diacritics");
+    var $language = $(".js-example-language");
 
-      <p>
-        <select class="js-example-matcher-start js-states form-control"></select>
-      </p>
+    $.fn.select2.defaults.set("width", "100%");
 
-      <p>
-        This custom matcher uses a
-        <a href="options.html#compat-matcher">compatibility module</a> that is
-        only bundled in the
-        <a href="index.html#builds-full">full version of Select2</a>. You also
-        have the option of using a
-        <a href="options.html#matcher">more complex matcher</a>.
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-matcher-start"></pre>
-
-<script type="text/x-example-code" class="js-code-matcher-start">
-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>
-    </div>
-  </section>
-
-  <section id="diacritics" class="row">
-    <div class="col-md-4">
-      <h1>Diacritics support</h1>
-
-      <p>
-        Select2's default matcher will ignore diacritics, making it easier for
-        users to filter results in international selects. Type "aero" into the
-        select below.
-      </p>
-
-      <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>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-diacritics"></pre>
-
-<script type="text/x-example-code" class="js-code-diacritics">
-$(".js-example-diacritics").select2();
-</script>
-    </div>
-  </section>
-
-  <section id="language" class="row">
-    <div class="col-md-4">
-      <h1>Multiple languages</h1>
-
-      <p>
-        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.
-      </p>
-
-      <p>
-        <select class="js-example-language js-states form-control">
-        </select>
-      </p>
-
-      <p>
-        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>.
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-language"></pre>
-
-<script type="text/x-example-code" class="js-code-language">
-$(".js-example-language").select2({
-  language: "es"
-});
-</script>
-    </div>
-  </section>
-
-  <section id="themes" class="row">
-    <div class="col-md-4">
-      <h1>Theme support</h1>
-
-      <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>
-        <select class="js-example-theme-single js-states form-control">
-        </select>
-      </p>
-
-      <p>
-        These are using the <code>classic</code> theme, which matches the old
-        look of Select2.
-      </p>
-
-      <p>
-        <select class="js-example-theme-multiple js-states form-control" multiple="multiple"></select>
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-theme"></pre>
-
-<script type="text/x-example-code" class="js-code-theme">
-$(".js-example-theme-single").select2({
-  theme: "classic"
-});
-
-$(".js-example-theme-multiple").select2({
-  theme: "classic"
-});
-</script>
-    </div>
-  </section>
-
-  <section id="rtl" class="row">
-    <div class="col-md-4">
-      <h1>RTL support</h1>
-
-      <p>
-        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.
-      </p>
-
-      <p>
-        <select class="js-example-rtl js-states form-control" dir="rtl"></select>
-      </p>
-
-      <p>
-        You can also use initialize Select2 with <code>dir: "rtl"</code> set.
-      </p>
-    </div>
-    <div class="col-md-8">
-      <h2>Example code</h2>
-
-      <pre data-fill-from=".js-code-rtl"></pre>
-
-<script type="text/x-example-code" class="js-code-rtl">
-$(".js-example-rtl").select2({
-  dir: "rtl"
-});
-</script>
-    </div>
-  </section>
-</div>
-
-<select class="js-source-states" style="display: none;">
-  <optgroup label="Alaskan/Hawaiian Time Zone">
-    <option value="AK">Alaska</option>
-    <option value="HI">Hawaii</option>
-  </optgroup>
-  <optgroup label="Pacific Time Zone">
-    <option value="CA">California</option>
-    <option value="NV">Nevada</option>
-    <option value="OR">Oregon</option>
-    <option value="WA">Washington</option>
-  </optgroup>
-  <optgroup label="Mountain Time Zone">
-    <option value="AZ">Arizona</option>
-    <option value="CO">Colorado</option>
-    <option value="ID">Idaho</option>
-    <option value="MT">Montana</option>
-    <option value="NE">Nebraska</option>
-    <option value="NM">New Mexico</option>
-    <option value="ND">North Dakota</option>
-    <option value="UT">Utah</option>
-    <option value="WY">Wyoming</option>
-  </optgroup>
-  <optgroup label="Central Time Zone">
-    <option value="AL">Alabama</option>
-    <option value="AR">Arkansas</option>
-    <option value="IL">Illinois</option>
-    <option value="IA">Iowa</option>
-    <option value="KS">Kansas</option>
-    <option value="KY">Kentucky</option>
-    <option value="LA">Louisiana</option>
-    <option value="MN">Minnesota</option>
-    <option value="MS">Mississippi</option>
-    <option value="MO">Missouri</option>
-    <option value="OK">Oklahoma</option>
-    <option value="SD">South Dakota</option>
-    <option value="TX">Texas</option>
-    <option value="TN">Tennessee</option>
-    <option value="WI">Wisconsin</option>
-  </optgroup>
-  <optgroup label="Eastern Time Zone">
-    <option value="CT">Connecticut</option>
-    <option value="DE">Delaware</option>
-    <option value="FL">Florida</option>
-    <option value="GA">Georgia</option>
-    <option value="IN">Indiana</option>
-    <option value="ME">Maine</option>
-    <option value="MD">Maryland</option>
-    <option value="MA">Massachusetts</option>
-    <option value="MI">Michigan</option>
-    <option value="NH">New Hampshire</option>
-    <option value="NJ">New Jersey</option>
-    <option value="NY">New York</option>
-    <option value="NC">North Carolina</option>
-    <option value="OH">Ohio</option>
-    <option value="PA">Pennsylvania</option>
-    <option value="RI">Rhode Island</option>
-    <option value="SC">South Carolina</option>
-    <option value="VT">Vermont</option>
-    <option value="VA">Virginia</option>
-    <option value="WV">West Virginia</option>
-  </optgroup>
-</select>
-
-<script type="text/javascript">
-var $states = $(".js-source-states");
-var statesOptions = $states.html();
-$states.remove();
-
-$(".js-states").append(statesOptions);
-
-$("[data-fill-from]").each(function () {
-  var $this = $(this);
-
-  var codeContainer = $this.data("fill-from");
-  var $container = $(codeContainer);
-
-  var code = $.trim($container.html());
-
-  $this.text(code);
-  $this.addClass("prettyprint linenums");
-});
-
-prettyPrint();
-
-$.fn.select2.amd.require(
-    ["select2/core", "select2/utils", "select2/compat/matcher"],
-    function (Select2, Utils, oldMatcher) {
-  var $basicSingle = $(".js-example-basic-single");
-  var $basicMultiple = $(".js-example-basic-multiple");
-  var $limitMultiple = $(".js-example-basic-multiple-limit");
-
-  var $dataArray = $(".js-example-data-array");
-  var $dataArraySelected = $(".js-example-data-array-selected");
+    $basicSingle.select2();
+    $basicMultiple.select2();
+    $limitMultiple.select2({
+      maximumSelectionLength: 2
+    });
 
-  var data = [{ id: 0, text: 'enhancement' }, { id: 1, text: 'bug' }, { id: 2, text: 'duplicate' }, { id: 3, text: 'invalid' }, { id: 4, text: 'wontfix' }];
+    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;
+    };
+
+    $(".js-example-templating").select2({
+      templateResult: formatState,
+      templateSelection: formatState
+    });
 
-  var $ajax = $(".js-example-data-ajax");
+    $dataArray.select2({
+      data: data
+    });
 
-  var $disabledResults = $(".js-example-disabled-results");
+    $dataArraySelected.select2({
+      data: data
+    });
 
-  var $tags = $(".js-example-tags");
+    function formatRepo (repo) {
+      if (repo.loading) return repo.text;
 
-  var $matcherStart = $('.js-example-matcher-start');
+      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>";
 
-  var $diacritics = $(".js-example-diacritics");
-  var $language = $(".js-example-language");
+      if (repo.description) {
+        markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
+      }
 
-  $basicSingle.select2();
-  $basicMultiple.select2();
-  $limitMultiple.select2({
-    maximumSelectionLength: 2
-  });
+      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>";
 
-  function formatState (state) {
-    if (!state.id) {
-      return state.text;
+      return markup;
     }
-    var $state = $(
-      '<span>' +
-        '<img src="vendor/images/flags/' +
-          state.element.value.toLowerCase() +
-        '.png" class="img-flag" /> ' +
-        state.text +
-      '</span>'
-    );
-    return $state;
-  };
 
-  $(".js-example-templating").select2({
-    templateResult: formatState,
-    templateSelection: formatState
-  });
-
-  $dataArray.select2({
-    data: data
-  });
-
-  $dataArraySelected.select2({
-    data: data
-  });
-
-  function formatRepo (repo) {
-    if (repo.loading) return repo.text;
-
-    var markup = '<div class="clearfix">' +
-    '<div class="col-sm-1">' +
-    '<img src="' + repo.owner.avatar_url + '" style="max-width: 100%" />' +
-    '</div>' +
-    '<div clas="col-sm-10">' +
-    '<div class="clearfix">' +
-    '<div class="col-sm-6">' + repo.full_name + '</div>' +
-    '<div class="col-sm-3"><i class="fa fa-code-fork"></i> ' + repo.forks_count + '</div>' +
-    '<div class="col-sm-2"><i class="fa fa-star"></i> ' + repo.stargazers_count + '</div>' +
-    '</div>';
-
-    if (repo.description) {
-      markup += '<div>' + repo.description + '</div>';
+    function formatRepoSelection (repo) {
+      return repo.full_name || repo.text;
     }
 
-    markup += '</div></div>';
-
-    return markup;
-  }
-
-  function formatRepoSelection (repo) {
-    return repo.full_name || repo.text;
-  }
-
-  $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
-        };
+    $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
       },
-      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;
+      escapeMarkup: function (markup) { return markup; },
+      minimumInputLength: 1,
+      templateResult: formatRepo,
+      templateSelection: formatRepoSelection
+    });
 
-        return {
-          results: data.items,
-          pagination: {
-            more: (params.page * 30) < data.total_count
-          }
-        };
-      },
-      cache: true
-    },
-    escapeMarkup: function (markup) { return markup; },
-    minimumInputLength: 1,
-    templateResult: formatRepo,
-    templateSelection: formatRepoSelection
-  });
+    $(".js-example-disabled").select2();
+    $(".js-example-disabled-multi").select2();
 
-  $(".js-example-disabled").select2();
-  $(".js-example-disabled-multi").select2();
+    $(".js-example-responsive").select2();
 
-  $(".js-example-responsive").select2();
+    $disabledResults.select2();
 
-  $disabledResults.select2();
+    $(".js-example-programmatic").select2();
+    $(".js-example-programmatic-multi").select2();
 
-  $(".js-example-programmatic").select2();
-  $(".js-example-programmatic-multi").select2();
+    $eventSelect.select2();
 
-  $eventSelect.select2();
+    $tags.select2({
+      tags: ['red', 'blue', 'green']
+    });
 
-  $tags.select2({
-    tags: ['red', 'blue', 'green']
-  });
+    $(".js-example-tokenizer").select2({
+      tags: true,
+      tokenSeparators: [',', ' ']
+    });
 
-  $(".js-example-tokenizer").select2({
-    tags: true,
-    tokenSeparators: [',', ' ']
-  });
+    function matchStart (term, text) {
+      if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
+        return true;
+      }
 
-  function matchStart (term, text) {
-    if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
-      return true;
+      return false;
     }
 
-    return false;
-  }
+    $matcherStart.select2({
+      matcher: oldMatcher(matchStart)
+    });
 
-  $matcherStart.select2({
-    matcher: oldMatcher(matchStart)
-  });
+    $(".js-example-basic-hide-search").select2({
+      minimumResultsForSearch: Infinity
+    });
 
-  $(".js-example-basic-hide-search").select2({
-    minimumResultsForSearch: Infinity
-  });
+    $diacritics.select2();
 
-  $diacritics.select2();
+    $language.select2({
+      language: "es"
+    });
 
-  $language.select2({
-    language: "es"
-  });
+    $(".js-example-theme-single").select2({
+      theme: "classic"
+    });
 
-  $(".js-example-theme-single").select2({
-    theme: "classic"
-  });
+    $(".js-example-theme-multiple").select2({
+      theme: "classic"
+    });
 
-  $(".js-example-theme-multiple").select2({
-    theme: "classic"
+    $(".js-example-rtl").select2();
   });
-
-  $(".js-example-rtl").select2();
-});
 </script>

docs/index.html

@@ -5,43 +5,95 @@ slug: home
 ---
 
 <main class="jumbotron" role="main">
-  <div class="container">
+  <div class="container text-center">
+    <h1>Select2</h1>
+    <p class="lead">
+      The jQuery replacement for select boxes
+    </p>
+    <p>
+      <a href="https://github.com/select2/select2/releases" class="btn btn-outline-inverse btn-lg">
+        Download Select2
+      </a>
+    </p>
+    <p class="version">
+      Currently v4.0.0</a>
+    </p>
+  </div>
+</main>
+
+{% include notice-previous.html %}
+
+<div class="container">
+  <section id="lead" class="lead">
+    Select2 gives you a customizable select box with support for searching,
+    tagging, remote data sets, infinite scrolling, and many other highly used
+    options.
+  </section>
+
+  <hr class="half-rule">
+
+
+  <div class="s2-docs-featurette">
     <div class="row">
-      <div class="col-md-6 text-center">
-        <h1>Select2</h1>
-        <p class="lead">
-          The jQuery replacement for select boxes
+      <div class="col-sm-4">
+        <i class="fa fa-language"></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="col-md-6 jumbotron-side text-center">
+
+      <div class="col-sm-4">
+        <i class="fa fa-database"></i>
+        <h4>Remote data support</h4>
         <p>
-          <a href="https://github.com/select2/select2/releases" class="btn btn-success btn-lg">
-            <i class="fa fa-download fa-lg"></i>
-            Download
-          </a>
+          <a href="examples.html#data-ajax">Using AJAX</a> you can efficiently
+          search large lists of items.
         </p>
+      </div>
+
+      <div class="col-sm-4">
+        <i class="fa fa-paint-brush"></i>
+        <h4>Fits in with your theme</h4>
         <p>
-          <strong>Version</strong> 4.0.0
+          Fully skinnable, CSS built with Sass and an
+          <a href="https://github.com/fk/select2-bootstrap-theme">optional theme for Bootstrap 3</a>.
         </p>
       </div>
     </div>
-  </div>
-</main>
 
-<section class="notice-previous">
-  <div class="container">
-    <a href="http://select2.github.io/select2/">Looking for the Select2 3.5.2 docs?</a>
-    We have moved them to a new location
-    <a href="announcements-4.0.html">while we push forward with Select2 4.0</a>.
+    <div class="row">
+      <div class="col-sm-4">
+        <i class="fa fa-plug"></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="col-sm-4">
+        <i class="fa fa-tag"></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="col-sm-4">
+        <i class="fa fa-html5"></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>
-</section>
 
-<div class="container">
-  <section id="lead" class="lead">
-    Select2 gives you a customizable select box with support for searching,
-    tagging, remote data sets, infinite scrolling, and many other highly used
-    options.
-  </section>
+  <hr class="half-rule">
 
   <section id="getting-started">
     <h2>
@@ -67,10 +119,12 @@ slug: home
 
     <ol>
       <li>
-        Include the following lines of code in the <code>&lt;head&gt;</code>
-        section of your HTML.
+        <p>
+          Include the following lines of code in the <code>&lt;head&gt;</code>
+          section of your HTML.
+        </p>
 
-<pre class="code">
+<pre class="code prettyprint">
 &lt;link href="//cdnjs.cloudflare.com/ajax/libs/select2/4.0.0/css/select2.min.css" rel="stylesheet" /&gt;
 &lt;script src="//cdnjs.cloudflare.com/ajax/libs/select2/4.0.0/js/select2.min.js"&gt;&lt;/script&gt;
 </pre>
@@ -82,14 +136,17 @@ slug: home
         </div>
       </li>
       <li>
-        Initialize Select2 on the <code>&lt;select&gt;</code> element that you
-        want to make awesome.
+        <p>
+          Initialize Select2 on the <code>&lt;select&gt;</code> element that you
+          want to make awesome.
+        </p>
 
-<pre class="code">
+<pre class="code prettyprint">
 &lt;script type="text/javascript"&gt;
   $('select').select2();
 &lt;/script&gt;
 </pre>
+
       </li>
       <li>
         Check out the <a href="examples.html">examples page</a> to start using
@@ -108,19 +165,24 @@ slug: home
 
     <ol>
       <li>
-        <a href="https://github.com/select2/select2/tags">
-          Download the code
-        </a>
-        from GitHub and copy the <code>dist</code> directory to your project.
+        <p>
+          <a href="https://github.com/select2/select2/tags">
+            Download the code
+          </a>
+          from GitHub and copy the <code>dist</code> directory to your project.
+        </p>
       </li>
       <li>
-        Include the following lines of code in the <code>&lt;head&gt;</code>
-        section of your HTML.
+        <p>
+          Include the following lines of code in the <code>&lt;head&gt;</code>
+          section of your HTML.
+        </p>
 
-<pre class="code">
+<pre class="code prettyprint">
 &lt;link href="path/to/select2.min.css" rel="stylesheet" /&gt;
 &lt;script src="path/to/select2.min.js"&gt;&lt;/script&gt;
 </pre>
+
       </li>
       <li>
         Check out the <a href="examples.html">examples page</a> to start using
@@ -173,28 +235,4 @@ slug: home
       </tbody>
     </table>
   </section>
-
-  <section id="about">
-    <h2>
-      About
-    </h2>
-
-    <ul>
-      <li>
-        <a href="https://github.com/select2/select2">
-          Source code, hosted on GitHub
-        </a>
-      </li>
-      <li>
-        <a href="https://github.com/select2/select2/issues">
-          Bug tracker
-        </a>
-      </li>
-      <li>
-        <a href="community.html">
-          Community and support
-        </a>
-      </li>
-    </ul>
-  </section>
 </div>

docs/options.html

@@ -4,1613 +4,34 @@ title: Options - Select2
 slug: options
 ---
 
-<div class="container">
-  <section id="core">
-    <div class="page-header">
-      <h1>Core options</h1>
-    </div>
-
-    <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 linenums">
-&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 linenums">
-&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>
-      Display
-    </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-4">
-        <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-8">
-        <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 linenums">
-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-8">
-        <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-4">
-        <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-4">
-        <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-8">
-        <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>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 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>
-      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>
-
-  <section id="dropdown">
-    <div class="page-header">
-      <h1>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-4">
-        <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-8">
-        <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-4">
-        <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-8">
-        <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>
-
-  <section id="events">
-    <div 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>
-      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>
-      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>
-
-  <section id="adapters">
-    <div class="page-header">
-      <h1>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>
-      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>
-
-  <section id="defaults">
-    <div class="page-header">
-      <h1>Setting default options</h1>
-    </div>
-
-    <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 linenums">
-$.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>
-
-  <section id="compatibility">
-    <div class="page-header">
-      <h1>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>
+<section class="jumbotron">
+  <div class="container">
+    <h1>
+      Options
+    </h1>
+  </div>
+</section>
 
-          <dt>Value</dt>
-          <dd>
-            A function taking a <code>callback</code>
-          </dd>
-        </dl>
-      </div>
+<div class="container s2-docs-container">
+  <div class="row">
+    <div class="col-md-9" role="main">
 
-      <div class="col-sm-6">
-        <dl class="dl-horizontal">
-          <dt>Adapter</dt>
-          <dd>
-            <code title="select2/data/base">DataAdapter</code>
-          </dd>
+      {% include options/core-options.html %}
+      {% include options/dropdown.html %}
+      {% include options/events.html %}
+      {% include options/adapters.html %}
+      {% include options/setting-default-options.html %}
+      {% include options/backwards-compatibility.html %}
 
-          <dt>Decorator</dt>
-          <dd>
-            <code title="select2/compat/initSelection">InitSelection</code>
-          </dd>
-        </dl>
-      </div>
     </div>
+    <div class="col-md-3" role="complementary">
 
-    <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>
+      {% include nav/options.html %}
 
-          <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>
-
-  <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>
+  </div>
 </div>
 
 <script type="text/javascript">
-prettyPrint();
+  prettyPrint();
 </script>

docs/vendor/css/anchor.css

@@ -0,0 +1,78 @@
+/**
+ * Store the link icon as a base64 embedded icon font.
+ */
+@font-face {
+  font-family: 'anchorjs-icons';
+  src: url(data:application/x-font-ttf;charset=utf-8;base64,AAEAAAALAIAAAwAwT1MvMg6v8yoAAAC8AAAAYGNtYXDL8RqdAAABHAAAADxnYXNwAAAAEAAAAVgAAAAIZ2x5Zkm2oNUAAAFgAAABWGhlYWQAHd4cAAACuAAAADZoaGVhB3sECwAAAvAAAAAkaG10eAYAAEcAAAMUAAAADGxvY2EACgCsAAADIAAAAAhtYXhwAAYAcAAAAygAAAAgbmFtZUQXtNYAAANIAAABOXBvc3QAAwAAAAAEhAAAACAAAwQAAZAABQAAApkCzAAAAI8CmQLMAAAB6wAzAQkAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAACDmAAPA/8D/wAPAAEAAAAAAAAAAAAAAAAAAAAAgAAAAAAACAAAAAwAAABQAAwABAAAAFAAEACgAAAAGAAQAAQACACDmAP//AAAAIOYA////4RoCAAEAAAAAAAAAAQAB//8ADwABAAAAAAAAAAAAAgAANzkBAAAAAAIARwAHA7kDeQA2AG0AAAEnLgEiBg8BDgEUFh8BHgMXNy4DLwEuATQ2PwE+ATIWHwEeARQGDwEeAxU3PgE0JicBLgMnBx4DHwEeARQGDwEOASImLwEuATQ2PwEuAzUHDgEUFh8BHgEyNj8BPgE0Ji8BA7kEI1ldWiPaIyQkIwQDBgYGBFAEBwYHAwQTExMT2xMwMjETBBMTExNjBwkGA5gkIyMk/r4DBgYGBFAEBwYHAwQTExMT2xMwMjETBBMTExNjBwkGA5gkIyMkBCNZXVoj2iMkJCMEA3UEJCMjJNojWV1aIwQDBgUFA1ACBQUFAwQUMDIxE9oTExMTBBMxMjATYxAhISIRmSNaXVkj/sYDBgUFA1ACBQUFAwQUMDIxE9oTExMTBBMxMjATYxAhISIRmSNaXVkjBCQjIyTaI1ldWiMEAAEAAAABAABR/4xQXw889QALBAAAAAAAzqNM0wAAAADOo0zTAAAAAAO5A3kAAAAIAAIAAAAAAAAAAQAAA8D/wAAABAAAAABHA7kAAQAAAAAAAAAAAAAAAAAAAAMAAAAAAgAAAAQAAEcAAAAAAAoArAABAAAAAwBuAAIAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAADgCuAAEAAAAAAAEADgAAAAEAAAAAAAIADgBHAAEAAAAAAAMADgAkAAEAAAAAAAQADgBVAAEAAAAAAAUAFgAOAAEAAAAAAAYABwAyAAEAAAAAAAoAKABjAAMAAQQJAAEADgAAAAMAAQQJAAIADgBHAAMAAQQJAAMADgAkAAMAAQQJAAQADgBVAAMAAQQJAAUAFgAOAAMAAQQJAAYADgA5AAMAAQQJAAoAKABjAGkAYwBvAG0AbwBvAG4AVgBlAHIAcwBpAG8AbgAgADAALgAwAGkAYwBvAG0AbwBvAG5pY29tb29uAGkAYwBvAG0AbwBvAG4AUgBlAGcAdQBsAGEAcgBpAGMAbwBtAG8AbwBuAEcAZQBuAGUAcgBhAHQAZQBkACAAYgB5ACAASQBjAG8ATQBvAG8AbgAAAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA) format('truetype'),
+       url(data:application/font-woff;charset=utf-8;base64,d09GRgABAAAAAATwAAsAAAAABKQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABPUy8yAAABCAAAAGAAAABgDq/zKmNtYXAAAAFoAAAAPAAAADzL8RqdZ2FzcAAAAaQAAAAIAAAACAAAABBnbHlmAAABrAAAAVgAAAFYSbag1WhlYWQAAAMEAAAANgAAADYAHd4caGhlYQAAAzwAAAAkAAAAJAd7BAtobXR4AAADYAAAAAwAAAAMBgAAR2xvY2EAAANsAAAACAAAAAgACgCsbWF4cAAAA3QAAAAgAAAAIAAGAHBuYW1lAAADlAAAATkAAAE5RBe01nBvc3QAAATQAAAAIAAAACAAAwAAAAMEAAGQAAUAAAKZAswAAACPApkCzAAAAesAMwEJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAg5gADwP/A/8ADwABAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAgAAAAMAAAAUAAMAAQAAABQABAAoAAAABgAEAAEAAgAg5gD//wAAACDmAP///+EaAgABAAAAAAAAAAEAAf//AA8AAQAAAAAAAAAAAAIAADc5AQAAAAACAEcABwO5A3kANgBtAAABJy4BIgYPAQ4BFBYfAR4DFzcuAy8BLgE0Nj8BPgEyFh8BHgEUBg8BHgMVNz4BNCYnAS4DJwceAx8BHgEUBg8BDgEiJi8BLgE0Nj8BLgM1Bw4BFBYfAR4BMjY/AT4BNCYvAQO5BCNZXVoj2iMkJCMEAwYGBgRQBAcGBwMEExMTE9sTMDIxEwQTExMTYwcJBgOYJCMjJP6+AwYGBgRQBAcGBwMEExMTE9sTMDIxEwQTExMTYwcJBgOYJCMjJAQjWV1aI9ojJCQjBAN1BCQjIyTaI1ldWiMEAwYFBQNQAgUFBQMEFDAyMRPaExMTEwQTMTIwE2MQISEiEZkjWl1ZI/7GAwYFBQNQAgUFBQMEFDAyMRPaExMTEwQTMTIwE2MQISEiEZkjWl1ZIwQkIyMk2iNZXVojBAABAAAAAQAAUf+MUF8PPPUACwQAAAAAAM6jTNMAAAAAzqNM0wAAAAADuQN5AAAACAACAAAAAAAAAAEAAAPA/8AAAAQAAAAARwO5AAEAAAAAAAAAAAAAAAAAAAADAAAAAAIAAAAEAABHAAAAAAAKAKwAAQAAAAMAbgACAAAAAAACAAAAAAAAAAAAAAAAAAAAAAAAAA4ArgABAAAAAAABAA4AAAABAAAAAAACAA4ARwABAAAAAAADAA4AJAABAAAAAAAEAA4AVQABAAAAAAAFABYADgABAAAAAAAGAAcAMgABAAAAAAAKACgAYwADAAEECQABAA4AAAADAAEECQACAA4ARwADAAEECQADAA4AJAADAAEECQAEAA4AVQADAAEECQAFABYADgADAAEECQAGAA4AOQADAAEECQAKACgAYwBpAGMAbwBtAG8AbwBuAFYAZQByAHMAaQBvAG4AIAAwAC4AMABpAGMAbwBtAG8AbwBuaWNvbW9vbgBpAGMAbwBtAG8AbwBuAFIAZQBnAHUAbABhAHIAaQBjAG8AbQBvAG8AbgBHAGUAbgBlAHIAYQB0AGUAZAAgAGIAeQAgAEkAYwBvAE0AbwBvAG4AAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==) format('woff');
+  font-style: normal;
+  font-weight: normal;
+}
+.anchorjs-icon {
+  font-family: 'anchorjs-icons';
+  font-style: normal;
+  font-variant: normal;
+  font-weight: normal;
+  line-height: 1;
+  speak: none;
+  text-transform: none;
+
+  /* Better Icon Rendering */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/**
+ * Link placement and hover behavior.
+ */
+.anchorjs-link {
+  opacity: 0;
+  text-decoration: none;
+}
+*:hover > .anchorjs-link,
+.anchorjs-link:focus  {
+  /* To fade links as they appear, change transition-property from 'color' to 'all' */
+  opacity: 1;
+  -webkit-transition: color .16s linear;
+  -moz-transition: color .16s linear;
+  -o-transition: color .16s linear;
+  transition: color .16s linear;
+}
+/**
+ * Make screen-reader friendly description text visually hidden.
+ */
+.anchorjs-description {
+  border: 0;
+  clip: rect(0 0 0 0);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  width: 1px;
+}
+
+/**
+ * Reasonable default styles.
+ * Feel free to override or replace these with your own.
+ */
+.anchorjs-link:link    { color: #DFD487; }
+.anchorjs-link:visited { color: #DFD487; }
+.anchorjs-link:hover   { color: #EC7963; }
+.anchorjs-link:active  { color: #EC7963; }
+
+.anchorjs-icon {
+  font-size: 90%;
+  padding-left: 6px;
+}
+
+.anchorjs-icon:before {
+  content: '\e600';
+  /* alternative icons -- uncomment to use */
+  /*
+  content: '#';
+  content: '¶';
+  content: '❡';
+  content: '§';
+  */
+}

docs/vendor/css/prettify.css

@@ -1,30 +0,0 @@
-.com { color: #93a1a1; }
-.lit { color: #195f91; }
-.pun, .opn, .clo { color: #93a1a1; }
-.fun { color: #dc322f; }
-.str, .atv { color: #D14; }
-.kwd, .linenums .tag { color: #1e347b; }
-.typ, .atn, .dec, .var { color: teal; }
-.pln { color: #48484c; }
-
-.prettyprint {
-  padding: 8px;
-  background-color: #f7f7f9;
-  border: 1px solid #e1e1e8;
-}
-.prettyprint.linenums {
-  -webkit-box-shadow: inset 40px 0 0 #fbfbfc, inset 41px 0 0 #ececf0;
-     -moz-box-shadow: inset 40px 0 0 #fbfbfc, inset 41px 0 0 #ececf0;
-          box-shadow: inset 40px 0 0 #fbfbfc, inset 41px 0 0 #ececf0;
-}
-
-/* Specify class=linenums on a pre to get line numbering */
-ol.linenums {
-  margin: 0;
-}
-ol.linenums li {
-  padding-left: 12px;
-  color: #bebec5;
-  line-height: 18px;
-  text-shadow: 0 1px 0 #fff;
-}

docs/vendor/js/anchor.min.js

@@ -0,0 +1,6 @@
+/*!
+ * AnchorJS - v0.3.1 - 2015-03-06
+ * https://github.com/bryanbraun/anchorjs
+ * Copyright (c) 2015 Bryan Braun; Licensed MIT
+ */
+function addAnchors(e){"use strict";if(e){if("string"!=typeof e)throw new Error("AnchorJS accepts only strings; you used a "+typeof e)}else e="h1, h2, h3, h4, h5, h6";var t=document.querySelectorAll(e);if(0===t.length)return!1;for(var r=document.querySelectorAll("[id]"),n=[].map.call(r,function(e){return e.id}),i=0;i<t.length;i++){var s;if(t[i].hasAttribute("id"))s=t[i].getAttribute("id");else{var o,a=document.body.textContent?"textContent":"innerText",c=t[i][a],l=c.replace(/[^\w\s-]/gi,"").replace(/\s+/g,"-").toLowerCase().substring(0,32),h=0,d=l;do void 0!==o&&(d=l+"-"+h),o=n.indexOf(d),h+=1;while(-1!==o);o=void 0,n.push(d),t[i].setAttribute("id",d),s=d}var u=s.replace(/-/g," "),p='<a class="anchorjs-link" href="#'+s+'"><span class="anchorjs-description">Anchor link for: '+u+'</span><span class="anchorjs-icon" aria-hidden="true"></span></a>';t[i].innerHTML+=p}}