Merge branch 'release/8.0.0' into feature/8.0.0/DOC-3147

Author: kemister85

CONTRIBUTING.md

@@ -1,119 +1,101 @@
-# TinyMCE documentation
+# TinyMCE Documentation
 
-This project maintains the documentation for TinyMCE at
-[https://www.tiny.cloud/docs](https://www.tiny.cloud/docs). If you have any
-modifications you wish to contribute, fork this project, make the changes
-and submit a pull request. You will need to sign the contributor’s license
-agreement, which will be emailed to you upon creating the pull request.
+This project maintains the official documentation for TinyMCE, available at [https://www.tiny.cloud/docs](https://www.tiny.cloud/docs). If you have modifications or improvements to contribute, fork this repository, make the necessary changes, and submit a pull request (PR). A contributor's license agreement (CLA) must be signed before your contribution can be merged. This agreement will be sent via email when you create a PR.
 
-This project is built using [Antora](https://antora.org/).
+This project is built using [Antora](https://antora.org/), a powerful documentation site generator that supports multi-repository collaboration, content modularization, and flexible versioning.
 
 ## Contributing to the TinyMCE Documentation
 
-If you would like to contribute to the TinyMCE project please read the TinyMCE Documentation Contributor’s Guide at either:
+To contribute to the TinyMCE documentation project, please review the following resources:
 
-- [TinyMCE Documentation - Contributor's Guide](https://www.tiny.cloud/docs/configure/contributing-docs/).
-- [GitHub - How to contribute to TinyMCE’s documentation](https://github.com/tinymce/tinymce-docs/blob/release/docs-6/CONTRIBUTING.md#how-to-contribute-to-tinymces-documentation).
+- [GitHub - How to contribute to TinyMCE’s documentation](https://github.com/tinymce/tinymce-docs/blob/main/CONTRIBUTING.md#how-to-contribute-to-tinymces-documentation)
 
-## Working on TinyMCE documentation
+These guides cover contribution guidelines, project structure, style conventions, and best practices for submitting changes.
 
-### Compiling or building the documentation
+## Setting Up Your Development Environment
 
-The following procedure assists with building (or compiling) the documentation locally. Tiny recommends testing and reviewing changes locally prior to submitting a pull request.
+To contribute effectively, you should set up a local development environment. This allows you to preview and test your changes before submitting a PR.
 
-#### Installing Prerequisites
+### Prerequisites
 
-##### Linux users
+Ensure the following software is installed:
 
-You need the following programs installed on your computer:
+- [Node.js](https://nodejs.org/en/) (version 22.9 or lower)
+- [Yarn](https://yarnpkg.com/)
+- Git
 
-#### First time set up
+### Cloning the Repository
 
-Once you have installed any missing prerequisites, in a terminal or on a command prompt:
+Clone the TinyMCE documentation repository:
 
-1. Clone the git repository:
-    ```
-    git clone [email protected]:tinymce/tinymce-docs.git
-    ```
-
-2. Change directory into the cloned git repository:
-    ```
-    cd tinymce-docs
-    ```
-
-3. Run yarn install
-    ```
-    yarn install
-    ```
+```bash
+git clone [email protected]:tinymce/tinymce-docs.git
+cd tinymce-docs
+yarn
+```
 
-#### Run the development version of the documentation
+### Running the Development Server
 
-To create a development version of the documentation, run:
+To build and serve the documentation locally:
 
-```
+```bash
 yarn build
-yarn serve
+yarn start-dev
 ```
 
+Visit [http://127.0.0.1:4000](http://127.0.0.1:4000) to view the documentation. The server supports hot-reloading, so changes will automatically reflect when you save your work.
 
-To view the documentation; in a web browser, navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000).
-
-> **Note**: The development version of the documentation will update automatically when you save changes locally.
+> **Note:** The `yarn build` command generates the API reference documentation from the TinyMCE source code. To adjust the API version, edit the `API_VERSION` variable in the `scripts/api-reference.sh` file. Alternatively, use `yarn build-local` to build using a local TinyMCE instance:
 
-The `yarn build` step will download the latest TinyMCE package and generate new API reference content from source code. To change the version of TinyMCE API, open the `-scripts/api-reference.sh` file and edit the API_VERSION to the TinyMCE version you would like to generate API docs for.  Alternatively, to build using a local version of TinyMCE, `yarn build-local ../path/to/local/TinyMCE`.
+Example:
 
-> **Note**: The development server does not need to be stopped prior to running the `yarn build` command, antora should pick up the new changes generated by the build step.
+```bash
+yarn build-local ../path/to/local/tinymce
+```
 
-#### TinyMCE API documentation
+### API Documentation
 
-The TinyMCE API documentation is maintained within the [TinyMCE project repository](https://github.com/tinymce/tinymce) and compiled for the documentation site using [MoxieDoc](https://github.com/tinymce/moxiedoc).
+The TinyMCE API documentation is compiled and generated using [MoxieDoc](https://github.com/tinymce/moxiedoc) from the core [TinyMCE project repository](https://github.com/tinymce/tinymce). To update the published API docs:
 
-To update the published API documentation:
+1. Update the `.api-version` file.
+2. Run `yarn build`:
 
-1. Change the version in `.api-version`.
-2. Run `yarn build`.
+   * Running `yarn build` downloads the TinyMCE package specified in `.api-version` and generates new API reference content from source.
 3. Commit the changes.
 
-Running `yarn build` downloads the TinyMCE package specified in `.api-version` and generates new API reference content from source.
+> **Warning:** The API documentation should not be edited manually. Always generate it from source to ensure accuracy.
 
-**Note:** The API documentation should never be edited manually.
+## Live Demos
 
-##### Prerequisites
+Live demos can be added to the `modules/ROOT/examples/live-demos` directory. Reference them in your documentation with:
 
-- [Node.js](https://nodejs.org/en/).
-
-
-### Live Demos
+```asciidoc
+liveDemo::{sub-directory-name}[]
+```
 
-New live demos can be added to the [modules/ROOT/examples/live-demos directory](modules/ROOT/examples/live-demos). It then can be referenced in your doc with the following code:
+### Overriding the tinymce URL in Live Demos
 
-```
-  liveDemo::{sub-directory-name}[]
-```
+By default, live demos load TinyMCE from the URL specified in the `tinymce_live_demo_url` attribute in the `antora.yml` file. This can be overridden for specific use cases:
 
-#### Overriding the tinymce URL in live demos
+* Testing a new feature on the `dev` channel.
+* Running the site locally while testing live demos on a different channel.
 
-All live demos usually get their `tinymce.min.js` URL from the `tinymce_live_demo_url` setting in the `antora.yml` file.
-However, there are some instances where you wish to override this, e.g.
+To help with this, there are two mechanisms for overriding the `tinymce.min.js` URL:
 
- - You want to push/deploy a branch for a new feature that's only on the 'dev' channel.
- - You want to run the site locally, but test out the live demos in a different channel.
+1. **Global Override:**
+   To change the TinyMCE URL for all live demos, modify the `tinymce_live_demo_url` attribute in `antora-playbook-dev.yml`:
 
-To help with this, there are two mechanisms for overriding the `tinymce.min.js` URL.
+   ```yaml
+   asciidoc:
+     attributes:
+       tinymce_live_demo_url: https://your-custom-url.com/tinymce.min.js
+   ```
 
- 1. Change the URL for all live demos by setting the `tinymce_live_demo_url` attribute in `antora-playbook-dev.yml`. For example:
-    ```
-      asciidoc
-        attributes:
-          tinymce_live_demo_url: URL_to_script_file
-    ```
+2. **Per-Demo Override:**  Use the `script_url_override` attribute:
+   To override the URL for a specific live demo:
 
- 2. Change the URL for an individual live demo by setting `script_url_override` attribute in the live demo markup. For example:
-    ```
-      liveDemo::{sub-directory-name}[script_url_override='URL_to_script_file']
-    ```
+   ```asciidoc
+   liveDemo::{sub-directory-name}[script_url_override='https://your-custom-url.com/tinymce.min.js']
+   ```
 
-    - This is useful if you want to deploy the develop branch for a feature only in the 'dev' channel.
-    - This only overrides the URL for one live demo.
-    - Don't use this in more than one live demo on a page.
-    - Don't use this long-term - when the feature is fully rolled-out, use the standard channel.
+> **Caution:** Use this sparingly. Avoid using different URLs for multiple demos on the same page, and remember to revert these changes once the feature is fully released.

README.md

@@ -8,7 +8,7 @@ content:
     branches: HEAD
     start_path: ./
   - url: https://github.com/tinymce/tinymce-docs.git
-    branches: [ tinymce/5, tinymce/6, tinymce/7]
+    branches: [ tinymce/5, tinymce/6, tinymce/7 ]
 urls:
   html_extension_style: indexify
   latest_version_segment: latest

antora-playbook.yml

@@ -15,7 +15,7 @@ asciidoc:
     webcomponent_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent/dist/tinymce-webcomponent.min.js
     jquery_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-jquery@2/dist/tinymce-jquery.min.js
     openai_proxy_url: https://openai.ai-demo-proxy.tiny.cloud/v1/chat/completions
-    openai_proxy_token: eyJhbGciOiJFUzM4NCJ9.eyJhdWQiOlsiaHR0cHM6Ly9vcGVuYWkuYWktZGVtby1wcm94eS50aW55LmNsb3VkLyJdLCJleHAiOjE3NTEzMjgwMDAsImh0dHBzOi8vb3BlbmFpLmFpLWRlbW8tcHJveHkudGlueS5jbG91ZC9yb2xlIjoicHVibGljLWRlbW8iLCJpc3MiOiJodHRwczovL2FpLWRlbW8tcHJveHkudGlueS5jbG91ZC8iLCJqdGkiOiJmOGFmY2EyNC1mN2FhLTQxMjktYTc2Yy02YThlZDU3YjAyZjYiLCJzdWIiOiJhaS1hc3Npc3RhbnQtZGVtbyJ9.Xu0apHCbxgmRQTeTqrTIDFFhh2CgKeARRXa3mCxSGoCwZqkoQaFRZBCzDo8Xz7DuUa5mW2XHl-HYcYiXJM9ly16d0oY7lJefHBeLlmJEBE1CSttHBkCRWZS8eFLCasL6
+    openai_proxy_token: eyJhbGciOiJFUzM4NCJ9.eyJhdWQiOlsiaHR0cHM6Ly9vcGVuYWkuYWktZGVtby1wcm94eS50aW55LmNsb3VkLyJdLCJleHAiOjE3ODI4NjQwMDAsImh0dHBzOi8vb3BlbmFpLmFpLWRlbW8tcHJveHkudGlueS5jbG91ZC9yb2xlIjoicHVibGljLWRlbW8iLCJpc3MiOiJodHRwczovL2FpLWRlbW8tcHJveHkudGlueS5jbG91ZC8iLCJqdGkiOiIxZWY3NjJiNi1mZDYyLTQ3ZWQtOGRkNS0yOGRmMzBkZDU4YmMiLCJzdWIiOiJhaS1hc3Npc3RhbnQtZGVtbyJ9.WC8GIY19MgZneDVZoA-Ttt9E7gNkD0Yl-pcM_5c2RT3RdV_zE0i4bPOGBJpg_g6wu_4ki2ery6_JZtk2Q9gXEBHH7fIu7hXDFS8uIV9qe8MyxEqqRncGFVDjSTldVXGS
     default_meta_keywords: tinymce, documentation, docs, plugins, customizable skins, configuration, examples, html, php, java, javascript, image editor, inline editor, distraction-free editor, classic editor, wysiwyg
     # product docker variables
     dockerimageimportfromwordexporttoword: registry.containers.tiny.cloud/docx-converter-tiny

antora.yml

@@ -1,18 +1,23 @@
 import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then(({ faker }) => {
+  /* This represents a database of users on the server */
   const userDb = {
     'michaelcook': {
       id: 'michaelcook',
       name: 'Michael Cook',
-      fullName: 'Michael Cook',
-      description: 'Product Owner',
-      image: "{{imagesdir}}/avatars/michaelcook.png"
+      avatar: '{{imagesdir}}/avatars/michaelcook.png',
+      custom: {
+        fullName: 'Michael Cook',
+        description: 'Product Owner'
+      }
     },
     'kalebwilson': {
       id: 'kalebwilson',
       name: 'Kaleb Wilson',
-      fullName: 'Kaleb Wilson',
-      description: 'Marketing Director',
-      image: "{{imagesdir}}/avatars/kalebwilson.png"
+      avatar: '{{imagesdir}}/avatars/kalebwilson.png',
+      custom: {
+        fullName: 'Kaleb Wilson',
+        description: 'Marketing Director',
+      }
     }
   };
 
@@ -35,7 +40,7 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
   const getAuthorInfo = (uid) => {
     const user = userDb[uid];
     if (user) {
-      return fillAuthorInfo(user.id, user.fullName, user.image);
+      return fillAuthorInfo(user.id, user.custom.fullName, user.avatar);
     }
     return {
       author: uid,
@@ -85,8 +90,8 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
   const resolvedConversationDb = {};
 
   const setupFakeServer = () => {
-    const images = [ adminUser.image, currentUser.image ];
-    const userNames = [ adminUser.fullName, currentUser.fullName ];
+    const images = [ adminUser.avatar, currentUser.avatar ];
+    const userNames = [ adminUser.custom.fullName, currentUser.custom.fullName ];
 
     for (let i = 0; i < numberOfUsers; i++) {
       images.push(faker.image.avatar());
@@ -99,14 +104,16 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
       [currentUser.id]: currentUser
     };
     userNames.map((fullName) => {
-      if ((fullName !== currentUser.fullName) && (fullName !== adminUser.fullName)) {
+      if ((fullName !== currentUser.custom.fullName) && (fullName !== adminUser.custom.fullName)) {
         const id = fullName.toLowerCase().replace(/ /g, '');
         userDb[id] = {
           id,
           name: fullName,
-          fullName,
-          description: faker.person.jobTitle(),
-          image: images[Math.floor(images.length * Math.random())]
+          avatar: images[Math.floor(images.length * Math.random())],
+          custom: {
+            fullName,
+            description: faker.person.jobTitle(),
+          }
         };
       }
     });
@@ -118,8 +125,8 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
         const users = Object.keys(userDb).map((id) => ({
           id,
           name: userDb[id].name,
-          image: userDb[id].image,
-          description: userDb[id].description
+          image: userDb[id].avatar,
+          description: userDb[id].custom.description
         }));
         resolve(users);
       }, fakeDelay);
@@ -320,9 +327,6 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
     });
     setTimeout(() => done({ conversations: fetchedConversations }), fakeDelay);
   };
-
-  // Read the above `getAuthorInfo` function to see how this could be implemented
-  const tinycomments_fetch_author_info = (done) => done(getAuthorInfo(currentUid));
 
   tinymce.init({
     selector: 'textarea#comments-callback-with-mentions',
@@ -350,9 +354,16 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
     mentions_select,
 
     tinycomments_mode: 'callback',
-    tinycomments_author: currentUser.id,
-    tinycomments_author_name: currentUser.fullName,
-    tinycomments_avatar: currentUser.image,
+    user_id: currentUser.id,
+    fetch_users: (userIds) => {
+      return Promise.all(
+        userIds.map(
+          (userId) => new Promise(
+            (resolve) => resolve(userDb[userId] || { id: userId })
+          )
+        )
+      )
+    },
     tinycomments_create,
     tinycomments_reply,
     tinycomments_delete,
@@ -362,6 +373,5 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
     tinycomments_delete_comment,
     tinycomments_edit_comment,
     tinycomments_fetch,
-    tinycomments_fetch_author_info
   });
 });