fix more links

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

@@ -43,12 +43,14 @@ should read over the list below.
 
 ## Using Select2 with AMD or CommonJS loaders
 
-Select2 should work with most AMD- or CommonJS-compliant module loaders, including <a href="http://requirejs.org/">RequireJS</a> and <a href="https://github.com/jrburke/almond">almond</a>. Select2 ships with a modified version of the <a href="https://github.com/umdjs/umd/blob/f208d385768ed30cd0025d5415997075345cd1c0/templates/jqueryPlugin.js">UMD jQuery template</a> that supports both CommonJS and AMD environments.
+Select2 should work with most AMD- or CommonJS-compliant module loaders, including [RequireJS](http://requirejs.org/) and [almond](https://github.com/jrburke/almond). Select2 ships with a modified version of the [UMD jQuery template](https://github.com/umdjs/umd/blob/f208d385768ed30cd0025d5415997075345cd1c0/templates/jqueryPlugin.js) that supports both CommonJS and AMD environments.
 
 ### Configuration
 
 For most AMD and CommonJS setups, the location of the data files used by Select2 will be automatically determined and handled without you needing to do anything.
 
+Select2 internally uses AMD and the r.js build tool to build the files located in the `dist` folder. These are built using the files in the `src` folder, so _you can_ just point your modules to the Select2 source and load in `jquery.select2` or `select2/core` when you want to use Select2. The files located in the `dist` folder are also AMD-compatible, so you can point to that file if you want to load in all of the default Select2 modules.
+
 If you are using Select2 in a build environment where preexisting module names are changed during a build step, Select2 may not be able to find optional dependencies or language files. You can manually set the prefixes to use for these files using the `amdBase` and `amdLanguageBase` options.
 
 ```
@@ -56,6 +58,12 @@ $.fn.select2.defaults.set('amdBase', 'select2/');
 $.fn.select2.defaults.set('amdLanguageBase', 'select2/i18n/');
 ```
 
-Select2 internally uses AMD and the r.js build tool to build the files located in the `dist` folder. These are built using the files in the `src` folder, so _you can_ just point your modules to the Select2 source and load in `jquery.select2` or `select2/core` when you want to use Select2. The files located in the `dist` folder are also AMD-compatible, so you can point to that file if you want to load in all of the default Select2 modules.
+#### `amdBase`
+
+Specifies the base AMD loader path to be used for select2 dependency resolution. This option typically doesn't need to be changed, but is available for situations where module names may change as a result of certain build environments.
+
+#### `amdLanguageBase` 
+
+Specifies the base AMD loader language path to be used for select2 language file resolution. This option typically doesn't need to be changed, but is available for situations where module names may change as a result of certain build environments.
 
 >>> Due to [a bug in older versions](https://github.com/jrburke/requirejs/issues/1342) of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery.  By upgrading to version 2.1.18 or higher of the r.js build tool, you will be able to fix the issue.

pages/02.configuration/01.options-api/docs.md

@@ -12,40 +12,40 @@ The following is an attempt to provide a comprehensive list of all configuration
 | `adaptDropdownCssClass` | | | |
 | `ajax` | object | `null` | Provides support for [ajax data sources](/data-sources/ajax). |
 | `allowClear` | boolean | `false` | Provides support for [clearable selections](/selections#clearable-selections). |
-| `amdBase` | string | `select2/` | The base AMD loader path to be used for select2 dependency resolution. This option typically doesn't need to be changed, but is available for situations where module names may change as a result of certain build environments. |
+| `amdBase` | string | `./` | See [Using Select2 with AMD or CommonJS loaders](/builds-and-modules#using-select2-with-amd-or-commonjs-loaders). |
-| `amdLanguageBase` | string | `select2/i18n/` | The base AMD loader language path to be used for select2 language file resolution. This option typically doesn't need to be changed, but is available for situations where module names may change as a result of certain build environments. |
+| `amdLanguageBase` | string | `./i18n/` | See [Using Select2 with AMD or CommonJS loaders](/builds-and-modules#using-select2-with-amd-or-commonjs-loaders). |
 | `closeOnSelect` | boolean | `true` | Controls whether the dropdown is [closed after a selection is made](/dropdown#forcing-the-dropdown-to-remain-open-after-selection). |
 | `containerCss` | | | |
-| `containerCssClass` | | | |
+| `containerCssClass` | string | `''` | |
-| `data` | array of objects | `null` | |
+| `data` | array of objects | `null` | Allows rendering dropdown options from an [array](/data-sources/arrays). |
 | `dataAdapter` | | `SelectAdapter` | Used to override the built-in [DataAdapter](/advanced/default-adapters/data). |
-| `debug` | boolean | | |
+| `debug` | boolean | `false` | Enable debugging messages in the browser console. |
 | `dir` | | |
 | `disabled` | boolean | `false` | When set to `true`, the select control will be disabled. |
 | `dropdownAdapter` | | `DropdownAdapter` | Used to override the built-in [DropdownAdapter](/advanced/default-adapters/dropdown) |
-| `dropdownAutoWidth` | boolean | | |
+| `dropdownAutoWidth` | boolean | `false` | |
-| `dropdownCss` | string | | |
+| `dropdownCss` | | | |
-| `dropdownCssClass` | string | | |
+| `dropdownCssClass` | string | `''` | |
-| `dropdownParent` | jQuery selector or DOM node | | Allows you to [customize placement](/dropdown#dropdown-placement) of the dropdown. |
+| `dropdownParent` | jQuery selector or DOM node | `$(document.body)` | Allows you to [customize placement](/dropdown#dropdown-placement) of the dropdown. |
-| `escapeMarkup` | | |
+| `escapeMarkup` | callback | `Utils.escapeMarkup` | Handles [automatic escaping of content rendered by custom templates](/dropdown#built-in-escaping). |
 | `initSelection` | callback | | See [`initSelection`](/upgrading/migrating-from-35#removed-the-requirement-of-initselection).  **This option was deprecated in Select2 v4.0, and will be removed in v4.1.** |
-| `language` | string or object | | |
+| `language` | string or object | `EnglishTranslation` | Specify the [language used for Select2 messages](/i18n#message-translations). |
-| `matcher` | A callback taking search `params` and the `data` object. | | |
+| `matcher` | A callback taking search `params` and the `data` object. | | Handles custom [search matching](/searching#customizing-how-results-are-matched). |
 | `maximumInputLength` | integer | `0` | [Maximum number of characters](/searching#maximum-search-term-length) that may be provided for a search term. |
 | `maximumSelectionLength` | integer | `0` | The maximum number of items that may be selected in a multi-select control. If the value of this option is less than 1, the number of selected items will not be limited.
 | `minimumInputLength` | integer | `0` | [Minimum number of characters required to start a search.](/searching#minimum-search-term-length) |
 | `minimumResultsForSearch` | integer | `0` | The minimum number of results required to [display the search box](/searching#limiting-display-of-the-search-box-to-large-result-sets). |
 | `multiple` | boolean | `false` | This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization. |
-| `placeholder` | string or object | | |
+| `placeholder` | string or object | `null` | Specifies the [placeholder](/placeholders) for the control. |
-| `query` | A function taking `params` (including a `callback`) | | **This option was deprecated in Select2 v4.0, and will be removed in v4.1.** |
+| `query` | A function taking `params` (including a `callback`) | `Query` | **This option was deprecated in Select2 v4.0, and will be removed in v4.1.** |
 | `resultsAdapter` | | `ResultsAdapter` | Used to override the built-in [ResultsAdapter](/advanced/default-adapters/results). |
 | `selectionAdapter` | | `SingleSelection` or `MultipleSelection`, depending on the value of `multiple`. | Used to override the built-in [SelectionAdapter](/advanced/default-adapters/selection). |
 | `selectOnClose` | boolean | `false` | Implements [automatic selection](/dropdown#automatic-selection) when the dropdown is closed. |
-| `sorter` | function | | |
+| `sorter` | callback | | |
 | `tags` | boolean / array of objects | `false` | Used to enable [free text responses](/tagging). |
-| `templateResult` | callback | | |
+| `templateResult` | callback | | Customizes the way that [search results are rendered](/dropdown#templating). |
-| `templateSelection` | callback | | |
+| `templateSelection` | callback | | Customizes the way that [selections are rendered](/selections#templating). |
 | `theme` | string | `default` | Allows you to set the [theme](/appearance#themes). |
-| `tokenizer` | | |
+| `tokenizer` | callback | | A callback that handles [automatic tokenization of free-text entry](/tagging#automatic-tokenization-into-tags). |
-| `tokenSeparators` | | | |
+| `tokenSeparators` | array | `[]` | The list of characters that should be used as token separators. |
 | `width` | string | `resolve` | Supports [customization of the container width](/appearance#container-width). |

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

@@ -4,7 +4,7 @@ taxonomy:
     category: docs
 ---
 
-In some cases, you need to set the default options for all instances of Select2 in your web application. This is especially useful when you are migrating from past versions of Select2, or you are using non-standard options <a href="#amd">like custom AMD builds</a>. Select2 exposes the default options through <code>$.fn.select2.defaults</code>, which allows you to set them globally.
+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 like [custom AMD builds](/getting-started/builds-and-modules#using-select2-with-amd-or-commonjs-loaders). Select2 exposes the default options through `$.fn.select2.defaults`, which allows you to set them globally.
 
 When setting options globally, any past defaults that have been set will be overridden. Default options are only used when an option is requested that has not been set during initialization.
 
@@ -16,7 +16,7 @@ $.fn.select2.defaults.set("theme", "classic");
 
 ## Nested options
 
-To set a default values for cache, use the same notation used for <a href="#data-attributes">HTML <code>data-*</code> attributes</a>.  Two dashes (`--`) will be replaced by a level of nesting, and a single dash (`-`) will convert the key to a camelCase string:
+To set a default values for cache, use the same notation used for [HTML `data-*` attributes](/configuration/data-attributes).  Two dashes (`--`) will be replaced by a level of nesting, and a single dash (`-`) will convert the key to a camelCase string:
 
 ```
 $.fn.select2.defaults.set("ajax--cache", false);

pages/02.configuration/03.data-attributes/docs.md

@@ -35,15 +35,16 @@ To write these options as `data-*` attributes, each level of nesting should be s
 </select>
 ```
 
-The value of the option is subject to jQuery's <a href="https://api.jquery.com/data/#data-html5">parsing rules</a> for HTML5 data attributes.
+The value of the option is subject to jQuery's [parsing rules](https://api.jquery.com/data/#data-html5) for HTML5 data attributes.
 
->>> Due to <a href="https://github.com/jquery/jquery/issues/2070">a jQuery bug</a>, nested options using <code>data-*</code> attributes <a href="https://github.com/select2/select2/issues/2969">do not work in jQuery 1.x</a>.
+>>> Due to [a jQuery bug](https://github.com/jquery/jquery/issues/2070), nested options using `data-*` attributes [do not work in jQuery 1.x](https://github.com/select2/select2/issues/2969).
 
 ## `camelCase` options
 
-HTML data attributes are case-insensitive, so any options which contain capital letters will be parsed as if they were all lowercase. Because Select2 has many options which are camelCase, where words are separated by uppercase letters, you must write these options out with dashes instead. So an option that would normally be called <code>allowClear</code> should instead be defined as `allow-clear`.
+HTML data attributes are case-insensitive, so any options which contain capital letters will be parsed as if they were all lowercase. Because Select2 has many options which are camelCase, where words are separated by uppercase letters, you must write these options out with dashes instead. So an option that would normally be called `allowClear` should instead be defined as `allow-clear`.
+
+This means that declaring your `<select>` tag as...
 
-This means that if you declare your <code>&lt;select&gt;</code> tag as...
 ```
 <select data-tags="true" data-placeholder="Select an option" data-allow-clear="true">
     ...

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

@@ -21,7 +21,7 @@ When using Select2 with remote data, the HTML required for the `select` is the s
 </select>
 ```
 
-You can configure how Select2 searches for remote data using the `ajax` option. More information on the individual options that Select2 handles can be found in the [options documentation for `ajax`](/configuration).
+You can configure how Select2 searches for remote data using the `ajax` option:
 
 <pre data-fill-from=".js-code-placeholder"></pre>
 
@@ -105,7 +105,7 @@ $('select').select2({
 
 ## Transforming response data
 
-You can use the <code>ajax.processResults</code> option to transform the data returned by your API into the format expected by Select2:
+You can use the `ajax.processResults` option to transform the data returned by your API into the format expected by Select2:
 
 ```
 $('select').select2({

pages/08.tagging/docs.md

@@ -1,5 +1,5 @@
 ---
-title: Free-text entry
+title: Dynamic option creation
 taxonomy:
     category: docs
 process:
@@ -7,7 +7,7 @@ process:
 never_cache_twig: true
 ---
 
-In addition to a prepopulated menu of options, Select2 can also allow free-text responses.  This feature is called "tagging".  To enable free-text responses, set the <code>tags</code> option to `true`:
+In addition to a prepopulated menu of options, Select2 can dynamically create new options from text input by the user in the search box.  This feature is called "tagging".  To enable tagging, set the `tags` option to `true`:
 
 <div class="s2-example">
   <p>
@@ -35,7 +35,7 @@ Note that when tagging is enabled the user can select from the pre-existing opti
 
 ## Tagging with multi-value select boxes
 
-Tagging can also be used in multi-value select boxes. In the example below, we set the <code>multiple="multiple"</code> attribute on a Select2 control that also has <code>tags: true</code> enabled:
+Tagging can also be used in multi-value select boxes. In the example below, we set the `multiple="multiple"` attribute on a Select2 control that also has `tags: true` enabled:
   
 <div class="s2-example">
   <p>

pages/09.placeholders/docs.md

@@ -39,7 +39,7 @@ The most common situation is to use a string of text as your placeholder value.
     });
 </script>
 
->>> Select2 uses the `placeholder` attribute on multiple select boxes, which requires IE 10+. You can support it in older versions with <a href="https://github.com/jamesallardice/Placeholders.js">the Placeholders.js polyfill</a>.
+>>> Select2 uses the `placeholder` attribute on multiple select boxes, which requires IE 10+. You can support it in older versions with [the Placeholders.js polyfill](https://github.com/jamesallardice/Placeholders.js).
 
 ## Default selection placeholders
 

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

@@ -150,15 +150,32 @@ $('select').val(null).trigger('change');
 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-set-val").on("click", function () {
+    $example.val("CA").trigger("change");
+});
 
-$(".js-programmatic-open").on("click", function () { $example.select2("open"); });
+$(".js-programmatic-open").on("click", function () {
-$(".js-programmatic-close").on("click", function () { $example.select2("close"); });
+    $example.select2("open");
+});
 
-$(".js-programmatic-init").on("click", function () { $example.select2(); });
+$(".js-programmatic-close").on("click", function () {
-$(".js-programmatic-destroy").on("click", function () { $example.select2("destroy"); });
+    $example.select2("close");
+});
 
-$(".js-programmatic-multi-set-val").on("click", function () { $exampleMulti.val(["CA", "AL"]).trigger("change"); });
+$(".js-programmatic-init").on("click", function () {
-$(".js-programmatic-multi-clear").on("click", function () { $exampleMulti.val(null).trigger("change"); });
+    $example.select2();
+});
+
+$(".js-programmatic-destroy").on("click", function () {
+    $example.select2("destroy");
+});
+
+$(".js-programmatic-multi-set-val").on("click", function () {
+    $exampleMulti.val(["CA", "AL"]).trigger("change");
+});
+
+$(".js-programmatic-multi-clear").on("click", function () {
+    $exampleMulti.val(null).trigger("change");
+});
 
 </script>

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

@@ -94,4 +94,4 @@ function log (name, evt) {
 
 ## Internal Select2 events
 
-Select2 has an internal event system that works independently of the DOM event system. This internal event system is only accessible from plugins and adapters that are connected to Select2.
+Select2 has an [internal event system](/advanced/default-adapters/selection#eventrelay) that works independently of the DOM event system. This internal event system is only accessible from plugins and adapters that are connected to Select2.

pages/13.advanced/02.default-adapters/02.array/docs.md

@@ -4,7 +4,7 @@ taxonomy:
     category: docs
 ---
 
-The `ArrayAdapter` implements support for creating results based on an [array of data objects](/data-sources/array).
+The `ArrayAdapter` implements support for creating results based on an [array of data objects](/data-sources/arrays).
 
 **AMD Modules:**