DOC-2711: Documentation Enhancements for bundling-icons, and creating-an-icon-pack.

modules/ROOT/examples/live-demos/custom-icon-pack/index.html

@@ -0,0 +1,38 @@
+<div style="display: flex; gap: 20px; width: 100%; flex-wrap: wrap;">
+  <div style="flex: 1; min-width: 300px;">
+    <h2>Default TinyMCE Icons</h2>
+    <textarea id="default-editor" style="width: 100%;">
+      <h2>Default Icons Editor</h2>
+      <p>This editor uses the <strong>default TinyMCE icons</strong>.</p>
+      <p>Notice the standard appearance of the toolbar buttons.</p>
+      <ul>
+        <li>Bold, italic, underline buttons</li>
+        <li>Link and image buttons</li>
+        <li>List and code buttons</li>
+      </ul>
+    </textarea>
+  </div>
+  <div style="flex: 1; min-width: 300px;">
+    <h2>Custom Icon Pack</h2>
+    <textarea id="custom-editor" style="width: 100%;">
+      <h2>Custom Icons Editor</h2>
+      <p>This editor uses a <strong>custom icon pack</strong> created with our icon pack system.</p>
+
+      <h3>How It Works:</h3>
+      <p><strong>Demo Setup:</strong> For this live demo, the custom icons are defined using <code>tinymce.IconManager.add()</code> directly in the JavaScript file.</p>
+
+      <p><strong>Production Setup:</strong> In normal usage, you would:</p>
+      <ul>
+        <li>Build your icon pack using the template (see our guide)</li>
+        <li>Place the generated <code>icons.js</code> file in <code>dist/icons/your-pack-name/</code></li>
+        <li>Use <code>icons_url: 'path/to/icons.js'</code> to load it</li>
+      </ul>
+
+      <p>The editor is configured with <code>icons: 'my-icon-pack'</code> to use the custom icons. <strong>Try the custom buttons:</strong> Look for the custom bold, italic, and audio buttons in the toolbar above.</p>
+    </textarea>
+  </div>
+</div>
+
+<div style="margin-top: 20px; padding: 15px; background: #f8f9fa; border-radius: 4px; font-size: 14px; color: #666;">
+  <strong>Icon Credits:</strong> Custom icons in this demo are sourced from <a href="https://freesvgicons.com/" target="_blank" rel="noopener">FreeSVGIcons.com</a> - a collection of 250k+ open-source SVG icons.
+</div>

modules/ROOT/examples/live-demos/custom-icon-pack/index.js

@@ -0,0 +1,47 @@
+// Load custom icon pack inline (for live demo compatibility)
+tinymce.IconManager.add('my-icon-pack', {
+  icons: {
+      'audio': '<svg width="24" height="24"><path d="M10.8 19q.9 0 1.5-.7t.7-1.5V13h3v-2h-4v3.9l-.6-.3-.6-.1q-1 0-1.7.7t-.6 1.6q0 .9.7 1.5t1.6.7ZM6 22q-.8 0-1.4-.6T4 20V4q0-.8.6-1.4T6 2h8l6 6v12q0 .8-.6 1.4T18 22H6Zm7-13h5l-5-5v5Z"/></svg>',
+      'bold': '<svg width="24" height="24"><path fill-rule="evenodd" d="M3.6 2.3a1.4 1.4 0 0 0-1.4 1.3v16.8c0 .7.7 1.4 1.4 1.4h16.8a1.4 1.4 0 0 0 1.4-1.4V3.6a1.4 1.4 0 0 0-1.4-1.3H3.6Zm6 4a1.4 1.4 0 0 0-1.3 1.3v9.3c0 .7.6 1.4 1.3 1.4H12v-.8.8a2.5 2.5 0 0 0 .2 0 4.6 4.6 0 0 0 1.6-.5c.5-.2 1-.5 1.3-1 .4-.5.7-1.2.7-2 0-.9-.3-1.6-.7-2a3.2 3.2 0 0 0-.8-.9 2.8 2.8 0 0 0 .4-.5c.4-.5.5-1.1.5-1.9s-.1-1.4-.5-1.9a3 3 0 0 0-1.1-1 3.9 3.9 0 0 0-1.6-.3H9.6Zm.1 6.5H12a3.2 3.2 0 0 1 1.2.2l.7.6c.2.2.4.6.4 1.1s-.2 1-.4 1.2a1.8 1.8 0 0 1-.7.6 3.2 3.2 0 0 1-1.1.2H9.7v-4Zm2.3 4Zm0-5.6H9.7V7.8H12l1 .2.5.5c.1.2.3.5.3 1s-.2.8-.3 1a1.4 1.4 0 0 1-.6.5 2.3 2.3 0 0 1-.9.2Z" clip-rule="evenodd"/></svg>',
+      'italic': '<svg width="24" height="24"><path fill-rule="evenodd" d="M3.6 2.3a1.4 1.4 0 0 0-1.4 1.3v16.8c0 .7.7 1.4 1.4 1.4h16.8a1.4 1.4 0 0 0 1.4-1.4V3.6a1.4 1.4 0 0 0-1.4-1.3H3.6ZM16 6.8h-1.5L11 17.1h1a.8.8 0 0 1 0 1.6H8a.8.8 0 0 1 0-1.6h1.5L13 6.8h-1a.8.8 0 0 1 0-1.5h4a.8.8 0 0 1 0 1.5Z" clip-rule="evenodd"/></svg>',
+  }
+});
+
+// Default Icons Editor
+tinymce.init({
+selector: '#default-editor',
+icons: 'material', // use material icon pack
+plugins: 'lists link image code',
+toolbar: 'undo redo | bold italic underline | bullist numlist | link image code',
+height: 500,
+// license_key: 'gpl'
+});
+
+// Custom Icons Editor
+tinymce.init({
+selector: '#custom-editor',
+icons: 'my-icon-pack',
+plugins: 'lists link image code',
+toolbar: 'undo redo | myButton1 myButton2 myButton3 | bullist numlist | link image code',
+height: 500,
+setup: (editor) => {
+  editor.ui.registry.addButton('myButton1', {
+    icon: 'bold',    // the 'bold' icon created from 'bold.svg'
+    onAction: (_) => {
+      editor.insertContent('&nbsp;<strong>It\'s my custom bold icon button!</strong>&nbsp;');
+    }
+  });
+  editor.ui.registry.addButton('myButton2', {
+    icon: 'italic',    // the 'italic' icon created from 'italic.svg'
+    onAction: (_) => {
+      editor.insertContent('&nbsp;<strong>It\'s my custom italic icon button!</strong>&nbsp;');
+    }
+  });
+  editor.ui.registry.addButton('myButton3', {
+    icon: 'audio',    // the 'audio' icon created from 'audio.svg'
+    onAction: (_) => {
+      editor.insertContent('&nbsp;<strong>It\'s my custom audio icon button!</strong>&nbsp;');
+    }
+  });
+}
+});

modules/ROOT/pages/bundling-icons.adoc

@@ -3,51 +3,87 @@
 :description_short: Information on bundling icon packs
 :description: Information on bundling TinyMCE icon packs using module loading
 
+== Overview
+
+Icon packs provide visual styling for {productname}'s toolbar buttons, menu items, and contextual toolbars. When bundling {productname} with a module loader, icon packs can be included to customize the editor's appearance.
+
+{productname} includes both community and premium icon packs:
+
+* **Community icon packs**: Available with all {productname} installations
+* **Premium icon packs**: Available with paid {productname} subscriptions
+
+The default icon pack is always required and provides the base set of icons. Additional icon packs can be bundled to extend or replace the default icons.
+
 :editorcomponent: icon pack
 include::partial$module-loading/bundling-ref-example.adoc[]
 :!editorcomponent:
 
-The following table shows examples of the syntax used to bundle the following icon pack:
+== Bundling syntax examples
 
-....
-./icons/example/icons.js
-....
-
-Example syntax for including the example icon pack in a bundle:
+The following examples show how to bundle icon packs using different module syntaxes. The examples use the `material` icon pack, but the same syntax applies to all available icon packs.
 
 [cols='1,1,4']
-|===
+|====
 |Module Syntax |Source |Example
 
 .2+|ES6+
 |npm
 a|
 [source, js]
 ----
-import 'tinymce/icons/example';
+import 'tinymce/icons/material';
 ----
 
 |`.zip`
 a|
 [source, js]
 ----
-import '../tinymce/icons/example/icons';
+import '../tinymce/icons/material/icons';
 ----
 
 .2+|Common JS
 |npm
 a|
 [source, js]
 ----
-require('tinymce/icons/example');
+require('tinymce/icons/material');
 ----
 
 |`.zip`
 a|
 [source, js]
 ----
-require('../tinymce/icons/example/icons.js');
+require('../tinymce/icons/material/icons.js');
 ----
-|===
+|====
+
+== Available icon packs
 
 include::partial$module-loading/bundling-icon-files.adoc[]
+
+== Usage in editor configuration
+
+After bundling an icon pack, configure the editor to use it by setting the `icons` option:
+
+[source, js]
+----
+tinymce.init({
+  selector: 'textarea',
+  icons: 'material',  // Use the bundled material icon pack
+  plugins: [
+    "advlist", "anchor", "autolink", "charmap", "code", "fullscreen",
+    "help", "image", "insertdatetime", "link", "lists", "media",
+    "preview", "searchreplace", "table", "visualblocks",
+  ],
+  toolbar: "undo redo | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image",
+});
+----
+
+== Troubleshooting
+
+**Icons not displaying**: Ensure the icon pack is properly bundled and the `icons` option matches the bundled pack name.
+
+**Missing icons**: The default icon pack is always required. Additional icon packs extend or replace default icons but do not provide all necessary icons on their own.
+
+**Build errors**: Verify that the icon pack path is correct and the pack exists in your {productname} installation.
+