8fold-simplemde 中文文档教程

Question

这个分支是出于必要而启动的。 需要明确的是，8fold 并没有试图劫持主项目。

SimpleMDE（以及许多其他包）依赖于 Marked，其中有一个漏洞已被纠正但未发布，核心团队似乎很少沟通（我希望主项目的人都没事）。 建立这个项目是为了允许 SimpleMDE 使用 8fold 组织下的替代 Marked 包，其中包括 XSS 修复。 所有的 PR 都应该提交到这个 repo，这样我们就可以在此处执行合并到 master 并将它们提交到主要的 SimpleMDE 项目。

SimpleMDE - Markdown Editor

一个用于编写漂亮且易于理解的 Markdown 的嵌入式 JavaScript 文本区域替代品。 WYSIWYG 式编辑器允许对 Markdown 经验不足的用户使用熟悉的工具栏按钮和快捷方式。 此外，语法在编辑时呈现，以清楚地显示预期结果。 标题更大，强调的单词用斜体，链接用下划线等等。SimpleMDE 是第一批同时具有内置自动保存和拼写检查功能的编辑器之一。

演示

Why not a WYSIWYG editor or pure Markdown?

生成 HTML 的所见即所得编辑器通常很复杂且存在错误。 Markdown 以多种方式解决了这个问题，而且 Markdown 可以在比 HTML 更多的平台上原生呈现。 但是，Markdown 并不是普通用户会熟悉的语法，在编辑时视觉上也不是很清晰。 换句话说，对于不熟悉的用户，他们编写的语法在他们单击预览按钮之前将毫无意义。 SimpleMDE 旨在为不太熟悉或刚刚学习 Markdown 语法的非技术用户弥合这一差距。

Install

通过 npm。

npm install simplemde --save

通过 bower。

bower install simplemde --save

通过 jsDelivr。 请注意，jsDelivr 可能需要几天时间才能更新到最新版本。

<link rel="stylesheet" href="https://cdn.jsdelivr.net/simplemde/latest/simplemde.min.css">
<script src="https://cdn.jsdelivr.net/simplemde/latest/simplemde.min.js"></script>

Quick start

安装后，在页面的第一个文本区域加载 SimpleMDE

<script>
var simplemde = new SimpleMDE();
</script>

Using a specific textarea

纯 JavaScript 方法

<script>
var simplemde = new SimpleMDE({ element: document.getElementById("MyID") });
</script>

jQuery 方法

<script>
var simplemde = new SimpleMDE({ element: $("#MyID")[0] });
</script>

Get/set the content

simplemde.value();

simplemde.value("This text will appear in the editor");

Configuration

• autoDownloadFontAwesome: If set to true, force downloads Font Awesome (used for icons). If set to false, prevents downloading. Defaults to undefined, which will intelligently check whether Font Awesome has already been included, then download accordingly.
• autofocus: If set to true, autofocuses the editor. Defaults to false.
• autosave: Saves the text that's being written and will load it back in the future. It will forget the text when the form it's contained in is submitted.
• enabled: If set to true, autosave the text. Defaults to false.
• delay: Delay between saves, in milliseconds. Defaults to 10000 (10s).
• uniqueId: You must set a unique string identifier so that SimpleMDE can autosave. Something that separates this from other instances of SimpleMDE elsewhere on your website.
• blockStyles: Customize how certain buttons that style blocks of text behave.
• bold Can be set to ** or __. Defaults to **.
• code Can be set to ``` or ~~~. Defaults to ```.
• italic Can be set to * or _. Defaults to *.
• element: The DOM element for the textarea to use. Defaults to the first textarea on the page.
• forceSync: If set to true, force text changes made in SimpleMDE to be immediately stored in original textarea. Defaults to false.
• hideIcons: An array of icon names to hide. Can be used to hide specific icons shown by default without completely customizing the toolbar.
• indentWithTabs: If set to false, indent using spaces instead of tabs. Defaults to true.
• initialValue: If set, will customize the initial value of the editor.
• insertTexts: Customize how certain buttons that insert text behave. Takes an array with two elements. The first element will be the text inserted before the cursor or highlight, and the second element will be inserted after. For example, this is the default link value: ["[", "](http://)"].
• horizontalRule
• image
• link
• table
• lineWrapping: If set to false, disable line wrapping. Defaults to true.
• parsingConfig: Adjust settings for parsing the Markdown during editing (not previewing).
• allowAtxHeaderWithoutSpace: If set to true, will render headers without a space after the #. Defaults to false.
• strikethrough: If set to false, will not process GFM strikethrough syntax. Defaults to true.
• underscoresBreakWords: If set to true, let underscores be a delimiter for separating words. Defaults to false.
• placeholder: Custom placeholder that should be displayed
• previewRender: Custom function for parsing the plaintext Markdown and returning HTML. Used when user previews.
• promptURLs: If set to true, a JS alert window appears asking for the link or image URL. Defaults to false.
• renderingConfig: Adjust settings for parsing the Markdown during previewing (not editing).
• singleLineBreaks: If set to false, disable parsing GFM single line breaks. Defaults to true.
• codeSyntaxHighlighting: If set to true, will highlight using highlight.js. Defaults to false. To use this feature you must include highlight.js on your page. For example, include the script and the CSS files like:
  <script src="https://cdn.jsdelivr.net/highlight.js/latest/highlight.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/highlight.js/latest/styles/github.min.css">
• shortcuts: Keyboard shortcuts associated with this instance. Defaults to the array of shortcuts.
• showIcons: An array of icon names to show. Can be used to show specific icons hidden by default without completely customizing the toolbar.
• spellChecker: If set to false, disable the spell checker. Defaults to true.
• status: If set to false, hide the status bar. Defaults to the array of built-in status bar items.
• Optionally, you can set an array of status bar items to include, and in what order. You can even define your own custom status bar items.
• styleSelectedText: If set to false, remove the CodeMirror-selectedtext class from selected lines. Defaults to true.
• tabSize: If set, customize the tab size. Defaults to 2.
• toolbar: If set to false, hide the toolbar. Defaults to the array of icons.
• toolbarTips: If set to false, disable toolbar button tips. Defaults to true.

// Most options demonstrate the non-default behavior
var simplemde = new SimpleMDE({
    autofocus: true,
    autosave: {
        enabled: true,
        uniqueId: "MyUniqueID",
        delay: 1000,
    },
    blockStyles: {
        bold: "__",
        italic: "_"
    },
    element: document.getElementById("MyID"),
    forceSync: true,
    hideIcons: ["guide", "heading"],
    indentWithTabs: false,
    initialValue: "Hello world!",
    insertTexts: {
        horizontalRule: ["", "\n\n-----\n\n"],
        image: ["![](http://", ")"],
        link: ["[", "](http://)"],
        table: ["", "\n\n| Column 1 | Column 2 | Column 3 |\n| -------- | -------- | -------- |\n| Text     | Text      | Text     |\n\n"],
    },
    lineWrapping: false,
    parsingConfig: {
        allowAtxHeaderWithoutSpace: true,
        strikethrough: false,
        underscoresBreakWords: true,
    },
    placeholder: "Type here...",
    previewRender: function(plainText) {
        return customMarkdownParser(plainText); // Returns HTML from a custom parser
    },
    previewRender: function(plainText, preview) { // Async method
        setTimeout(function(){
            preview.innerHTML = customMarkdownParser(plainText);
        }, 250);

        return "Loading...";
    },
    promptURLs: true,
    renderingConfig: {
        singleLineBreaks: false,
        codeSyntaxHighlighting: true,
    },
    shortcuts: {
        drawTable: "Cmd-Alt-T"
    },
    showIcons: ["code", "table"],
    spellChecker: false,
    status: false,
    status: ["autosave", "lines", "words", "cursor"], // Optional usage
    status: ["autosave", "lines", "words", "cursor", {
        className: "keystrokes",
        defaultValue: function(el) {
            this.keystrokes = 0;
            el.innerHTML = "0 Keystrokes";
        },
        onUpdate: function(el) {
            el.innerHTML = ++this.keystrokes + " Keystrokes";
        }
    }], // Another optional usage, with a custom status bar item that counts keystrokes
    styleSelectedText: false,
    tabSize: 4,
    toolbar: false,
    toolbarTips: false,
});

Toolbar icons

下面是内置的工具栏图标（仅其中一些是默认启用的），可以根据需要重新组织。 “名称”是图标的名称，在 JS 中引用。 “Action”是一个函数或一个要打开的 URL。 “类别”是赋予图标的类别。 “工具提示”是通过 title="" 属性显示的小工具提示。 请注意，快捷方式提示会自动添加并反映指定的操作，如果它有分配给它的键绑定（即 action 的值设置为 bold 和 tooltip 设置为 Bold，用户将看到的最终文本将是“Bold (Ctrl-B)”）。

此外，您可以通过将 "|" 添加到工具栏数组来在任何图标之间添加分隔符。

Name	Action	Tooltip Class
bold	toggleBold	Bold fa fa-bold
italic	toggleItalic	Italic fa fa-italic
strikethrough	toggleStrikethrough	Strikethrough fa fa-strikethrough
heading	toggleHeadingSmaller	Heading fa fa-header
heading-smaller	toggleHeadingSmaller	Smaller Heading fa fa-header
heading-bigger	toggleHeadingBigger	Bigger Heading fa fa-lg fa-header
heading-1	toggleHeading1	Big Heading fa fa-header fa-header-x fa-header-1
heading-2	toggleHeading2	Medium Heading fa fa-header fa-header-x fa-header-2
heading-3	toggleHeading3	Small Heading fa fa-header fa-header-x fa-header-3
code	toggleCodeBlock	Code fa fa-code
quote	toggleBlockquote	Quote fa fa-quote-left
unordered-list	toggleUnorderedList	Generic List fa fa-list-ul
ordered-list	toggleOrderedList	Numbered List fa fa-list-ol
clean-block	cleanBlock	Clean block fa fa-eraser fa-clean-block
link	drawLink	Create Link fa fa-link
image	drawImage	Insert Image fa fa-picture-o
table	drawTable	Insert Table fa fa-table
horizontal-rule	drawHorizontalRule	Insert Horizontal Line fa fa-minus
preview	togglePreview	Toggle Preview fa fa-eye no-disable
side-by-side	toggleSideBySide	Toggle Side by Side fa fa-columns no-disable no-mobile
fullscreen	toggleFullScreen	Toggle Fullscreen fa fa-arrows-alt no-disable no-mobile
guide	This link	Markdown Guide fa fa-question-circle

使用 toolbar 选项自定义工具栏，例如：

// Customize only the order of existing buttons
var simplemde = new SimpleMDE({
    toolbar: ["bold", "italic", "heading", "|", "quote"],
});

// Customize all information and/or add your own icons
var simplemde = new SimpleMDE({
    toolbar: [{
            name: "bold",
            action: SimpleMDE.toggleBold,
            className: "fa fa-bold",
            title: "Bold",
        },
        {
            name: "custom",
            action: function customFunction(editor){
                // Add your own code
            },
            className: "fa fa-star",
            title: "Custom Button",
        },
        "|", // Separator
        ...
    ],
});

Keyboard shortcuts

SimpleMDE 带有一组预定义的键盘快捷键，但可以使用配置选项更改它们。 默认的列表如下：

Shortcut	Action
Cmd-'	"toggleBlockquote"
Cmd-B	"toggleBold"
Cmd-E	"cleanBlock"
Cmd-H	"toggleHeadingSmaller"
Cmd-I	"toggleItalic"
Cmd-K	"drawLink"
Cmd-L	"toggleUnorderedList"
Cmd-P	"togglePreview"
Cmd-Alt-C	"toggleCodeBlock"
Cmd-Alt-I	"drawImage"
Cmd-Alt-L	"toggleOrderedList"
Shift-Cmd-H	"toggleHeadingBigger"
F9	"toggleSideBySide"
F11	"toggleFullScreen"

这里是您如何更改一些，同时保持其他不变：

var simplemde = new SimpleMDE({
    shortcuts: {
        "toggleOrderedList": "Ctrl-Alt-K", // alter the shortcut for toggleOrderedList
        "toggleCodeBlock": null, // unbind Ctrl-Alt-C
        "drawTable": "Cmd-Alt-T" // bind Cmd-Alt-T to drawTable action, which doesn't come with a default shortcut
    }
});

快捷方式在平台之间自动转换。 如果您将快捷方式定义为“Cmd-B”，则在 PC 上该快捷方式将更改为“Ctrl-B”。 相反，定义为“Ctrl-B”的快捷方式对于 Mac 用户将变为“Cmd-B”。

可绑定的操作列表与可用于工具栏按钮 的内置操作列表相同。

Height

要更改最小高度（在它开始自动增长之前）：

.CodeMirror, .CodeMirror-scroll {
    min-height: 200px;
}

或者，您可以保持高度不变：

.CodeMirror {
    height: 300px;
}

Event handling

您可以捕获以下事件列表：https://codemirror.net/doc/manual.html#events

var simplemde = new SimpleMDE();
simplemde.codemirror.on("change", function(){
    console.log(simplemde.value());
});

Removing SimpleMDE from textarea

您可以恢复通过调用 toTextArea 方法到初始文本区域。 请注意，这会清除与其关联的自动保存（如果启用）。 textarea 将保留来自已销毁的 SimpleMDE 实例的任何文本。

var simplemde = new SimpleMDE();
...
simplemde.toTextArea();
simplemde = null;

Useful methods

在使用 SimpleMDE 进行开发时，可能会使用以下不言自明的方法。

var simplemde = new SimpleMDE();
simplemde.isPreviewActive(); // returns boolean
simplemde.isSideBySideActive(); // returns boolean
simplemde.isFullscreenActive(); // returns boolean
simplemde.clearAutosavedValue(); // no returned value

How it works

SimpleMDE 开始是 lepture 的编辑器项目的改进，但现在有了自己的身份。 它与 CodeMirror 捆绑在一起，并依赖于 Font Awesome .

CodeMirror 是该项目的支柱，它在编写时解析大部分 Markdown 语法。 这允许我们向正在编写的 Markdown 添加样式。 此外，工具栏和状态栏已分别添加到顶部和底部。 预览由 Marked 使用 GFM 呈现。