From 157026c86e08eb5df76312fe38904512a6520a6b Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 19 May 2025 22:02:57 +1000 Subject: [PATCH 1/3] DOC-3220: Update the README.md file for tinymce/docs to include updated information. --- README.md | 137 ++++++++++++++++++++++++------------------------------ 1 file changed, 60 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index be169e039f..cacb5a7291 100644 --- a/README.md +++ b/README.md @@ -1,119 +1,102 @@ -# 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). +- [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) -## 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 git@github.com:tinymce/tinymce-docs.git - ``` - -2. Change directory into the cloned git repository: - ``` - cd tinymce-docs - ``` - -3. Run yarn install - ``` - yarn install - ``` +```bash +git clone git@github.com: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. From c5b27d27d326c96477ed02c0b2929386606162a8 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 20:48:06 +1000 Subject: [PATCH 2/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cacb5a7291..f809971729 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This project is built using [Antora](https://antora.org/), a powerful documentat 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) These guides cover contribution guidelines, project structure, style conventions, and best practices for submitting changes. From 28327a2be7b0262633449003b078d5c6a8c09ba0 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 15 Jul 2025 20:54:28 +1000 Subject: [PATCH 3/3] Update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index f809971729..48fa09273e 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,6 @@ This project is built using [Antora](https://antora.org/), a powerful documentat 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/main/CONTRIBUTING.md#how-to-contribute-to-tinymces-documentation) These guides cover contribution guidelines, project structure, style conventions, and best practices for submitting changes.