From 4aa391fc9f0da6029a7c3eec4b29b8fa100bd0a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=B5=9C=EA=B7=9C=EC=9A=B0/FE=EA=B0=9C=EB=B0=9C=EB=9E=A9/?= =?UTF-8?q?NE?= Date: Thu, 28 Dec 2017 18:45:33 +0900 Subject: [PATCH] docs: update readme for 1.0 (fix #1026, #1055) * docs: update readme for 1.0 (fix #1026) * docs: apply review (fix #1055) --- README.md | 237 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 185 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index de2b161fab..7d713f732c 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,185 @@ -## ![toast ui editor](https://cloud.githubusercontent.com/assets/389021/16107646/9729e556-33d8-11e6-933f-5b09fa3a53bb.png) -
-The ToastUI Editor is a two-way editor based on Markdown. -You can choose and use WYSIWYG and Markdown as needed. -And if you are in need, you can switch the editing mode (WYSIWYG ↔ Markdown) while you are writing it fluidly. - -## Features -* Input & output with GFM : All documents are exported by "Github Flavored Markdown" format even if it has written in WYSIWYG mode. -* Quick & Easy mode switching : Switch editing mode WYSIWYG and Markdown anytime you need. -* Live preview : Always display current Markdown document's HTML preview. -* Extensible : You can extend features by integrated API & Extension. -* Auto-Scroll : A scroll automatically follows cursor position during editing so that you can see a Markdown preview in real time. -* Text color : You can set the text color using inline html tag. - -## DEMO - -You can try a demo at [nhnent.github.io/tui.editor](http://nhnent.github.io/tui.editor/) - -## Screenshots - -### Markdown Mode -![Markdown Mode](https://cloud.githubusercontent.com/assets/389021/16108210/d55d4576-33dc-11e6-943a-66c29ae1ff4d.png) - -### Wysiwyg Mode -![WYsiwyg Mode](https://cloud.githubusercontent.com/assets/389021/16108214/d7ac03d0-33dc-11e6-9ab6-06e7734a7fb1.png) - -## Documentation -* **Getting Started** : https://github.com/nhnent/tui.editor/wiki/Getting-Started -* **API** : https://nhnent.github.io/tui.editor/api/latest - -## Dependency -* codemirror -* squire -* jquery 2.1.3 -* tui-code-snippet -* highlightjs -* markdown-it -* toMark - -## Test environment -* PC - * IE10~11 - * Chrome - * Firefox - -## Download/Install -* Bower - * Latest version: `bower install https://github.com/nhnent/tui.editor.git` - * Specific version: `bower install https://github.com/nhnent/tui.editor.git#[tagName]` - -## License -This software is licensed under the [MIT License](https://github.com/nhnent/tui.editor/blob/master/LICENSE). +# ![logo](https://cloud.githubusercontent.com/assets/389021/16107646/9729e556-33d8-11e6-933f-5b09fa3a53bb.png) +> GFM Markdown Wysiwyg Editor - Productive and Extensible + +[![github version](https://img.shields.io/github/release/nhnent/tui.editor.svg)](https://github.com/nhnent/tui.editor/releases/latest) [![npm version](https://img.shields.io/npm/v/tui-editor.svg)](https://www.npmjs.com/package/tui-editor) [![bower version](https://img.shields.io/bower/v/tui-editor.svg)](https://github.com/nhnent/tui.editor/releases/latest) [![license](https://img.shields.io/github/license/nhnent/tui.editor.svg)](https://github.com/nhnent/tui.editor/blob/production/LICENSE) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg)](https://github.com/nhnent/tui.editor/pulls) [![code with hearth by NHN ent.](https://img.shields.io/badge/%3C%2F%3E%20with%20%E2%99%A5%20by-NHN%20Ent.-brightgreen.svg)](https://github.com/nhnent) + +

+ +## 🚩 Table of Contents +- [ Standard and Extensible](#-standard-and-extensible) + - [CommonMark + GFM Specifications](#commonmark--gfm-specifications) + - [Powerful Extensions](#powerful-extensions) +- [🎨 Features](#-features) + - [Productive Markdown mode](#productive-markdown-mode) + - [Easy Wysiwig mode](#easy-wysiwig-mode) + - [And more](#and-more) +- [💾 Install](#-install) + - [using npm](#using-npm) + - [using bower](#using-bower) + - [Download](#download) +- [🔨 Usage](#-usage) + - [Editor](#editor) + - [HTML](#html) + - [javascript](#javascript) + - [options](#options) + - [Viewer](#viewer) +- [📙 Docs](#-docs) +- [🐾 Examples](#-examples) +- [🌏 Browser Support](#-browser-support) +- [📜 License](#-license) + +## Standard and Extensible +![standard and extensible image](https://user-images.githubusercontent.com/1215767/34353629-95b58da0-ea6c-11e7-859b-df5e990dd157.png) + +### CommonMark + GFM Specifications + +Today *CommonMark* is the de-facto *Markdown* standard. And *GFM (GitHub Flavored Markdown)* is another popular specification based on *CommonMark* maintained by *GitHub* which is known as the biggest *Markdown* user. +**ToastUI Editor** respects [*CommonMark*](http://commonmark.org/) and [*GFM*](https://github.github.com/gfm/) specifications. Write documents with easy and productive tools provided by **ToastUI Editor**. You can open this document wherever the specifications are supported. + +### Powerful Extensions +*CommonMark* and *GFM* are great, but we often face requirements beyond the specifications. The **ToastUI Editor** comes with powerful **Extensions** in compliance with the *Markdown* syntax. And it also provides APIs so you can develop your own extensions. Please check [here](https://github.com/nhnent/tui.editor/wiki/Extensions) to learn about **Extensions**. + +Here are some of extensions which you can start right on. + +* **Color picker**: [ColorPicker](https://github.com/nhnent/tui.color-picker) provides an easy way to color text with a GUI tool box +* **Chart code block**: A Code block marked as a 'chart' will render [charts](https://github.com/nhnent/tui.chart) +* **UML code block**: A Code block marked as an 'uml' will render [UML diagrams](http://plantuml.com/screenshot) +* **Table merge**: You can merge columns and rows in tables + + [Here](https://github.com/nhnent/tui.editor/wiki/Extensions) you can find and more + +## 🎨 Features +**ToastUI Editor** provides **Markdown mode** and **Wysiwyg mode**. + +Someone may like the productivity of *Markdown*, but the other can be looking for a way to make it easier to edit. The **ToastUI Editor** can be the coordinator of both. It offers **Markdown mode** and **Wysiwyg mode**, those can be switched at any time during writing content. Work together conveniently in one document. + +### Productive Markdown mode +![markdown image](https://user-images.githubusercontent.com/1215767/34354737-b98a0736-ea73-11e7-8375-d4c83b8894d8.png) +* **Live Preview**: Edit Markdown while keeping eye on the rendered HTML. Your edits will be applied immediately +* **Scrolling Sync**: Synchronous scrolling between Markdown and Preview. You don't need to scroll those separately +* **Auto indent**: The cursor will always be where you want to be +* **Syntax highlight**: You can check broken Markdown syntax immediately + +### Easy Wysiwig mode +![wysiwyg image](https://user-images.githubusercontent.com/1215767/34354831-5f04c7e6-ea74-11e7-9664-97f71c4fee6e.png) +* **Copy and paste**: Paste anything from browser, screenshot, excel, powerpoint etc +* **Codeblock editor**: Highlight 170+ languages with full size code editor +* **Table**: Hate the Markdown table? You can do everything with a mouse + +### And more +* **i18n**: English, Dutch, Korean, Japanese, Chinese + language you extend. +* **Viewer**: Renders Markdown content with extensions + + +## 💾 Install + +### using npm +```sh +npm install --save tui-editor +``` + +### using bower +```sh +bower install --save tui-editor +``` + +### from downloading +* [Download bundle files from `dist` directory](https://github.com/nhnent/tui.editor/tree/production/dist) +* [Download all sources for each version from release](https://github.com/nhnent/tui.editor/releases) + +## 🔨 Usage +Below codes are for *npm*. If you are using *bower* please see [Getting started with bower](https://github.com/nhnent/tui.editor/wiki/Getting-started-with-bower). + +### Editor + +#### HTML +Place a `
` where you want ToastUI Editor rendered. +```html + +... +
+... + +``` + +#### javascript +Initialize Editor class with given element to make an Editor. +```javascript +var Editor = require('tui-editor'); +... +var editor = new Editor({ + el: document.querySelector('#editSection'), + initialEditType: 'markdown', + previewStyle: 'vertical', + height: '300px' +}); +``` + +or you can use jquery plugin. +```javascript +$('#editSection').tuiEditor({ + initialEditType: 'markdown', + previewStyle: 'vertical', + height: '300px' +}); +``` + +#### options +* **height**: Height in string or auto ex) `300px` | `auto` +* **initialValue**: Initial value. Set Markdown string +* **initialEditType**: Initial type to show `markdown` | `wysiwyg` +* **previewType**: Preview style of Markdown mode `tab` | `vertical` + +Find out more options [here](https://nhnent.github.io/tui.editor/api/latest/ToastUIEditor.html#ToastUIEditor) + +### Viewer +**ToastUI Editor** provides a **Viewer** in case you want to show *Markdown* content without loading the editor. The **Viewer** has much **lighter** than the editor. + +```javascript +var Viewer = require('tui-editor/dist/tui-editor-Viewer'); +... +var editor = new Viewer({ + el: document.querySelector('#viewerSection'), + height: '500px', + initialValue: '# content to be rendered' +}); +... +``` + +Be careful not to load both the editor and the viewer. Since the editor already includes the viewer function, you can initialize editor by calling [Editor.factory()](https://nhnent.github.io/tui.editor/api/latest/ToastUIEditor.html#.factory) with `viewer` option `true` value to make the editor a viewer. You can also call [getHTML()](https://nhnent.github.io/tui.editor/api/latest/ToastUIEditor.html#getHtml) to get rendered *HTML* string. + +```javascript +var Editor = require('tui-editor'); +... +var editor = Editor.factory({ + el: document.querySelector('#viewerSection'), + viewer: true, + height: '500px', + initialValue: '# content to be rendered' +}); +... +``` + +**ToastUI Editor** respects *CommonMark* and *GFM*. So any *Markdown* renderer including [markdownit](https://github.com/markdown-it/markdown-it) can handle the content it made. You can use any of those renderer without **Viewer** if you want. + + +## 📙 Docs +* [Getting Started](https://github.com/nhnent/tui.editor/wiki/Getting-Started) +* [APIs](https://nhnent.github.io/tui.editor/api/latest/) +* [Getting started with bower](https://github.com/nhnent/tui.editor/wiki/Getting-started-with-bower) + +## 🐾 Examples +* [editor basic](https://nhnent.github.io/tui.editor/api/latest/tutorial-example01-basic.html) +* [viewer basic](https://nhnent.github.io/tui.editor/api/latest/tutorial-example02-viewer-basic.html) +* [jQuery plugin](https://nhnent.github.io/tui.editor/api/latest/tutorial-example03-jquery.html) +* [uml plugin](https://nhnent.github.io/tui.editor/api/latest/tutorial-example08-uml.html) +* [chart plugin](https://nhnent.github.io/tui.editor/api/latest/tutorial-example11-chart.html) +* [more examples in demo directory](https://nhnent.github.io/tui.editor/api/latest/tutorial-example00-demo.html) + +## 🌏 Browser Support +|IE / Edge Internet Explorer | IE / Edge Edge | Firefox Firefox | Chrome Chrome | Safari Safari | +| :---------: | :---------: | :---------: | :---------: | :---------: | +| 10+ | Yes | Yes | Yes | Yes | + +## 📜 License +This software is licensed under the [MIT](https://github.com/nhnent/tui.editor/blob/production/LICENSE) © [NHN Ent.](https://github.com/nhnent)