tiny-markdown-editor v0.1.12

tiny-markdown-editor

TinyMDE: A tiny, low-dependency(1) embeddable HTML/JavaScript Markdown editor.

(1): TinyMDE's runtime only depends on core-js for polyfills to support older browsers.

Visit the demo page to see TinyMDE in action.

Overview

TinyMDE is an in-browser markdown editor that allows editing Markdown files with in-line formatting previews (bold, italic, headings, code etc.) as well as a toolbar with familiar point-and-click or keyboard shortcut interaction.

TinyMDE can be used as a drop-in text area replacement.

Motivation

TinyMDE was motivated by wanting to improve on EasyMDE which is extremely flexible but had two shortcomings:

• EasyMDE depends on Code Mirror for editing and formatting. CodeMirror is a full fledged and customizable in-browser code editor, and has a price: EasyMDE's JS file is 280kb in size. TinyMDE is less than 70kb (less than a quarter of EasyMDE's size), the "tiny" version without the toolbar even below 60kb!
• CodeMirror doesn't work well on mobile, at least not for writing prose: mobile phone OS auto-correction functionality, which many people rely on to quickly type on mobile, is not supported by CodeMirror.

Install TinyMDE

You can install TinyMDE from NPM (e.g., if you want to use it in a bundled JS application using Webpack or Rollup), use a hosted version, or self-host the JavaScript and CSS files.

Install TinyMDE from NPM

Install the tiny-markdown-editor package from NPM:

npm install --save tiny-markdown-editor

Then, in your JavaScript file, simply import the package like this:

const TinyMDE = require('tiny-markdown-editor');
var tinyMDE = new TinyMDE.Editor({element: 'editor'});

Bundle the JavaScript with your favorite bundler like Webpack or Rollup to ensure the TinyMDE code gets included in the shipped JavaScript file.

Please note: If you go down the NPM package route, you will also need to make sure to style the components. After installing TinyMDE from NPM, you will find a CSS file tiny-mde.css you can use as a base in the directory node_modules/tiny-markdown-editor/dist.

Hosted version

You can simply include the JavaScript and CSS files from Unpkg on your website, using the following code:

<script src="https://unpkg.com/tiny-markdown-editor/dist/tiny-mde.min.js"></script>
<link
  rel="stylesheet"
  type="text/css"
  href="https://unpkg.com/tiny-markdown-editor/dist/tiny-mde.min.css"
/>

Self-host

To self-host TinyMDE, follow these steps:

• Download and build TinyMDE. Alternatively, download the newest release and unpack the archive.
• Copy the output JS and CSS files tiny-mde.min.js and tiny-mde.min.css from the dist directory to your website's directory.
• Include these files on your website:

  <script src="tiny-mde.min.js"></script>
  <link rel="stylesheet" type="text/css" href="tiny-mde.min.css" />

Creating an editor and toolbar on your page

Simple creation

To create a simple editor as child of an HTML div element with the ID editor, use the following HTML / JS code:

<div id="editor"></div>
<script type="text/javascript">
  var tinyMDE = new TinyMDE.Editor({ element: "editor" });
</script>

Command bar creation

To create a toolbar (command bar) along with the editor, create another container div (here called toolbar), and instantiate editor and toolbar as follows:

<div id="toolbar"></div>
<div id="editor"></div>
<script type="text/javascript">
  var tinyMDE = new TinyMDE.Editor({ element: "editor" });
  var commandBar = new TinyMDE.CommandBar({
    element: "toolbar",
    editor: tinyMDE,
  });
</script>

Creation from a textarea

TinyMDE can be used as a drop-in textarea replacement. This means that when TinyMDE is passed a textarea, the editor will act as if the user is directly editing the textarea: The editor is initialized with the content of the textarea, and changing text in the editor changes the textarea's content. The easiest code to do so is as follows:

<div class="txtcontainer">
  <textarea id="txt">This is some **Markdown** formatted text</textarea>
</div>
<script type="text/javascript">
  var tinyMDE = new TinyMDE.Editor({ textarea: "txt" });
</script>

Please note:

• The editor doesn't quite replace the textarea. The textarea just gets hidden, and the editor content is mirrored in the textarea. If you programmatically change the contents of the textarea, the editor would get out of sync.
• The editor element will be inserted in the DOM as a sibling of the textarea element. In order to size and format the editor element properly, apply styles to the parent element of the textarea (in the example above, div.txtcontainer).

Configure TinyMDE

Editor constructor parameters

TinyMDE.Editor takes as argument a key-value object with the following possible attributes:

If neither element not textarea are given, the editor element will be created as the last child element of the body element (probably not what you want in most cases, so you probably want to pass at least one of element or textarea).

If neither content nor textarea are given, the content of the editor is initialized with a placeholder text (# Hello TinyMDE!\nEdit **here**). This is probably not what you want, so you probably want to pass at least one of content or textarea.

CommandBar constructor parameters

TinyMDE.Editor takes as argument a key-value object with the following possible attributes:

Customizing commands

In order to customize the commands shown on the command bar, pass an array to the commands attribute. Each of the entries of the array defines one command bar element (button or separator), left to right. Each of the entries of the commands array can be one of the following:

• A string with the content | (vertical pipe), which will create a separator line.
• A string with one of the command identifiers bold, italic, strikethrough, code, h1, h2, ul, ol, blockquote, hr, insertLink, or insertImage, which will create the default button for that command
• A key-value object to create a customized or custom button.

If an entry of the commands array is an object, you can either customize one of the existing commands (e.g., use a different icon or keyboard shortcut for the bold command), or use a completely custom command. An object entry of the commands array can contain the following attributes:

The default array of commands is as follows: ['bold', 'italic', 'strikethrough', '|', 'code', '|', 'h1', 'h2', '|', 'ul', 'ol', '|', 'blockquote', 'hr', '|', 'insertLink', 'insertImage'].

Editor methods

Here are some methods of the Editor object that might be useful in general interaction or custom CommandBar commands:

Event listeners

There are two event listener types that can be registered on the editor: change and selection.

change event

A change event is fired any time the content of the editor changes. The event object passed to the listener function contains the following properties:

selection event

A selection event is fired any time the selection within the editor changes. The event object passed to the listener function contains the following properties:

Styling TinyMDE

In order to style TinyMDE, edit the CSS file. You can see the classes that can be assigned styles within the file. For a bit more detail about the classes, read on.

Editor styling

There are some generally interesting CSS classes that can be formatted. Most of them start with TM, short for TinyMDE.

• TinyMDE is the editor element.
• TMMark is any markup. Any element with the class TMMark will also have another class called TMMark_*, where * is replaced by the class name of the respective block or inline style. For example, in a H1 line with the content # Heading 1, the # is contained in an element with the classes TMMark TMMark_TMH1.
• TMInlineFormatted contains text that is inline formatted.

The following classes denote Markdown blocks: TMPara, TMBlankLine, TMH1, TMH2, TMH3, TMH4, TMH5, TMH6, TMBlockquote, TMCodeFenceBacktickOpen, TMFencedCodeBacktick, TMCodeFenceBacktickClose, TMCodeFenceTildeOpen, TMFencedCodeTilde, TMCodeFenceTildeClose, TMSetextH1, TMSetextH1Marker, TMSetextH2, TMSetextH2Marker, TMHR, TMUL, TMOL, TMIndentedCode, TMLinkReferenceDefinition, TMHTMLBlock.

The following classes denote Markdown inline formatted stretches of text: TMCode, TMAutolink, TMHTML, TMStrong, TMEm, TMStrikethrough, TMImage, TMLink, (TMLinkLabel (also marked as TMLinkLabel_Valid or TMLinkLabel_Invalid depending on whether or not the label references a valid reference), TMLinkDestination, TMLinkTitle, TMImageDestination, TMImageTitle.

CommandBar styling

The main toolbar element has the class TMCommandBar. Buttons have the class TMCommandButton, with an additional class of TMCommandButton_Active, TMCommandButton_Inactive, or TMCommandButton_Disabled, depending on the state of the respective command. Divider elements have the class TMCommandDivider.

Build TinyMDE

Building TinyMDE is pretty straight forward:

1. Clone this repository:

   git clone git@github.com:jefago/tiny-markdown-editor.git

2. In the repository directory, run the build script:

   npm run build

The build output is in the dist directory. You will find the following files there:

• tiny-mde.css and tiny-mde.min.css: CSS files to style the editor. These can be edited at will to make the editor look like you want to. tiny-mde.min.css has the same content as tiny-mde.css, it's just minified. You will only need to use one of the files on your page. If you want to edit the CSS file, it's easier to edit tiny-mde.css and then minify the edited version.
• tiny-mde.js: Debug version of the editor. The JS file is not minified and contains a sourcemap. It is not recommended to use this in production settings, since the file is large.
• tiny-mde.min.js: Minified JS file for most use cases. Simply copy this to your project to use it.
• tiny-mde.tiny.js: Minified and stripped-down JS file. Contains only the editor itself, not the toolbar.