diff --git a/docs/_includes/nav/options-old.html b/docs/_includes/nav/options-old.html
new file mode 100644
index 00000000..b03d3d07
--- /dev/null
+++ b/docs/_includes/nav/options-old.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>
diff --git a/docs/_includes/nav/options.html b/docs/_includes/nav/options.html
index b03d3d07..4c1be4f3 100644
--- a/docs/_includes/nav/options.html
+++ b/docs/_includes/nav/options.html
@@ -1,28 +1,53 @@
 <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>
+      <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="#setting-default-options">Changing default options</a></li>
+        <li><a href="#data-attributes">Declaring configuration in the HTML</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>
+      <a href="#data-adapters">Data adapters</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>
+        <li>
+          <a href="#data-adapters-select-tag">Using a <code>&lt;select&gt;</code></a>
+        </li>
+        <li>
+          <a href="#data">Loading data from an array</a>
+        </li>
+        <li>
+          <a href="#ajax">Connecting to a remote data source</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#selections">Displaying selections</a>
+      <ul class="nav">
+        <li>
+          <a href="#placeholder">Showing a placeholder</a>
+        </li>
+        <li>
+          <a href="#allowClear">Clearing selections</a>
+        </li>
+        <li>
+          <a href="#templateSelection">Templating</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#results">Displaying results</a>
+      <ul class="nav">
+        <li><a href="#can-i-change-when-search-results-are-loaded">Controlling result loading</a></li>
+        <li><a href="#can-i-change-how-selecting-results-works">Making selections</a></li>
+        <li><a href="#can-i-change-how-the-dropdown-is-placed">Placement</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-public">Public jQuery events</a></li>
         <li><a href="#events-internal">Internal events</a></li>
       </ul>
     </li>
@@ -37,10 +62,7 @@
       </ul>
     </li>
     <li>
-      <a href="#setting-default-options">Setting default options</a>
-    </li>
-    <li>
-      <a href="#backwards-compatibility">Backwards compatibility</a>
+      <a href="#backwards-compatibility">Deprecated options</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>
diff --git a/docs/_includes/options/adapters.html b/docs/_includes/options-old/adapters.html
similarity index 100%
rename from docs/_includes/options/adapters.html
rename to docs/_includes/options-old/adapters.html
diff --git a/docs/_includes/options/backwards-compatibility.html b/docs/_includes/options-old/backwards-compatibility.html
similarity index 100%
rename from docs/_includes/options/backwards-compatibility.html
rename to docs/_includes/options-old/backwards-compatibility.html
diff --git a/docs/_includes/options/core-options.html b/docs/_includes/options-old/core-options.html
similarity index 100%
rename from docs/_includes/options/core-options.html
rename to docs/_includes/options-old/core-options.html
diff --git a/docs/_includes/options-old/dropdown.html b/docs/_includes/options-old/dropdown.html
new file mode 100644
index 00000000..87629077
--- /dev/null
+++ b/docs/_includes/options-old/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>
diff --git a/docs/_includes/options-old/events.html b/docs/_includes/options-old/events.html
new file mode 100644
index 00000000..bf4f39a9
--- /dev/null
+++ b/docs/_includes/options-old/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>
diff --git a/docs/_includes/options/setting-default-options.html b/docs/_includes/options-old/setting-default-options.html
similarity index 100%
rename from docs/_includes/options/setting-default-options.html
rename to docs/_includes/options-old/setting-default-options.html
diff --git a/docs/_includes/options/compatibility.html b/docs/_includes/options/compatibility.html
new file mode 100644
index 00000000..a7f6197e
--- /dev/null
+++ b/docs/_includes/options/compatibility.html
@@ -0,0 +1,10 @@
+<section>
+  <h1>
+    Backwards compatibility
+  </h1>
+
+  {% include options/compatibility/matcher.html %}
+  {% include options/compatibility/initial-selection.html %}
+  {% include options/compatibility/query-function.html %}
+  {% include options/compatibility/text-input.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/compatibility/initial-selection.html b/docs/_includes/options/compatibility/initial-selection.html
new file mode 100644
index 00000000..62fd0933
--- /dev/null
+++ b/docs/_includes/options/compatibility/initial-selection.html
@@ -0,0 +1,50 @@
+<section>
+  <h2 id="initSelection">
+    Old initial selections with <code>initSelection</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
+    This has been replaced by another option and is only available in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2.
+  </p>
+
+  <p>
+    In the past, Select2 required an option called <code>initSelection</code>
+    that was defined whenever a custom data source was being used, allowing
+    for the initial selection for the component to be determined. This has
+    been replaced by the <code>current</code> method on the
+    <a href="#dataAdapter">data adapter</a>.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>initSelection</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking a <code>callback</code>
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/compat/initSelection">InitSelection</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/compatibility/introduction.html b/docs/_includes/options/compatibility/introduction.html
new file mode 100644
index 00000000..0e82aabe
--- /dev/null
+++ b/docs/_includes/options/compatibility/introduction.html
@@ -0,0 +1,18 @@
+<section>
+  <p>
+    Select2 offers limited backwards compatibility with the previously 3.5.x
+    release line, allowing people more efficiently transfer across releases
+    and get the latest features. For many of the larger changes, such as the
+    change in how custom data adapters work, compatibility modules were
+    created that will be used to assist in the upgrade process. It is not
+    recommended to rely on these compatibility modules, as they will not
+    always exist, but they make upgrading easier for major changes.
+  </p>
+
+  <p>
+    <strong>The compatibility modules are only included in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2</strong>. These files end in <code>.full.js</code>, and the
+    compatibility modules are prefixed with <code>select2/compat</code>.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/compatibility/matcher.html b/docs/_includes/options/compatibility/matcher.html
new file mode 100644
index 00000000..150f72c1
--- /dev/null
+++ b/docs/_includes/options/compatibility/matcher.html
@@ -0,0 +1,50 @@
+<section>
+  <h2 id="compat-matcher">
+    Simplified function for matching data objects
+  </h2>
+
+  <p class="alert alert-info">
+    <a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
+    This method was added to make upgrading easier from earlier versions of
+    Select2.
+  </p>
+
+  <p>
+    During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
+    <code>matcher</code> function was changed to allow for more complex
+    matching of nested objects.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>matcher</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking a search <code>term</code> and the data object
+          <code>text</code>.
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/compat/matcher">oldMatcher</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+
+  <p>
+    The <a href="examples.html#matcher">custom matcher example</a> provides a
+    guide for how to use this in your own application. For those upgrading
+    from older versions of Select2, you just need to wrap your old
+    <code>matcher</code> with this function to maintain compatibility.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/compatibility/query-function.html b/docs/_includes/options/compatibility/query-function.html
new file mode 100644
index 00000000..f5f557de
--- /dev/null
+++ b/docs/_includes/options/compatibility/query-function.html
@@ -0,0 +1,50 @@
+<section>
+  <h2 id="query">
+    Querying old data with <code>query</code>
+  </h2>
+
+  <p class="alert alert-warning">
+    <a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
+    This has been replaced by another option and is only available in the
+    <a href="index.html#builds-full" class="alert-link">full builds</a> of
+    Select2.
+  </p>
+
+  <p>
+    In the past, Select2 supported an option called <code>query</code> that
+    allowed for a custom data source to be used. This option has been replaced
+    by the <code>query</code> method on the
+    <a href="#dataAdapter">data adapter</a> and takes a very similar set of
+    parameters.
+  </p>
+
+  <div class="row">
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Key</dt>
+        <dd>
+          <code>query</code>
+        </dd>
+
+        <dt>Value</dt>
+        <dd>
+          A function taking <code>params</code> (including a <code>callback</code>)
+        </dd>
+      </dl>
+    </div>
+
+    <div class="col-sm-6">
+      <dl class="dl-horizontal">
+        <dt>Adapter</dt>
+        <dd>
+          <code title="select2/data/base">DataAdapter</code>
+        </dd>
+
+        <dt>Decorator</dt>
+        <dd>
+          <code title="select2/compat/query">Query</code>
+        </dd>
+      </dl>
+    </div>
+  </div>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/compatibility/text-input.html b/docs/_includes/options/compatibility/text-input.html
new file mode 100644
index 00000000..4cea8c86
--- /dev/null
+++ b/docs/_includes/options/compatibility/text-input.html
@@ -0,0 +1,32 @@
+<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>
\ No newline at end of file
diff --git a/docs/_includes/options/core.html b/docs/_includes/options/core.html
new file mode 100644
index 00000000..df834804
--- /dev/null
+++ b/docs/_includes/options/core.html
@@ -0,0 +1,9 @@
+<section>
+  <h1>
+    Core options
+  </h1>
+
+  {% include options/core/options.html %}
+  {% include options/core/data-attributes.html %}
+  {% include options/core/amd-support.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/core/amd-support.html b/docs/_includes/options/core/amd-support.html
new file mode 100644
index 00000000..9dfd2759
--- /dev/null
+++ b/docs/_includes/options/core/amd-support.html
@@ -0,0 +1,38 @@
+<section>
+  <h2 id="amd">
+    Can I use Select2 with my AMD or CommonJS loader?
+  </h2>
+
+  <p>
+    Yes, Select2 should work with most AMD or CommonJS loaders without any issues.
+  </p>
+
+  <h3>
+    How do I tell Select2 where to look for modules?
+  </h3>
+
+  <p>
+    For most AMD and CommonJS setups, the location of the data files used by Select2 will be automatically determined and handled without you needing to do anything.
+  </p>
+
+  <p>
+    If you are using Select2 in a build environment where preexisting module names are changed during a build step, Select2 may not be able to find optional dependencies or language files. You can manually set the prefixes to use for these files using the <code>amdBase</code> and <code>amdLanugageBase</code> options.
+  </p>
+
+<pre class="prettyprint">
+$.fn.select2.defaults.set('amdBase', 'select2/');
+$.fn.select2.defaults.set('amdLanguageBase', 'select2/i18n/');
+</pre>
+
+  <h3>
+    Select2 is being placed before jQuery in my JavaScript file
+  </h3>
+
+  <p>
+    Due to a bug in older versions of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery.
+  </p>
+
+  <p>
+    You can fix this issue by upgrading to a newer version of the r.js build tool.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/core/data-attributes.html b/docs/_includes/options/core/data-attributes.html
new file mode 100644
index 00000000..9a95e105
--- /dev/null
+++ b/docs/_includes/options/core/data-attributes.html
@@ -0,0 +1,72 @@
+<section>
+  <h2 id="data-attributes">
+    Can I declare my configuration within the HTML?
+  </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>
+
+  <h3>
+    How should <code>camelCase</code> options be written?
+  </h3>
+
+  <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" data-allow-clear="true"&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",
+  allowClear: true
+});
+</pre>
+
+  <h3>
+    Are options with nested configurations supported?
+  </h3>
+
+  <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>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/core/options.html b/docs/_includes/options/core/options.html
new file mode 100644
index 00000000..2b7cb1f4
--- /dev/null
+++ b/docs/_includes/options/core/options.html
@@ -0,0 +1,58 @@
+<section>
+  <h2 id="options">
+    How should Select2 be initialized?
+  </h2>
+
+  <h3 id="setting-default-options">
+    Can default options be set for all dropdowns?
+  </h3>
+
+  <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>.
+  </p>
+
+<pre class="prettyprint">
+$.fn.select2.defaults.set("theme", "classic");
+</pre>
+
+  <h3>
+    How can I set a default value for a nested option?
+  </h3>
+
+  <p>
+    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>
+
+  <h3>
+    How can I reset all of the global default options?
+  </h3>
+
+  <p>
+    You can reset the default options by calling
+  </p>
+
+<pre class="prettyprint">
+$.fn.select2.defaults.reset();
+</pre>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/data.html b/docs/_includes/options/data.html
new file mode 100644
index 00000000..c9c6f684
--- /dev/null
+++ b/docs/_includes/options/data.html
@@ -0,0 +1,9 @@
+<section>
+  <h1>
+    Data adapters
+  </h1>
+
+  {% include options/data/select.html %}
+  {% include options/data/array.html %}
+  {% include options/data/ajax.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/data/ajax.html b/docs/_includes/options/data/ajax.html
new file mode 100644
index 00000000..0aa3b117
--- /dev/null
+++ b/docs/_includes/options/data/ajax.html
@@ -0,0 +1,109 @@
+<section>
+  <h2 id="ajax">
+    Can Select2 be connected to a remote data source?
+  </h2>
+
+  <p>
+    Select2 supports connecting to a remote data source using the <code>ajax</code> option.
+  </p>
+
+  <h3>
+    How can I set the initially selected options when using AJAX?
+  </h3>
+
+  <p>
+    You can refer to the following Stack Overflow answer if you want to set the initial value for AJAX requests: <a href="http://stackoverflow.com/q/30316586/359284#30328989">Select2 4.0.0 initial value with AJAX</a>
+  </p>
+
+  <h3>
+    What should the results returned to Select2 look like?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    Is there a way to modify the response before passing it back to Select2?
+  </h3>
+
+  <p>
+    You can use the <code>ajax.processResults</code> option to modify the data returned from the server before passing it to Select2.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  ajax: {
+    url: '/example/api',
+    processResults: function (data) {
+      return {
+        results: data.items
+      };
+    }
+  }
+});
+</pre>
+
+  <h3>
+    A request is being triggered on every key stroke, can I delay this?
+  </h3>
+
+  <p>
+    By default, Select2 will trigger a new AJAX request whenever the user changes their search term. You can set a time limit for debouncing requests using the <code>ajax.delay</code> option.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  ajax: {
+    url: '/example/api',
+    delay: 250
+  }
+});
+</pre>
+
+  <p>
+    This will tell Select2 to wait 250 milliseconds before sending the request out to your API.
+  </p>
+
+  <h3>
+    I want to add more query parameters to the request, where can this be done?
+  </h3>
+
+  <p>
+    By default, Select2 will send the query term as well as the pagination data as query parameters in requests. You can override the data that is sent to your API, or change any of the query paramters, by overriding the <code>ajax.data</codE> option.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  ajax: {
+    data: function (params) {
+      var query = {
+        search: params.term,
+        page: params.page
+      }
+
+      // Query paramters will be ?search=[term]&page=[page]
+      return query;
+    }
+  }
+});
+</pre>
+
+  <h3>
+    Can an AJAX plugin other than <code>jQuery.ajax</code> be used?
+  </h3>
+
+  <p>
+    Select2 uses the transport method defined in <code>ajax.transport</code> to send requests to your API. By default, this transport method is <code>jQuery.ajax</code> but this can be changed.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  ajax: {
+    transport: function (params, success, failure) {
+      var request = new AjaxRequest(params.url, params);
+      request.on('success', success);
+      request.on('failure', failure);
+    }
+  }
+});
+</pre>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/data/array.html b/docs/_includes/options/data/array.html
new file mode 100644
index 00000000..b73ee095
--- /dev/null
+++ b/docs/_includes/options/data/array.html
@@ -0,0 +1,53 @@
+<section>
+  <h2 id="data">
+    Can I load data into Select2 using an array?
+  </h2>
+
+  <p>
+    Yes, but only when you are initially creating it.
+  </p>
+
+  <h3>
+    What properties are required on the objects passed in to the array?
+  </h3>
+
+  <p>
+    The <code>id</code> and <code>text</code> properties are required on each object, and these are the properties that Select2 uses for the internal data objects. Any additional paramters passed in with data objects will be included on the data objects that Select2 exposes.
+  </p>
+
+  <h3>
+    How should nested results be formatted?
+  </h3>
+
+  <h3>
+    How many levels of nesting are allowed?
+  </h3>
+
+  <p>
+    Because Select2 falls back to an <code>&lt;optgroup&gt;</code> when creating nested options, only a single level of nesting can be supported.
+  </p>
+
+  <h3>
+    Why are <code>&lt;option&gt;</code> tags being created?
+  </h3>
+
+  <p>
+    The <code>data</code> option is a shortcut that Select2 provides which allows you to load options into your <code>select</code> from a data array.
+  </p>
+
+  <h3>
+    My objects don&apos;t use <code>id</code> for their unique identifiers, what can I do?
+  </h3>
+
+  <p>
+    You can re-map your identifier before passing it to Select2.
+  </p>
+
+  <h3>
+    My objects use a property other than <code>text</code> for the text that needs to be displayed
+  </h3>
+
+  <p>
+    These can also be re-mapped.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/data/select.html b/docs/_includes/options/data/select.html
new file mode 100644
index 00000000..b915c921
--- /dev/null
+++ b/docs/_includes/options/data/select.html
@@ -0,0 +1,57 @@
+<section>
+  <h2 id="data-adapters-select-tag">
+    Can Select2 be used with a <code>&lt;select&gt;</code> tag?
+  </h2>
+
+  <h3>
+    Does Select2 support nesting options?
+  </h3>
+
+  <p>
+    Yes, just like in a standard <code>select</code>.
+  </p>
+
+  <h3>
+    How many levels of nesting can there be?
+  </h3>
+
+  <p>
+    Only a single level of nesting is allowed per the HTML specification.
+  </p>
+
+  <h3>
+    Can <code>&lt;optgroup&gt;</code> tags be made selectable?
+  </h3>
+
+  <p>
+    No. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
+  </p>
+
+  <h3>
+    How are <code>&lt;option&gt;</code> and <code>&lt;optgroup&gt;</code> tags serialized into data objects?
+  </h3>
+
+  <p>
+    Select2 will convert the <code>&lt;option&gt;</code> tag into a data object based on the following rules.
+  </p>
+
+<pre class="prettyprint linenums">
+{
+  "id": "value attribute" || "option text",
+  "text": "label attribute" || "option text",
+  "element": HTMLOptionElement
+}
+</pre>
+
+  <p>
+    And <code>&lt;optgroup&gt;</code> tags will be converted into data objects using the following rules
+  </p>
+
+<pre class="prettyprint linenums">
+{
+  "text": "label attribute",
+  "children": [ option data object, ... ],
+  "elment": HTMLOptGroupElement
+}
+</pre>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/dropdown.html b/docs/_includes/options/dropdown.html
index 87629077..b09fb6a3 100644
--- a/docs/_includes/options/dropdown.html
+++ b/docs/_includes/options/dropdown.html
@@ -1,308 +1,9 @@
 <section>
-  <div class="page-header">
-    <h1 id="dropdown">Dropdown</h1>
-  </div>
+  <h1 id="results">
+    Displaying results
+  </h1>
 
-  <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>
+  {% include options/dropdown/filtering.html %}
+  {% include options/dropdown/selections.html %}
+  {% include options/dropdown/placement.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/dropdown/filtering.html b/docs/_includes/options/dropdown/filtering.html
new file mode 100644
index 00000000..054ec19d
--- /dev/null
+++ b/docs/_includes/options/dropdown/filtering.html
@@ -0,0 +1,23 @@
+<section>
+  <h2>
+    Can I change when search results are loaded?
+  </h2>
+
+  <h3>
+    Can Select2 wait until the user has typed a search term before triggering the request?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    Select2 is allowing long search terms, can this be prevented?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    I only want the search box if there are enough results
+  </h3>
+
+  {% include options/not-written.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/dropdown/placement.html b/docs/_includes/options/dropdown/placement.html
new file mode 100644
index 00000000..67c986c7
--- /dev/null
+++ b/docs/_includes/options/dropdown/placement.html
@@ -0,0 +1,29 @@
+<section>
+  <h2>
+    Can I change how the dropdown is placed?
+  </h2>
+
+  <h3 id="dropdown-attachContainer">
+    Can the dropdown be placed directly after the selection container?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3 id="dropdownParent">
+    Can I pick an element for the dropdown to be appended to?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    I&apos;m using a Bootstrap modal and I can&apos;t use the search box
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    I&apos;m using jQuery UI and I can&apos;t use the search box
+  </h3>
+
+  {% include options/not-written.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/dropdown/selections.html b/docs/_includes/options/dropdown/selections.html
new file mode 100644
index 00000000..bcaf0370
--- /dev/null
+++ b/docs/_includes/options/dropdown/selections.html
@@ -0,0 +1,17 @@
+<section>
+  <h2>
+    Can I change how selecting results works?
+  </h2>
+
+  <h3>
+    Can I select the highlighted result when the dropdown is closed?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    Can I prevent the dropdown from closing when a result is selected?
+  </h3>
+
+  {% include options/not-written.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/events.html b/docs/_includes/options/events.html
index bf4f39a9..ea0dd2c1 100644
--- a/docs/_includes/options/events.html
+++ b/docs/_includes/options/events.html
@@ -1,50 +1,8 @@
 <section>
-  <div id="events" class="page-header">
-    <h1>Events</h1>
-  </div>
+  <h1>
+    Events
+  </h1>
 
-  <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>
+  {% include options/events/jquery.html %}
+  {% include options/events/internal.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/events/internal.html b/docs/_includes/options/events/internal.html
new file mode 100644
index 00000000..df49d5c9
--- /dev/null
+++ b/docs/_includes/options/events/internal.html
@@ -0,0 +1,9 @@
+<section>
+  <h2 id="events-internal">
+    Internal Select2 events
+  </h2>
+  
+  <p>
+    Select2 has an internal event system that works independently of the DOM event system. This internal event system is only accesssible from plugins and adapters that are connected to Select2.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/events/jquery.html b/docs/_includes/options/events/jquery.html
new file mode 100644
index 00000000..dd28c077
--- /dev/null
+++ b/docs/_includes/options/events/jquery.html
@@ -0,0 +1,29 @@
+<section>
+  <h2 id="events-public">
+    Public jQuery events
+  </h2>
+
+  <h3>
+    What events will Select2 trigger?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    How can I attach listeners for these events?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    What events does Select2 listen for?
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    What events can be prevented? How can I prevent a selection from being made?
+  </h3>
+
+  {% include options/not-written.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/introduction.html b/docs/_includes/options/introduction.html
new file mode 100644
index 00000000..7cc343fc
--- /dev/null
+++ b/docs/_includes/options/introduction.html
@@ -0,0 +1,9 @@
+<section>
+  <div class="alert alert-warning">
+    This page of the documentation is currently <strong>undergoing a rewrite and may be incomplete</strong>. If you do not find the answer you are looking for on this page, you may have better luck looking at <a href="options-old.html">the old options page</a>.
+  </div>
+
+  <p>
+    This documentation is set up in the form of a FAQ and covers the most common questions. If you do not find the answer to your question here, you may want to <a href="community.html">reach out to the community</a> to see if someone else can answer it.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/not-written.html b/docs/_includes/options/not-written.html
new file mode 100644
index 00000000..b4967088
--- /dev/null
+++ b/docs/_includes/options/not-written.html
@@ -0,0 +1,3 @@
+<div class="alert alert-info">
+  This answer to this question has not yet been written. You can <a href="https://github.com/select2/select2/blob/master/docs/README.md#how-can-i-fix-an-issue-in-these-docs">improve this documentation</a> by creating a pull request with an answer to this question.
+</div>
\ No newline at end of file
diff --git a/docs/_includes/options/selections.html b/docs/_includes/options/selections.html
new file mode 100644
index 00000000..086c2aec
--- /dev/null
+++ b/docs/_includes/options/selections.html
@@ -0,0 +1,10 @@
+<section>
+  <h1 id="selections">
+    Displaying selections
+  </h1>
+
+  {% include options/selections/multiple.html %}
+  {% include options/selections/placeholder.html %}
+  {% include options/selections/clearing-selections.html %}
+  {% include options/selections/templating.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/selections/clearing-selections.html b/docs/_includes/options/selections/clearing-selections.html
new file mode 100644
index 00000000..2e81614b
--- /dev/null
+++ b/docs/_includes/options/selections/clearing-selections.html
@@ -0,0 +1,17 @@
+<section>
+  <h2 id="allowClear">
+    Can I allow users to clear their selections?
+  </h2>
+
+  <h3>
+    The "x" icon is not clearing the selection
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    Can users remove all of their selections in a multiple select at once?
+  </h3>
+
+  {% include options/not-written.html %}
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/selections/multiple.html b/docs/_includes/options/selections/multiple.html
new file mode 100644
index 00000000..645a0b61
--- /dev/null
+++ b/docs/_includes/options/selections/multiple.html
@@ -0,0 +1,17 @@
+<section>
+  <h2 id="multiple">
+    Can I allow users to make multiple selections?
+  </h2>
+
+  <p>
+    Yes, Select2 supports making multiple selections through the use of the <code>multiple</code> option that can be passed in when initializing Select2.
+  </p>
+
+  <h3>
+    Can the <code>multiple</code> attribute be used on my <code>&lt;select&gt;</code> element?
+  </h3>
+
+  <p>
+    Yes, Select2 will automatically map the value of the <code>multiple</code> attribute to the <code>multiple</code> option during initialization.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/selections/placeholder.html b/docs/_includes/options/selections/placeholder.html
new file mode 100644
index 00000000..bcb08b5f
--- /dev/null
+++ b/docs/_includes/options/selections/placeholder.html
@@ -0,0 +1,53 @@
+<section>
+  <h2 id="placeholder">
+    How can I have Select2 display a placeholder?
+  </h2>
+
+  <p>
+    Select2 supports displaying a placeholder by default using the <code>placeholder</code> option. This can be either a data object matching the placeholder option, or a string to display as the placeholder if you are using a blank placeholder option.
+  </p>
+
+  <h3>
+    My first option is being displayed instead of my placeholder
+  </h3>
+
+  <p>
+    This usually means that you do not have a blank <code>&lt;option&gt;&lt/option&gt;</code> as the first option in your <code>&lt;select&gt;</code>.
+  </p>
+
+  <p>
+    Note that this does not apply to multiple selects, as the browser does not select the first option by default when multiple selections can be made.
+  </p>
+
+  <h3>
+    I am using AJAX, can I still show a placeholder?
+  </h3>
+
+  <p>
+    Yes, Select2 supports placeholders for all configurations. You will still need to add in the placeholder option if you are using a single select.
+  </p>
+
+  <h3>
+    Can I use an option without a blank value as my placeholder?
+  </h3>
+
+  <p>
+    The <code>placeholder</code> option allows you to pass in a data object instead of just a string if you need more flexibility. The <code>id</code> of the data object should match the <code>value</code> of the placeholder option.
+  </p>
+
+  <h3>
+    Can I change how the placeholder looks?
+  </h3>
+
+  <p>
+    The placeholder option should go through the standard templating methods, including <code>templateSelection</code>, so you can change how it is displayed.
+  </p>
+
+  <h3>
+    My placeholders aren&apos;t being displayed in Internet Explorer
+  </h3>
+
+  <p>
+    Select2 uses the native <code>placeholder</code> attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include Placeholders.js on your page, or use the full build, in order to add <code>placeholder</code> attribute support to input boxes.
+  </p>
+</section>
\ No newline at end of file
diff --git a/docs/_includes/options/selections/templating.html b/docs/_includes/options/selections/templating.html
new file mode 100644
index 00000000..7063561a
--- /dev/null
+++ b/docs/_includes/options/selections/templating.html
@@ -0,0 +1,23 @@
+<section>
+  <h2 id="templateSelection">
+    How can I customize the way selections are displayed?
+  </h2>
+
+  <h3>
+    Nothing is being displayed when I select an option
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    I am using HTML in my selection template but it isn't displaying it
+  </h3>
+
+  {% include options/not-written.html %}
+
+  <h3>
+    How can I access the container where the selection is displayed?
+  </h3>
+
+  {% include options/not-written.html %}
+</section>
\ No newline at end of file
diff --git a/docs/options-old.html b/docs/options-old.html
new file mode 100644
index 00000000..65690d18
--- /dev/null
+++ b/docs/options-old.html
@@ -0,0 +1,37 @@
+---
+layout: default
+title: Options - Select2
+slug: options
+---
+
+<section class="jumbotron">
+  <div class="container">
+    <h1>
+      Options
+    </h1>
+  </div>
+</section>
+
+<div class="container s2-docs-container">
+  <div class="row">
+    <div class="col-md-9" role="main">
+
+      {% include options-old/core-options.html %}
+      {% include options-old/dropdown.html %}
+      {% include options-old/events.html %}
+      {% include options-old/adapters.html %}
+      {% include options-old/setting-default-options.html %}
+      {% include options-old/backwards-compatibility.html %}
+
+    </div>
+    <div class="col-md-3" role="complementary">
+
+      {% include nav/options-old.html %}
+
+    </div>
+  </div>
+</div>
+
+<script type="text/javascript">
+  prettyPrint();
+</script>
diff --git a/docs/options.html b/docs/options.html
index e3c19cbd..5670c1cf 100644
--- a/docs/options.html
+++ b/docs/options.html
@@ -9,25 +9,25 @@ slug: options
     <h1>
       Options
     </h1>
+    <p class="lead">
+      Select2 supports a wide variety of options that allow you to customize it to your needs.
+    </p>
   </div>
 </section>
 
 <div class="container s2-docs-container">
   <div class="row">
     <div class="col-md-9" role="main">
-
-      {% include options/core-options.html %}
+      {% include options/introduction.html %}
+      {% include options/core.html %}
+      {% include options/data.html %}
+      {% include options/selections.html %}
       {% include options/dropdown.html %}
       {% include options/events.html %}
-      {% include options/adapters.html %}
-      {% include options/setting-default-options.html %}
-      {% include options/backwards-compatibility.html %}
-
+      {% include options/compatibility.html %}
     </div>
     <div class="col-md-3" role="complementary">
-
       {% include nav/options.html %}
-
     </div>
   </div>
 </div>