Skip to content

DOC-3220: Update the README.md file for tinymce/docs project to include updated information. (#3733) #3800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kemister85 merged 3 commits into from
Jul 23, 2025
Merged

DOC-3220: Update the README.md file for tinymce/docs project to include updated information. (#3733) #3800

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9f02248
DOC-3220: Update the `README.md` file for `tinymce/docs` project to i…
kemister85 Jul 15, 2025
16cb92c
Update README.md
kemister85 Jul 21, 2025
ad62ed5
Update README.md
kemister85 Jul 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 59 additions & 77 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/)

## 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.