Contribute to documentation

This page outlines how you can provide feedback and contribute to TinyMCE documentation.

Contributor Code of Conduct

For our Contributor Code of Conduct, visit our Contributor Covenant Code of Conduct on GitHub.

How to contribute to TinyMCE’s documentation

We welcome people with technical writing experience to help make TinyMCE’s docs as useful to our community as possible. Although you don’t need to be an expert developer to contribute, a basic understanding of software development is helpful.

What is more important is your ability to articulate complex ideas. Our goal is to help developers understand TinyMCE’s functionality as quickly as possible.

Simply branch the docs GitHub repository and submit a PR, or reach out to the TinyMCE docs team if you have a specific question.

TinyMCE documentation tech stack

The documentation is built with Jekyll. Text files are written in kramdown and published on GitHub. You will find the repo here.

Markdown & code syntax

The documentation is written in kramdown Flavored Markdown. If you are not familiar with kramdown read this.

Highlighting

Code language syntax and associated elements are highlighted using an open and closing backtick. For example, this object is actually enclosed with backticks like this: object.

Highlight words relating specifically to executable parts of software languages. Keys and their values when pertaining to objects and methods (particularly the case with TinyMCE) should have backticks. We cannot cover every use case here and contributors need to use their best judgment. What is more important is your ability to articulate complex ideas.

Code snippets

Code snippets should always be complete, executable code blocks starting with the tinymce object. We write code snippets by enclosing the example code within three opening and closing backticks. The first set of backticks is immediately followed by the code’s language, which helps correct syntax highlighting: typically, html, css, js (and sometimes php).

Include any key values pairs and method options that are required to enable a user to test the snippet in a local HTML file. You do not need to include the html surrounding the tinymce object that would be required to make the snippet work.

For example, this is good:

tinymce.init({
  selector: 'textarea', // change this value according to your HTML
  plugins: 'codesample',
  toolbar: 'codesample',
});

This is not:

tinymce.init({
  ...
  plugins: 'codesample',
  toolbar: 'codesample'
  ...
});

URLs and links

Resources to be linked take the form of placing the linked text between brackets and the URL between parenthesis. Linking an external resource looks like this:

hello, [text to link](http://www.example.com) to the URL example.com.

Live demos

Live demos can be added to content using the "live-demo.html" include, such as:

liveDemo::basic-example[]

There are several options for this include file, see _includes/live-demo.html for details.

The source for each live-demo is store in the _includes/live-demos/ directory.

Adding metadata to a page

Every page should have a meta section starting at line 1 containing information that is both informative and system critical. If you are creating a page or editing one that currently has inadequate meta information, please read the comments next to the default meta fields below.

---                // Three dashes at the start and end of the meta section, must be included.
layout: default    // In most cases leave this as 'default'.
title:             // The nav.yml references this so it must be included and it should be brief.
title_nav:         // Descriptive title for the navigation bar, if omitted nav defaults to title field.
description_short: // Short description for the grid layouts.
description:       // Detailed description at page level for the header section under the title.
keywords:          // Space-separated list of keywords in the content.
---

Recommended tools

The following tools are recommended for significant edits to the documentation. The warnings and notifications from these tools should only be used as guides, not as rules.

A Spelling Checker (US English). Note: Some IDE/text editor spelling checkers work well with Pascal-case, Camel-case, and Snake-case.
Alex - Alex.js integrations.
Write Good - Write good based plugins.
A markdown linter (We use the Kramdown flavor of markdown).
A Jekyll linter.

Style guide

You are not required to know the style guide, but changes may be requested on GitHub pull requests to Tiny documentation where these guidelines are not met.

The Tiny documentation style guide is based on the Readability Guideline provided by Content Design London. We have chosen this guide because it’s:

open to the community
focused on readability.

The information in the following subsections gives an overview of key points and lists both exceptions and additions. Please follow the guidelines on this page when they differ from the linked information.

For information the Readability Guidelines project, visit Content Design London: Readability Guidelines.

Keep it simple

Use short, simple words where possible. Use formal language.

Do not use:

Long sentences.
Slang; such as there you go.
Jargon; such as leverage and streamline.
Ambiguous contractions; such as there’d, and it’ll.
Latin terms; such as i.e., e.g., etc., vs., and via.
Metaphors; such as cherry picking and nutshell.
Complex or specialist terms; such as chrome (the toolbar, menu bar, status bar) and upstream.

For guidelines on using specialist terms, see: Content Design London: Readability Guidelines - Specialist terms.

For information on:

Using simple words, see: Content Design London: Readability Guidelines - Plain English.
Short, simple sentences, see: Content Design London: Readability Guidelines - Simple sentences.
Words to avoid, such as jargon, metaphores, and Latin terms; see: Content Design London: Readability Guidelines - Words to avoid.

For a short list of some commonly used Latin terms, see: Australian Government Style Manual - Latin shortened forms.

Use US English (en_US) spelling

Use United States English. For example:

"behavior" rather than "behaviour".
"canceled" rather than "cancelled".

Use proper names for programs and languages

When referring to the name of a development language, use the proper name or the industry convention.

For example:

"CSS" not "css"
"jQuery" not "Jquery"
"React" not "React-js"

When using these terms in code elements (`) or pre blocks (```), use standard syntax. Such as:

tinymce
<html>
var React = require('react');

When referring to a program, use the proper name.

For example:

"Microsoft Internet Explorer" not "IE"
"Apache Tomcat" not "Tomcat"
"TinyMCE" not "Tiny"

TinyMCE or tinymce

Use the capitalized version of TinyMCE when referring to the open source project or the editor. "TinyMCE" is an abbreviation of "Tiny MoxieCode Editor", but is better known as TinyMCE.

Use lowercase when referring to the tinymce JavaScript object.

Use Active voice not Passive voice

Use active voice. Passive voice decreases readability and comprehension.

For information on the difference between active and passive voice, see: Grammar Girl: Active Voice Versus Passive Voice.

Titles and headings

Titles and headings should be:

Descriptive but concise
Written using Sentence-case capitalization.

Sentence case capitalization is more comfortable to read in technical documentation.

For guidelines on headings and titles, see: Content Design London: Readability Guidelines - Headings and titles.

Using abbreviations, acronyms, and intialisms

General points:

Do not use points or spaces.
Write out "for example" and "that is" in full (not "eg" or "ie").
If an acronym is better understood than the full text, use the acronym.
Use all capital letters for initialisms.
Start with a capital letter for acronyms.
Capitalize single letters in expressions.
Provide full text explanations.
Consider providing a full explanation each time.

For guidelines on using abbreviations, acronyms, and intialisms; see: Content Design London: Readability Guidelines - Abbreviations and acronyms.

Adverbs

Avoid adverbs, such as: very and usually.

For examples and a definition of an adverb, see: Cambridge Dictionary: Grammar - Adverbs.

For (casual) information on removing adverbs, see: Grammar Girl: How to Eliminate Adverbs.

Contractions

Avoid contractions, such as: can’t, don’t, they’re, and could’ve.

For information on contractions, see: Content Design London: Readability Guidelines - Contractions.

Hyphens

Limit use of hyphens. Some general pointers:

Only use a hyphen if the word or phrase is confusing without it.
Make sure your hyphen usage is up to date.
Be consistent with hyphen usage.

For guidelines on using hyphens, see: Content Design London: Readability Guidelines - Hyphens and dashes.

Pronouns

Avoid pronouns, such as: we, you, their, and I.

For examples and a definition of an pronoun, see: Cambridge Dictionary: Grammar - Pronouns.

For reasons to avoid pronouns, see: Content Design London: Readability Guidelines - We, you, our, your, my.

First, Second, or Third Person Perspective

Write in a second person perspective, such as: You, and your. Remember to avoid using pronouns, including you and your.

For information on writing in a second person perspective, see: Grammar Girl: First, Second, and Third Person.

Links and cross-references

When adding links or cross-references:

Make link text meaningful.
Avoid mid-sentence links.
Match the destination content.
Use sentence case.

For guidelines on adding links to the documentation, see: Content Design London: Readability Guidelines - Links.

Images and icons

Avoid adding images to the documentation. They can quickly become outdated. Use a description or a "demo" instead.

When images are used, reuse existing images if possible. This includes icons.

Ensure a brief description of the image is provided in the alternative text attribute.

For information on providing useful alternative text for images, see: WCAG 2.1 specification: G95 - Providing short text alternatives that provide a brief description of the non-text content.

Talking about the user interface

Tiny uses the Microsoft Style Guide for describing the user interface and interacting with the user interface. Some exceptions may exist in the glossary at the end of this page.

For guidelines on:

Describing interactions with the user interface for a procedure or task, see: Microsoft Style Guide: Describing interactions with UI.
Describing interactions with the user interface for a procedure or task with multiple input methods; for example, procedures that can be performed with a keyboard or a mouse; see: Microsoft Style Guide: Describing alternative input methods - Multiple input methods and branching within procedures.
Referring to user interface elements in instructions or procedures, see: Microsoft Style Guide: Formatting text in instructions.
Referring to the mouse and mouse-based interactions, such as "click" and "right mouse button"; see: Microsoft Style Guide: Mouse and mouse interaction terms.
Referring to keyboard keys and keyboard shortcuts, see: Microsoft Style Guide: Keys and keyboard shortcuts.
Referring to touch interactions, such as "tap" and "swipe"; see: Microsoft Style Guide: Describing alternative input methods - Pen-computing and touch procedures.

Adding admonitions or notes

Avoid adding admonitions (also known as: notices, notes, warnings, or callouts) where possible. Over-use of admonitions may lead to what is sometimes referred to as "Admonition Fatigue". For an article on reason for limiting the use of admonitions, see: Harvard Business Review: Consumer Warning Labels Aren’t Working.

Admontions typically start with: Tip, Note, Important, Caution, or Warning.

For example:

This is a note; used for additional, indirectly related information.

This is a note that is important for users to read.

Tiny documentation uses four levels of admonition:

NOTE: Use for additional, indirectly related information. Do not use where it is possible to reword or rewrite the content to incorporate the information.
IMPORTANT: Use when ignoring the notice may or will lead to unexpected behavior.
CAUTION: Use when ignoring the notice may lead to one or more of the following:
- A significant increase in the risk of a security breach.
- Create a security vulnerability.
- Cause information loss.
- System failure.
- Worse outcomes than those listed here.
WARNING: Use when ignoring the notice will lead to one or more of the following:
- A significant increase in the risk of a security breach.
- Create a security vulnerability.
- Cause information loss.
- System failure.
- Worse outcomes than those listed here.

Useful general writing advice

The following pages provide advice on writing, including technical writing.

For a brief overview of how users read (or don’t read) content, see: Content Design London: Readability Guidelines - How people read.
For points on how to structure content, see: Content Design London: Readability Guidelines - Page design.
For general information on writing, covering a variety of subjects, see: plainlanguage.gov: Mary Dash’s Writing Tips.

Glossary

Accessible Rich Internet Applications (ARIA)

Acronym for Accessible Rich Internet Applications Spell out and describe on first mention within a section.

See: MDN Web Docs - ARIA.

add-on

Do not use add-on. Use "`plugin`" instead.

anchor

Use when describing the Anchor plugin or the technical insertion of an anchor tag into HTML. When talking with a business audience, use bookmark or add bookmark as a clarifier.

Application Programming Interface (API)

Use API in most circumstances. Spell it out on first mention only if the document is for a non-technical audience.

asynchronous, async

Use asynchronous Do not use async.

back end, back-end, backend

Do not use backend. Use back end as a noun. Use back-end as a compound adjective.

bookmark

A common term for a HTML anchor element. Use bookmark instead of anchor in content for a general audience. Do not use when referring to the anchor plugin.

control, such as control identifier

Do not use. Use the type of control, such as Toolbar button or Menu item

Cascading Style Sheets (CSS)

Capitalize references to the technique for adding formatting and styles to web content. Do not use CSS to refer to a specific cascading style sheet. Instead, use CSS file or style sheet.

channel

Use channel to describe the various CDN URLs that developers can use to source the TinyMCE JavaScript files.

For example: Load TinyMCE from the stable channel on Tiny Cloud by including the following script tag.

cloud

Use cloud as an adjective. Do not use as a noun (the cloud). Do not use cloud interchangeably with internet

configuration option, configuration setting, configuration parameter

Use configuration option. For example: the selector configuration option. This can be abbreviated to option in sequential mentions, such as: the selector option.

configuration, config

Use configuration. Do not abbreviate to config.

content delivery network (CDN)

Spell out and describe on first mention within a section.

content management system (CMS)

Spell out and describe on first mention within a section.

content security policy (CSP)

Spell out and describe on first mention within a section. See: MDN Web Docs - Content Security Policy (CSP).

context menu

Use context menu in content for developers. Make it clear it refers to the shortcut menu activated using a mouse right-click.

cross-site scripting (XSS)

Spell out and describe on first mention within a section. See: OWASP (Open Web Application Security Project) - Cross Site Scripting (XSS).

digital asset management (DAM)

Spell out and describe on first mention within a section.

documentation, docs

Use documentation.

editable area, editor canvas, content area, editor content

Use editor content to refer to the content editing canvas.

emoji, emoticons

Do not use emoji (😄) or emoticons (:-() in the documentation.

There may be exceptions on pages talking about emoji or emoticons.

Use the terms emoji and emoticon as required.

Ephox

Old business name phased out in 2018. Use Tiny or Tiny Technologies Inc..

example, examples

Do not use as a heading, provide a detailed heading.

In text, use The following example uses… or The following example shows….

exclamation points ("!")

Do not use in text, only use in code where required.

extension

Do not use. Use plugin instead.

execute/executed

Do not use. Use run (or ran for past-tense) instead.

front end, front-end, frontend

Do not use frontend. Use front end as a noun. Use front-end as a compound adjective.

HTML

Do not spell out. Do not use html (except in codeblocks).

JavaScript, JS

The correct capitalization is JavaScript Do not use Javascript or javascript Do not use JS unless it is referring to a specific library such as PrismJS

For example: Another popular JavaScript minification tool, UglifyJS2, will corrupt TinyMCE unless ASCII-only is set.

menu bar, menubar

Use menu bar as two words. Do not use menubar or menu-bar as a compound word.

plugin

The preferred way of referring to an add-on or extension for TinyMCE. Do not use add-on, extension, app, or plug-in.

premium features

premium features and not Premium features.

programmer

Do not use. Use developer.

question marks ("?")

Use questions sparingly. In general, user want us to give them answers. When a customer needs to make a decision, a question may be appropriate.

Bad example:

Why make TinyMCE mobile friendly?

Good examples:

If you forgot your password, provide your secret answer.
More nature themes are available online.
Do you want to save your changes?

quickstart, quick start

Content to help developers get our products up and running quickly. Use quickstart.

rich text editor, rich-text editor, RTE

Most common way to refer to TinyMCE’s product category.

Use rich text editor rather than rich-text editor (even if the later may be more technically correct). Do not use RTE.

screen size, screensize

Use screen size.

SDK

Do not use. Use Self-hosted installation.

See or Refer to…

Use see for internal links, use visit for external links.

Such as: For information on creating links, see: <link>.

self-hosted

The preferred way to refer to an on-premises deployment of our technology.

self-hosted premium plugins

Preferred. Do not use premium plugin SDKs.

should or must

Avoid using must or should Only use where it is unavoidable.

submenu

Use submenu Do not use sub-menu or sub menu.

Software as a Service (SaaS)

Spell out on the first mention in a section for general audience. For a technical audience, it is always OK to use SaaS.

Do not capitalize as SAAS.

Do not hyphenate as a modifier, but include the abbreviated form in parentheses.

spell checking, spell checker, spell check

Do not use the compound words spellcheck or spellchecker

Do not hyphenate.

textarea, text box, textbox

Use textarea to refer to a multi-line text box in a form.

Tiny

Use to refer to the company or our entire solution/platform.

Do not use Tiny to refer to the core editor, which is TinyMCE.

Tiny 4.x, Tiny 5.0

Tiny is not a product. Do not give it a version. Use the product name, such as TinyMCE 5.0 or TinyMCE 4.9.

Tiny Cloud

Correct way to refer to the Tiny Cloud service. Spell it out on all occasions.

For example: Tiny Cloud includes a fast content delivery network.

Tiny Technologies Inc.

Tiny Technologies Inc. is full and correct business name for Tiny

Do not use Ephox Corporation.

TinyMCE

This is the JavaScript library for rich text editing.

Capitalize the MCE Do not use Tinymce tinymce is allowed in code and codeblocks where required.

TinyMCE 4

Correct way to refer to the 4.x releases of TinyMCE unless a specific version number (major.minor.patch) is required.

TinyMCE 4.x

Do not use. Use TinyMCE 4 or version 4 If necessary to specify the availability of a new feature or change in behavior, specify the minor version number such as TinyMCE 4.7.

TinyMCE 5

Correct way to refer to the 5.x releases of TinyMCE unless a specific version number (major.minor.patch) is required.

TinyMCE Cloud

Do not use. Use Tiny Cloud.

UI component

Collective term for TinyMCE user interface elements, such as: dialogs, toolbars, and toolbar buttons.

UI element

Avoid using UI element.

URL, url, Url

Use URL Do not spell out the acronym. Do not use url or Url.

user

Typically refers to the end user of TinyMCE (such as the content author).

Use end user when it is necessary to delineate between the developer as a user and the end user of TinyMCE.

Use Integrator or developer where appropriate.

user experience (UX), experience

Be careful to use UX and UI correctly as they are different. Spell out user experience to give it context.

Avoid using experience

Do not use UI experience

For example:

To give feedback on the TinyMCE user experience on mobile devices, complete this survey.

user interface (UI)

Acceptable to use UI in most communication. For content destined for non-technical users, spell out user interface (UI) the first time it used in the document.

Do not use Ui or ui

Do not use UI experience It is either user experience (UX) OR user interface (UI), but never both.

web

Do not use web Use Internet for clarity. Can be used for terms such as web server.

Web Content Accessibility Guidelines (WCAG)

Acronym for Web Content Accessibility Guidelines Spell out and describe on first mention within a section.

WYSIWYG

Avoid using WYSIWYG Use rich text editor

It stands for what you see is what you get Make sure to use the acronym correctly, it is easy to misspell.