README

Showdown是一个基于John Gruber原始工作的JavaScript Markdown转HTML转换器。Showdown可以用于客户端（在浏览器中）或服务器端（与NodeJs一起）。

实时演示

在这里查看实时演示 http://showdownjs.github.io/demo/

安装

下载tarball

您可以直接从发行版下载最新的发布tarball。

Bower

bower install showdown

npm（服务器端）

npm install showdown

CDN

您还可以使用几个可用的CDN之一

github CDN

  https://cdn.rawgit.com/showdownjs/showdown/<version tag>/dist/showdown.min.js

cdnjs

  https://cdnjs.cloudflare.com/ajax/libs/showdown/<version tag>/showdown.min.js

浏览器兼容性

Showdown已经成功与以下浏览器进行了测试

Firefox 1.5和2.0
Chrome 12.0
Internet Explorer 6和7
Safari 2.0.4
Opera 8.54和9.10
Netscape 8.1.2
Konqueror 3.5.4

理论上，Showdown将在支持ECMA 262第3版（JavaScript 1.5）的任何浏览器中工作。转换器本身甚至可能在非网络浏览器中工作，如Acrobat。不能保证。

Node兼容性

Showdown已经与node 0.8和0.10进行了测试。然而，它应该与较旧版本兼容，例如node 0.6。

旧版本

如果您正在寻找Showdown v<1.0.0，您可以在旧分支中找到它。

变更日志

您可以查看完整的变更日志

扩展文档

请参阅我们的wiki页面，以获取示例和更深入的文档。

快速示例

Node

var showdown  = require('showdown'),
    converter = new showdown.Converter(),
    text      = '#hello, markdown!',
    html      = converter.makeHtml(text);

浏览器

var converter = new showdown.Converter(),
    text      = '#hello, markdown!',
    html      = converter.makeHtml(text);

输出

这两个示例应该输出...

<h1 id="hellomarkdown">hello, markdown!</h1>

选项

您可以通过选项更改Showdown的一些默认行为。

设置选项

选项可以

全局设置

设置“全局”选项会影响Showdown的所有实例

showdown.setOption('optionKey', 'value');

本地设置

设置“本地”选项仅影响指定的Converter对象。本地选项可以通过以下方式设置

通过构造函数

var converter = new showdown.Converter({optionKey: 'value'});

通过setOption()方法

var converter = new showdown.Converter();
converter.setOption('optionKey', 'value');

获取选项

Showdown提供了2种方法（本地和全局）来检索之前设置的选项。

getOption()

// Global
var myOption = showdown.getOption('optionKey');

//Local
var myOption = converter.getOption('optionKey');

getOptions()

// Global
var showdownGlobalOptions = showdown.getOptions();

//Local
var thisConverterSpecificOptions = converter.getOptions();

检索默认选项

您可以使用以下方式获取Showdown的默认选项

var defaultOptions = showdown.getDefaultOptions();

有效选项

omitExtraWLInCodeBlocks: (布尔值) [默认false] 在代码块中省略尾随换行符。例如

这个
```
<code><pre>var foo = 'bar';
</pre></code>
```
变为这个
```
<code><pre>var foo = 'bar';</pre></code>
```
noHeaderId: (布尔值) [默认false] 禁用自动生成标题ID。将值设置为true会覆盖 prefixHeaderId
prefixHeaderId: (字符串/布尔值) [默认false] 将前缀添加到生成的标题ID中。传递字符串将把该字符串作为前缀添加到标题ID中。将值设置为true将添加通用的“section”前缀。

parseImgDimensions: (布尔值) [默认false] 启用从Markdown语法中设置图像尺寸的支持。示例

![foo](foo.jpg =100x80)     simple, assumes units are in px
![bar](bar.jpg =100x*)      sets the height to "auto"
![baz](baz.jpg =80%x5em)  Image with width of 80% and height of 5em

headerLevelStart: (整数) [默认1] 设置标题起始级别。例如，将此值设置为3表示
```
# foo
```
将被解析为
```
<h3>foo</h3>
```
simplifiedAutoLink: (布尔值) [默认false] 启用此功能将启用GFM自动链接样式。这意味着
```
some text www.google.com
```
将被解析为
```
<p>some text <a href="www.google.com">www.google.com</a>
```
```
中间单词下划线: (布尔值) [默认 false] 启用此选项将阻止 showdown 将单词中间的下划线解释为 <em> 和 <strong>，并将其视为字面下划线。

示例
```
some text with__underscores__in middle
```
将被解析为
```
<p>some text with__underscores__in middle</p>
```
删除线: (布尔值) [默认 false] 启用对删除线语法的支持。 ~~删除线~~ 转换为 <del>删除线</del>

表格: (布尔值) [默认 false] 启用对表格语法的支持。示例

| h1    |    h2   |      h3 |
|:------|:-------:|--------:|
| 100   | [a][1]  | ![b][2] |
| *foo* | **bar** | ~~baz~~ |

更多信息请参阅维基百科

表格表头ID: (布尔值) [默认 false] 启用时向表格表头标签添加 id 属性。
ghCodeBlocks: (布尔值) [默认 true] 启用对 GFM 代码块样式的支持。
任务列表:(布尔值) [默认 false] 启用对 GFM 任务列表的支持。示例
```
 - [x] This task is done
 - [ ] This is still pending
```
平滑实时预览: (布尔值) [默认 false] 防止由于输入不完整而在实时预览中产生奇怪的效果

CLI 工具

Showdown 还附带了一个命令行界面工具。有关更多信息，请参阅 CLI 维基页面

与 AngularJS 集成

ShowdownJS 项目还提供了通过“插件”无缝集成 AngularJS 的支持。有关更多信息，请访问 https://github.com/showdownjs/ngShowdown

与 TypeScript 集成

如果你正在使用 TypeScript，你可能想使用 DefinitelyTyped 中的类型

XSS 漏洞

Showdown 不对输入进行清理。这是按设计进行的，因为 markdown 依赖于它来正确解析某些功能到 HTML。然而，这意味着 XSS 注入的可能性相当大。

有关更多信息，请参阅维基文章 Markdown 的 XSS 漏洞（以及如何缓解它）

扩展

Showdown 允许通过扩展加载额外的功能。（你可以在这里找到已知 showdown 扩展的列表这里）

客户端扩展使用

<script src="showdown.js" />
<script src="twitter-extension.js" />

var converter = new showdown.Converter({ extensions: 'twitter' });

服务器端扩展使用

var showdown    = require('showdown'),
    myExtension = require('myExtension'),
    converter = new showdown.Converter({ extensions: ['myExtension'] });

测试

有一套测试套件可用，需要 node.js。一旦安装了 node，请从项目根目录运行以下命令以安装依赖项

npm install

安装完成后，可以从项目根目录运行测试

npm test

可以轻松地添加新的测试用例。创建一个以 .md 结尾的 markdown 文件，其中包含要测试的 markdown。创建一个同名的 .html 文件。当使用 mocha 执行测试时，它将自动进行测试。

贡献

如果你想贡献，请阅读以下快速指南。

想要一个新功能吗？

你可以通过提交问题来请求新功能。如果你想实现新功能，请随时提交拉取请求。

拉取请求（PR）

PR 是很棒的。然而，在提交你的拉取请求之前，请考虑以下指南

在 GitHub 上搜索与你的提交相关的已开放或已关闭的 PR。你不想重复工作。
在提交更改代码的 PR 时，请基于 master 创建一个新的 git 分支
```
git checkout -b my-fix-branch master
```
文档（即：README.md）更改可以直接针对 master 进行。
在提交之前运行完整的测试套件，并确保所有测试通过（显然 =P）。
尽量遵循我们的 编码风格规则。违反这些规则会阻止 PR 通过测试。
避免在同一个拉取请求中修复多个问题。更倾向于打开多个小的 PR 而不是一个难以审查的大 PR。
如果 PR 引入了一个新功能或修复了一个问题，请添加相应的测试用例。
我们使用提交说明来生成变更日志。如果您的提交消息遵循AngularJS Git 提交指南，这将非常有帮助。
如果我们建议修改，那么
- 进行必要的更新。
- 重新运行 Angular 测试套件以确保测试仍然通过。
- 将您的分支重新变基，并强制推送到您的 GitHub 仓库（这将更新您的拉取请求）
```
git rebase master -i
git push origin my-fix-branch -f
```
您的拉取请求合并后，您可以安全地删除您的分支。

如果您有时间为这个项目做出贡献，我们觉得有义务让您得到应有的认可。这些规则使我们能够更快地审查您的拉取请求，并将给您在 GitHub 个人资料中适当的认可。感谢您提前的贡献！

加入团队

我们正在寻找成员来帮助维护 Showdown。请参阅此问题以表达兴趣或对此说明发表评论。

致谢

完整致谢名单请见https://github.com/showdownjs/showdown/blob/master/CREDITS.md

Showdown 由以下机构提供支持

webutilz / showdown

维护者

详细信息