Skip to content

Commit 157026c

Browse files
kemister85kemister85
committed
DOC-3220: Update the README.md file for tinymce/docs to include updated information.
1 parent a772c00 commit 157026c

File tree

1 file changed

+60
-77
lines changed

1 file changed

+60
-77
lines changed

‎README.md‎

Lines changed: 60 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,102 @@
1-
# TinyMCE documentation
1+
# TinyMCE Documentation
22

3-
This project maintains the documentation for TinyMCE at
4-
[https://www.tiny.cloud/docs](https://www.tiny.cloud/docs). If you have any
5-
modifications you wish to contribute, fork this project, make the changes
6-
and submit a pull request. You will need to sign the contributor’s license
7-
agreement, which will be emailed to you upon creating the pull request.
3+
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.
84

9-
This project is built using [Antora](https://antora.org/).
5+
This project is built using [Antora](https://antora.org/), a powerful documentation site generator that supports multi-repository collaboration, content modularization, and flexible versioning.
106

117
## Contributing to the TinyMCE Documentation
128

13-
If you would like to contribute to the TinyMCE project please read the TinyMCE Documentation Contributor’s Guide at either:
9+
To contribute to the TinyMCE documentation project, please review the following resources:
1410

15-
- [TinyMCE Documentation - Contributor's Guide](https://www.tiny.cloud/docs/configure/contributing-docs/).
16-
- [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).
11+
- [TinyMCE Documentation - Contributor's Guide](https://www.tiny.cloud/docs/configure/contributing-docs/)
12+
- [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)
1713

18-
## Working on TinyMCE documentation
14+
These guides cover contribution guidelines, project structure, style conventions, and best practices for submitting changes.
1915

20-
### Compiling or building the documentation
16+
## Setting Up Your Development Environment
2117

22-
The following procedure assists with building (or compiling) the documentation locally. Tiny recommends testing and reviewing changes locally prior to submitting a pull request.
18+
To contribute effectively, you should set up a local development environment. This allows you to preview and test your changes before submitting a PR.
2319

24-
#### Installing Prerequisites
20+
### Prerequisites
2521

26-
##### Linux users
22+
Ensure the following software is installed:
2723

28-
You need the following programs installed on your computer:
24+
- [Node.js](https://nodejs.org/en/) (version 22.9 or lower)
25+
- [Yarn](https://yarnpkg.com/)
26+
- Git
2927

30-
#### First time set up
28+
### Cloning the Repository
3129

32-
Once you have installed any missing prerequisites, in a terminal or on a command prompt:
30+
Clone the TinyMCE documentation repository:
3331

34-
1. Clone the git repository:
35-
```
36-
git clone [email protected]:tinymce/tinymce-docs.git
37-
```
38-
39-
2. Change directory into the cloned git repository:
40-
```
41-
cd tinymce-docs
42-
```
43-
44-
3. Run yarn install
45-
```
46-
yarn install
47-
```
32+
```bash
33+
git clone [email protected]:tinymce/tinymce-docs.git
34+
cd tinymce-docs
35+
yarn
36+
```
4837

49-
#### Run the development version of the documentation
38+
### Running the Development Server
5039

51-
To create a development version of the documentation, run:
40+
To build and serve the documentation locally:
5241

53-
```
42+
```bash
5443
yarn build
55-
yarn serve
44+
yarn start-dev
5645
```
5746

47+
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.
5848

59-
To view the documentation; in a web browser, navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000).
60-
61-
> **Note**: The development version of the documentation will update automatically when you save changes locally.
49+
> **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:
6250
63-
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`.
51+
Example:
6452

65-
> **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.
53+
```bash
54+
yarn build-local ../path/to/local/tinymce
55+
```
6656

67-
#### TinyMCE API documentation
57+
### API Documentation
6858

69-
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).
59+
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:
7060

71-
To update the published API documentation:
61+
1. Update the `.api-version` file.
62+
2. Run `yarn build`:
7263

73-
1. Change the version in `.api-version`.
74-
2. Run `yarn build`.
64+
* Running `yarn build` downloads the TinyMCE package specified in `.api-version` and generates new API reference content from source.
7565
3. Commit the changes.
7666

77-
Running `yarn build` downloads the TinyMCE package specified in `.api-version` and generates new API reference content from source.
67+
> **Warning:** The API documentation should not be edited manually. Always generate it from source to ensure accuracy.
7868
79-
**Note:** The API documentation should never be edited manually.
69+
## Live Demos
8070

81-
##### Prerequisites
71+
Live demos can be added to the `modules/ROOT/examples/live-demos` directory. Reference them in your documentation with:
8272

83-
- [Node.js](https://nodejs.org/en/).
84-
85-
86-
### Live Demos
73+
```asciidoc
74+
liveDemo::{sub-directory-name}[]
75+
```
8776

88-
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:
77+
### Overriding the tinymce URL in Live Demos
8978

90-
```
91-
liveDemo::{sub-directory-name}[]
92-
```
79+
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:
9380

94-
#### Overriding the tinymce URL in live demos
81+
* Testing a new feature on the `dev` channel.
82+
* Running the site locally while testing live demos on a different channel.
9583
96-
All live demos usually get their `tinymce.min.js` URL from the `tinymce_live_demo_url` setting in the `antora.yml` file.
97-
However, there are some instances where you wish to override this, e.g.
84+
To help with this, there are two mechanisms for overriding the `tinymce.min.js` URL:
9885

99-
- You want to push/deploy a branch for a new feature that's only on the 'dev' channel.
100-
- You want to run the site locally, but test out the live demos in a different channel.
86+
1. **Global Override:**
87+
To change the TinyMCE URL for all live demos, modify the `tinymce_live_demo_url` attribute in `antora-playbook-dev.yml`:
10188
102-
To help with this, there are two mechanisms for overriding the `tinymce.min.js` URL.
89+
```yaml
90+
asciidoc:
91+
attributes:
92+
tinymce_live_demo_url: https://your-custom-url.com/tinymce.min.js
93+
```
10394
104-
1. Change the URL for all live demos by setting the `tinymce_live_demo_url` attribute in `antora-playbook-dev.yml`. For example:
105-
```
106-
asciidoc
107-
attributes:
108-
tinymce_live_demo_url: URL_to_script_file
109-
```
95+
2. **Per-Demo Override:** Use the `script_url_override` attribute:
96+
To override the URL for a specific live demo:
11097
111-
2. Change the URL for an individual live demo by setting `script_url_override` attribute in the live demo markup. For example:
112-
```
113-
liveDemo::{sub-directory-name}[script_url_override='URL_to_script_file']
114-
```
98+
```asciidoc
99+
liveDemo::{sub-directory-name}[script_url_override='https://your-custom-url.com/tinymce.min.js']
100+
```
115101
116-
- This is useful if you want to deploy the develop branch for a feature only in the 'dev' channel.
117-
- This only overrides the URL for one live demo.
118-
- Don't use this in more than one live demo on a page.
119-
- Don't use this long-term - when the feature is fully rolled-out, use the standard channel.
102+
> **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.

0 commit comments

Comments
 (0)