diff --git a/README.md b/README.md index be169e039f..48fa09273e 100644 --- a/README.md +++ b/README.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 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.