tinymce / tinymce-docs

TinyMCE Documentation

TinyMCE documentation

This project maintains the documentation for TinyMCE at 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 is built using Antora.

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:

• TinyMCE Documentation - Contributor's Guide.
• GitHub - How to contribute to TinyMCE’s documentation.

Working on TinyMCE documentation

Compiling or building the documentation

The following procedure assists with building (or compiling) the documentation locally. Tiny recommends testing and reviewing changes locally prior to submitting a pull request.

Installing Prerequisites

Linux users

You need the following programs installed on your computer:

First time set up

Once you have installed any missing prerequisites, in a terminal or on a command prompt:

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
   

Run the development version of the documentation

To create a development version of the documentation, run:

yarn build
yarn serve

To view the documentation; in a web browser, navigate to http://127.0.0.1:4000.

Note: The development version of the documentation will update automatically when you save changes locally.

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.

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.

TinyMCE API documentation

The TinyMCE API documentation is maintained within the TinyMCE project repository and compiled for the documentation site using MoxieDoc.

To update the published API documentation:

1. Change the version in .api-version.
2. Run yarn build.
3. Commit the changes.

Running yarn build downloads the TinyMCE package specified in .api-version and generates new API reference content from source.

Note: The API documentation should never be edited manually.

Prerequisites

• Node.js.

Live Demos

New live demos can be added to the modules/ROOT/examples/live-demos directory. It then can be referenced in your doc with the following code:

  liveDemo::{sub-directory-name}[]

Overriding the tinymce URL in live demos

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.

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

To help with this, there are two mechanisms for overriding the tinymce.min.js URL.

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. 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']
   

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

tinymce-docs's Issues

Duplicate entry

Configuration Settings -> Editor Appearance: There are two entries for 'toolbar', the second of which is broken.

left nav should scroll to always keep visible the active page

When the left nav is too tall, a page refresh will hide the active item in the nav if it's too low in list

Backticked code in titles should be the same size as the title

Text marked with backticks in titles currently defaults to the <p> style and size. It would ideally be similar in size and style as the element it is inline with, e.g h3.

http://localhost:4000/getting-started/first-steps/#stepsavingcontentwithaformpost

test

Rendering of banner on features page is wrong

See attached. I haven't been able to replicate exactly when this occurs but I have seen it multiple times.

I believe it has to do either with first load, retina displays or large screens!

Wrong encoding for snippet

see /editor-configuration-settings/content-filtering/#protect

Basic Configuration Article - Example

Ehe Basic Configuration example introduces config settings that were not previous introduced in the article. Width and Height are pretty simple so not much of a problem. Theme is probably ok too. But I have a hard time with style formats. If we are going to include the in the example then we should introduce the beforehand. If not, then I suggest we remove them from the example. I'm thinking these maybe too much for a basic config.

Also the link at the end to 'formats configuration' is broken.

The class "typ" is too big on the bottom margin

The class "typ" is too big on the bottom margin so that when two instances of the class are applied to text sitting above/below each other (i.e. within the same sentence and where the sentence has wrapped) the effect applied to the span merges.

See the 3rd para on this page where 'file' and 'edit' merge with the word 'edit' below.

http://localhost:4000/getting-started/basic-configuration/#aquicklookatmenuandmenubarcontrols

It looks like it's too big by only 1px?

Sidebar nav highlights both BBCode and Code plugins

Go to the BBCode plugin page. For example:
http://127.0.0.1:4000/plugins/bbcode/

The side nave for both the BBCodde and the Code plugins is highlighted in blue.

Check all external URLs

@r12s - can you use search to look for all "http://" links in the docs and confirm they are going to the right location now?

I know there are a lot referencing old parts of the website for example.

Content/pages from old site missing in redesign

There are links in the docs pointing to pages on the "old" site that (as far as I know) haven't been discussed in the redesign and therefore don't yet exist.

• http://www.tinymce.com/i18n/index.php
• http://www.tinymce.com/download/compressors.php
• http://www.tinymce.com/develop/develop.php

Are there any others?

Tiled page content hidden by footer

@kilianc content in pages using the tiled layout with greater than 10 items disappear into the footer. The page stops scrolling.

See attached image, where items 11 and 12 are behind in the footer.

Ref http://beta.tinymce.com/docs/get-started/

Add Insitez NPS Survey to docs template

We have an NPS survey that we have been running on the existing tinymce.com that I would like to run on the docs so that we can benchmark satisfaction with the new design.

Will get the necessary JavaScript for this ticket.

React-TinyMCE Integration article

This might help:
https://github.com/instructure-react/react-tinymce

Images not deploying

Images in here are not getting deployed:
http://beta.tinymce.com/docs/enterprise/check-spelling/troubleshoot/

sort api methods and props alphabetically

Anchors aren't unique

This is notable in the Changelog but is a more widespread bug I believe.

The heading 2 is "Version 4.2.2 — July 22, 2015"

And the anchor that is generated is #versionjuly

This is not unique in this document.

Sidenav highlighting sometimes highlights two points

See attached image. When there are two articles in view (such as in the config section) two nav items can be highlighted. Not a showstopper but visually not ideal.

Line spacing of h4 titles is too tight

Line spacing of h4 titles (markdown ####) appears to be too tight. It would be slightly easier to read if spacing was larger than the font size. Looks like both are at 30px?

http://localhost:4000/getting-started/advanced-installation-options/#useoflocalpluginslanguagepackswheninstallingviapackagemanagers

Google Analytics for website

so far I only have the snippet for the docs, or is it the same?

Improve styling of changelog

The changelog is awfully plain right now.

I really like this one:
https://help.us-themes.com/zephyr/changelog/

Add article on configuring for multiple editors on single page

A pretty common use case is for people to want to have multiple editable spots on a single page. This can be done in both classic mode (not as often) as well as inline (very common). This topic doesn't appear to be addressed anywhere else in the documentation and we do get questions on this that come into support. I recommend we document the following:

• How and why to use multiple inits (ex. I want to have different config for editing H1s vs. Divs)
• How to use sector within single TinyMCE init. There are multiple ways of doing this. We don't need to describe all of them, but a couple of examples would be good.
• examples for inline and maybe one for classic.

Explore Gzip Compressing Content

Our lack of compression is hurting our speed a bit. At least in the eyes of Google's PageSpeed:
https://developers.google.com/speed/pagespeed/insights/?url=http%3A%2F%2Fbeta.tinymce.com%2Fdocs%2F&tab=desktop

Unfortunately S3 doesn't do this automatically and there appears to be quite a few hoops to jump through:
http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/ServingCompressedFiles.html#CompressedS3

Changes needed to Support sections

A number of changes should be made to this Support article:

• The ordering of info seems odd. The section starts with a 'now that you are finished this is what you should do' before the actual contents of the article. Shouldn't this be flipped? It would be more consistent with the rest of the documentation
• Please remove the pointer to Stack Overflow. We prefer users to post questions to the TinyMCE forum rather than StackOverflow. Those who like to use Stack Overflow will use it regardless. Those that don't care should be directed to our forum.
• I don't want to include Premium Support info in the same article as Community Support. This needs to be placed into a dedicated article for Enterprise clients. (the reason is that this could lead some Community users down the route of opening tickets which leads to wasted time on our end and potential dissatisfaction on their end.

h1 font size is smaller than h2

Currently h1 font size (derived from # in the markdown) is smaller than h2 (markdown ##). See the title "Plugins" on this page:

http://localhost:4000/getting-started/working-with-plugins/

(Note, the "plugins" title on this page is redundant and I'll remove it in my current edits, but there may be instances where we do need a h1 and it won't be styled correctly.)

Create Examples Directory

Create "View Examples" section of the docs - just below Get Started.

Create a page for each of the examples that we need to bring across from the current www website.

Missing List Plugin

Plugin on old site called lists that we haven't migrated.

http://www.tinymce.com/wiki.php/Plugin:lists

Hover over unreadable for configuration settings

The hover over color for all of the entries under configuration settings appears to be white which renders them unreadable.

Ensure consistency of spelling

spell checker vs. spellchecker

PowerPaste vs Power Paste

others?

Lists don't inherit paragraph style

@kilianc ordered and unordered list font size is smaller than body

text.

Ref list http://localhost:4000/docs/get-started/basic-setup/

Intermingling Pro/Enterprise info within the doc is problematic

We need to either create Pro / Enterprise 'companion' docs, or create a separate Pro / Enterprise section of this doc. For a number of reasons:

• the pro plugins get lost in the long list of standard plugins. That list is already too long and adding the pro plugins just makes it worse. We'll need to eventually categorize the plugin list which would just make it worse if we have pro plugins spread across a bunch of different categories.
• System requirements differ between Community and Suported versions
• Support differs not only between Community and fee...but will differ between the different fee based coverings.
  By spreading the Pro / Enterprise info out across the document we are making it more difficult for our paying clients and we create more opportunities for people to be confused.

Problem with page plugins/autoresize.md

Autoresize Plugin issue:

There should be a short intro that better explains what this plugin does. The intro would also make it more consistent with the rest of the plugins doc.

Contribute icon not ideal

This might be a matter of taste but it kind of looks like a no smoking sign.
Perhaps we should try and icon without the circle around it?

The text color for Notes is too light

The text color for Notes (designated by the green side bar) within articles is too light. Users with less than ideal eye sight/color perception could have an issue. This would not pass an accessibility test. I suggest using something that is darker to create greater contrast.

Premium plugins need a visual indicator in the sidebar

Some sort of "pro" badge perhaps? E.g. moxiemanager

Problem with page plugins/bbcode.md

BBCode Plugin issue:

We need to add a better explanation for this plugin.

TinyMCE Language Article requires changes

Required changes:

• This article uses the term internationalization improperly. What the article is mainly talking about is localization, not internationalization.
• We should make it clear that these translations are provided by the Community. (btw...these are not included in our Enterprise Offering and are not supported).
• The link is pointing to the old site. Will this be part of the re-do?

Decide on and add license to docs

This is a WIP I am discussing.

When should we include 4.3 changes

@kilianc @andrew I noticed a 4.3 plugin codesample in the 4.2 docs. I think we should branch 4.2 into 4.3 and put changes in the new branch.

As to when should this happen? Before Wednesday obviously :-)

include API examples back in reference

Top Nav in docs does not link to main site correctly

Features, Documentation, Pricing etc. linked incorrectly.

`description` page field is sometimes too long for index pages

We need to introduce description_short in the front matter to handle this, I am going to prepare the code side, @r12s I'll leave the content part to you

Backticked text is larger than the text it is inline with

Instances of text with the class prettyprint and prettyprinted are noticably larger than the p text it is inline with.

http://localhost:4000/getting-started/basic-configuration/#aquicklookatmenuandmenubarcontrols

Suggest either bringing this class font size down 1pt, or bring the p sizing up one. My preference is to bring the p sizing up 1pt as it is difficult to read on large screens. I realize it is readable on smaller screens, especially retina displays, but data says most users are on large screens.

Write codesample plugin docs

This needs to be documented:
https://github.com/tinymce/tinymce-docs/blob/master/plugins/codesample.md

Basic Configuration Article - Toolbar Config

A few items here:

• We talk about 'core' controls. I don't know if we are trying to stress the term 'core', but it would be much clearer to the reader if we said these were the default controls.
• I don't know when we list the default controls using:

xx

In the rest of the doc we seem to only use that for display if real code snippets. What is contained here is not a code snippet. I find that confusing.

• We also don't define what these mean. Shouldn't we spell out what the controls do?
• Would it help to include screenshots of the default config in the document?

3.x compatibility plugin - missing link

In the 3.x compatibility plugin section:
The following instruction is lacking a link and/or instructions on where to locate the package. This should be corrected.

'Download the tinymce development package.'

Plugin Directory needs an index layout

Plugin directory needs an index page layout similar to /configure/

Add Angular to Integrations

This project is very active and should be listed under integrations:
https://github.com/angular-ui/ui-tinymce

Adding styling for toolbar and menubar associations in plugins

@kilianc we need to add css for any plugins that have toolbar and menubar control associations. Currently there is a comment in any plugins with these associations, so we need to resolve how we're going to write this in the markdown.

h2 and h3 not clearly differentiated

The font size and weight of h2 (md ##) and h3 (md ###) elements are quite similar, making it difficult to differentiate between titles in sections. This is an issue for context when reading lengthly sections that have many h2 and h3 heads.

Suggest increasing h2 font weight and slightly decreasing h2 font size.