DOC-3329: Re-feactor editor-skin, editor-icon and all related partials for better flow, and add references to NPM.

Author: kemister85

modules/ROOT/pages/bundling-icons.adoc

@@ -26,7 +26,7 @@ The following examples show how to bundle icon packs using different module synt
 |====
 |Module Syntax |Source |Example
 
-.2+|ES6+
+.3+|ES6+
 |npm (community)
 a|
 [source, js]
@@ -48,7 +48,7 @@ a|
 import '../tinymce/icons/material/icons';
 ----
 
-.2+|Common JS
+.3+|Common JS
 |npm (community)
 a|
 [source, js]

modules/ROOT/pages/bundling-plugins.adoc

@@ -141,8 +141,9 @@ tinymce.init({
   license_key: 'T8LK:...', // Your commercial license key
   external_plugins: {
     'advcode': '<path_to_premium_plugins>/advcode/plugin.min.js',
-    'licensekeymanager': '<path_to_premium_plugins>/licensekeymanager/plugin.min.js',
-    'tinycomments': '<path_to_premium_plugins>/tinycomments/plugin.min.js'
+    'tinycomments': '<path_to_premium_plugins>/tinycomments/plugin.min.js',
+    // Always include the licensekeymanager plugin when using premium plugins with a commercial license.
+    'licensekeymanager': '<path_to_premium_plugins>/licensekeymanager/plugin.min.js'
   },
   plugins: 'advcode tinycomments',
   // ... other configuration

modules/ROOT/pages/editor-icons.adoc

@@ -2,6 +2,37 @@
 :navtitle: Icons
 :description: Configure the editor's toolbar button and menu item icons.
 
+{productname} icons come from icon packs. {productname} includes both community and premium icon packs, but also allows integrators to add custom icons or override {productname} icons with their own.
+
+The default icon pack is shipped with {productname} and does not require any configuration, though it must be imported when bundling for deployment:
+
+[source,js]
+----
+import 'tinymce/icons/default';
+----
+
+Replacing the default icon can be done using the `+icons+` and `+icons_url+` settings.
+
+== Available icon packs
+
+{productname} includes both community and premium icon packs:
+
+* **Community**: `default` (always required)
+* **Premium**: `bootstrap`, `jam`, `material`, `small`, `thin` (available with paid subscriptions)
+
+For information on which icon packs work best with which skins, see: xref:enhanced-skins-and-icon-packs.adoc#icon-pack-compatibility-matrix[Icon pack compatibility matrix].
+
+== Custom icon packs
+
+For information on creating custom icon packs, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].
+
+The value passed to `+icons+` must match the pack name defined either:
+
+* Passed to `+tinymce.IconManager.add+` when registering the icon pack via JavaScript; or
+* Specified in the `+package.json+` `+iconPackName+` field when creating the icon pack using the xref:creating-an-icon-pack.adoc#download-and-setup-the-icon-pack-template[Icon Pack Template].
+
+== Replacing the default icon pack
+
 include::partial$misc/icons-or-icons_url.adoc[]
 
 include::partial$configuration/icons.adoc[]

modules/ROOT/pages/editor-skin.adoc

@@ -2,6 +2,34 @@
 :navtitle: Skins
 :description: Configure the editor's overall appearance.
 
+{productname} comes with several premium skins which change the look of the editor. These skins are an easy way to restyle {productname} to better suit applications.
+
+[NOTE]
+====
+*Skins vs Content CSS:*
+
+Skins change both the look of {productname}'s UI and the editable area. To change only the look of the editable area, use xref:add-css-options.adoc#content_css[`+content_css+`].
+====
+
+The default skin does not require any configuration, though it must be imported when bundling for deployment:
+
+[source,js]
+----
+import 'tinymce/skins/ui/oxide/skin';
+----
+
+Replacing the default skin uses the `+skin+` and `+skin_url+` settings.
+
+== Available skins
+
+See xref:enhanced-skins-and-icon-packs.adoc[Enhanced Skins & Icon Packs] for a list of available skins and the icon packs which look best with each skin.
+
+== Custom skins
+
+Integrators can create and use their own skin files. For information on creating custom skins, see: xref:creating-a-skin.adoc[Create a skin for {productname}].
+
+== Replacing the default skin
+
 include::partial$misc/skin-or-skin_url.adoc[]
 
 include::partial$configuration/skin.adoc[]

modules/ROOT/pages/license-key.adoc

@@ -223,7 +223,7 @@ To obtain a new {productname} 8 license key (T8LK-prefixed):
 Existing {productname} 7 license keys cannot be modified to work with {productname} 8 by adding the T8LK prefix. A new {productname} 8 license must be obtained through the proper channels listed above.
 ====
 
-=== If im upgrading from TinyMCE 7 how do I get a TinyMCE 8 license key?
+=== When upgrading from {productname} 7, what is the process for obtaining a {productname} 8 license key?
 
 If you are using {cloudname} (cloud-hosted):
 

modules/ROOT/partials/configuration/icons.adoc

@@ -3,45 +3,13 @@ ifeval::[{customIconPack} != true]
 [[icons]]
 == `+icons+`
 
-The *icons* option allows the editor icons to be extended or replaced using an icon pack. For information on creating icon packs, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].
+The *icons* option allows the editor icons to be extended or replaced using an icon pack. The icon pack is specified by name.
 
 *Type:* `+String+`
 endif::[]
 
 On initialization, {productname} will try to load any icon pack specified by the *icons* option. The icons in the icon pack will be merged with xref:editor-icon-identifiers.adoc[{productname}'s default icons] and icons in the icon pack will overwrite the default icons with the same identifier.
 
-{productname} loads icon packs from the path `+TINYMCE_BASE/icons/${iconPackName}/icons.js+`; where:
-
-* `+TINYMCE_BASE+` is the {productname} root directory (the directory containing `+tinymce.min.js+`).
-* `+${iconPackName}+` is the name of the icon pack.
-
-== Available icon packs
-
-{productname} includes both community and premium icon packs:
-
-* **Community**: `default` (always required)
-* **Premium**: `bootstrap`, `jam`, `material`, `small`, `thin` (available with paid subscriptions)
-
-For information on creating custom icon packs, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].
-
-== Usage
-
-To use a {productname} icon pack:
-
-. If required, create a new `+icons+` directory in `+TINYMCE_BASE+`.
-. Copy the icon pack into the `+icons+` directory.
-ifeval::[{customIconPack} == true]
-For example:
-+
-[source,sh]
-----
-$ cp -r  dist/icons/my_icon_pack  TINYMCE_BASE/icons/
-----
-
-endif::[]
-
-. Add the `+icons+` option to `+tinymce.init+`.
-
 ifeval::[{customIconPack} == true]
 For custom icon packs:
 
@@ -56,7 +24,7 @@ tinymce.init({
 endif::[]
 ifeval::[{customIconPack} != true]
 
-=== Example: using premium icon packs
+=== Example: using a premium icon pack
 
 [source,js]
 ----
@@ -72,7 +40,7 @@ tinymce.init({
 });
 ----
 
-=== Example: using multiple icon packs
+=== Example: using icon packs with matching skins and content styling
 
 [source,js]
 ----

modules/ROOT/partials/configuration/icons_url.adoc

@@ -3,12 +3,12 @@ ifeval::[{customIconPack} != true]
 [[icons_url]]
 == `+icons_url+`
 
-The *icons_url* option allows the editor icons to be extended or replaced using an icon pack. For information on creating icon packs, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].
-endif::[]
+The *icons_url* option allows integrators to specify a non-default location to load icon packs from. This is useful when {productname} and the icon pack are loaded from different locations. For example: When loading {productname} from {cloudname}, the icon pack can be loaded from a different web server.
 
-On initialization, {productname} will try to load any icon pack specified by the *icons_url* option. The icons in the icon pack will be merged with xref:editor-icon-identifiers.adoc[{productname}'s default icons] and icons in the icon pack will overwrite the default icons with the same identifier.
+*Type:* `+String+`
+endif::[]
 
-`+icons_url+` is used to specify the location of an icon pack when {productname} and the icon pack are loaded from different locations. For example: When loading {productname} from {cloudname}, the icon pack can be loaded from a different web server.
+On initialization, {productname} will try to load any icon pack specified by the *icons* option from the location specified by *icons_url*. The icons in the icon pack will be merged with xref:editor-icon-identifiers.adoc[{productname}'s default icons] and icons in the icon pack will overwrite the default icons with the same identifier.
 
 [IMPORTANT]
 ====
@@ -30,7 +30,6 @@ tinymce.init({
 });
 ----
 
-The `icons` value must match the pack name defined in your `package.json` `iconPackName` field.
 ====
 
 == Usage
@@ -39,6 +38,7 @@ To use a {productname} icon pack from a separate location:
 
 . Ensure the icon pack is available at the specified URL.
 . Add the `+icons_url+` option to `+tinymce.init+`.
+. Specify the icon pack name using the `+icons+` setting.
 
 ifeval::[{customIconPack} == true]
 For custom icon packs:
@@ -92,7 +92,6 @@ tinymce.init({
 
 endif::[]
 ifeval::[{customIconPack} != true]
-*Type:* `+String+`
 
 === Example: using `+icons_url+`
 
@@ -113,13 +112,13 @@ tinymce.init({
 
 === Example: loading premium icons from `+tinymce-premium+` (NPM)
 
-When installing the `+tinymce-premium+` NPM package, premium icon packs are stored in `+node_modules/tinymce-premium/icons/+`. Configure `+icons_url+` to point at the desired icon pack file. For example:
+When installing the `+tinymce-premium+` NPM package, premium icon packs are stored in `+node_modules/tinymce-premium/icons/+`. Configure `+icons_url+` to point at the desired icon pack file. The path is relative to where {productname} is loaded from. For example:
 
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',
-  icons_url: '/node_modules/tinymce-premium/icons/material/icons.js',
+  icons_url: '../../node_modules/tinymce-premium/icons/material/icons.js',
   icons: 'material'
 });
 ----

modules/ROOT/partials/configuration/skin.adoc

@@ -1,22 +1,22 @@
 [[skin]]
 == `+skin+`
 
-This option allows you to specify the skin that {productname} should use, or `+false+` to not load a skin. The default skin included with {productname} is named "oxide".
+This option specifies the skin that {productname} should use, or `+false+` to not load a skin. The default skin included with {productname} is named "oxide".
 
 *Type:* `+String+` or `+Boolean+`
 
 *Default value:* `+'oxide'+`
 
 *Possible values:* the name of a skin or `+false+`
 
-The name of the skin should match the name of the folder within the skins directory of {productname}. If the specified skin is not found, {productname} will not load.
+The name of the skin should match the name of the folder within the `+skins/ui+` directory of {productname}. If the specified skin is not found, {productname} will not load.
 
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your HTML
-  skin: 'oxide'
+  selector: 'textarea',  // change this value according to the HTML
+  skin: 'fabric'
 });
 ----
 
-If you would like to create your own skin, please see the guide xref:creating-a-skin.adoc[here].
+For information on creating custom skins, see: xref:creating-a-skin.adoc[Create a skin for {productname}].

modules/ROOT/partials/configuration/skin_url.adoc

@@ -1,30 +1,31 @@
 [[skin_url]]
 == `+skin_url+`
 
-If you are using {productname} skins, this option enables you to specify the location of the skin directory. This is useful if you are loading {productname} from one URL, for example a CDN, while loading a skin on, say, a local server.
+This option specifies the location of the skin directory. This is useful when loading {productname} and the skin files from different locations.
+
+When using `+skin_url+`, the `+skin+` option is not required. The `+skin_url+` option points directly to the skin directory location.
 
 *Type:* `+String+`
 
 === Example: using `+skin_url+`
 
-[source,js,subs="attributes+"]
+[source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your HTML
-  skin_url: '/css/my{prodnamecode}skin'
+  selector: 'textarea',  // change this value according to the HTML
+  skin_url: '/css/mytinymceskin' // change this to point to the folder of skin files
 });
 ----
 
 === Example: loading premium skins from `+tinymce-premium+` (NPM)
 
-When installing the `+tinymce-premium+` NPM package, premium skins are stored in `+node_modules/tinymce-premium/skins/+`. Configure `+skin_url+` to point at the desired skin directory. For example:
+When installing the `+tinymce-premium+` NPM package, premium skins are stored in `+node_modules/tinymce-premium/skins/ui/+`. Configure the `+skin_url+` to point at the desired skin directory. For example:
 
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',
-  skin_url: '/node_modules/tinymce-premium/skins/ui/oxide',
-  skin: 'oxide'
+  skin_url: '/node_modules/tinymce-premium/skins/ui/fabric'
 });
 ----
 

modules/ROOT/partials/misc/icons-or-icons_url.adoc

@@ -1,4 +1,14 @@
-There are two options for replacing the icons in {productname}: `+icons+` and `+icons_url+`. 
+There are two options related to replacing the icons in {productname}: `+icons+` and `+icons_url+`.
 
-* Use the `+icons+` option when icon packs are in the default location (for {cloudname} deployments, ZIP bundles, or when using NPM packages with bundling or file layering).
-* Use the `+icons_url+` option to specify a custom path to icon packs, which is useful for custom icon packs or when using NPM packages without bundling.
+* `+icons+` specifies *which* icon pack to use.
+* `+icons_url+` specifies *where* to find that icon pack if it is not in the **default location**.
+
+If only `+icons+` is configured, {productname} will try to load the specified icon pack from `+TINYMCE_BASE/icons/${iconPackName}/icons.js+`; where:
+
+* `+TINYMCE_BASE+` is the {productname} root directory (the directory containing `+tinymce.min.js+`).
+* `+${iconPackName}+` is the name of the icon pack.
+
+To load icon packs from another location, integrators must specify that location using `+icons_url+`.
+
+* When using {productname} from {cloudname}, ZIP bundles, or NPM packages with bundling or file layering, only `+icons+` should be required.
+* When using custom icon packs or using NPM packages without bundling, `+icons_url+` will likely also be required.