From da09ee8565b95ca80249542921a78fb1933a598d Mon Sep 17 00:00:00 2001 From: Antonio Date: Sat, 14 May 2022 01:02:26 +0300 Subject: [PATCH] docs: update README to get rid of overlapping info from main docs --- CREDITS.md | 53 ------ README.md | 546 ++++------------------------------------------------- 2 files changed, 41 insertions(+), 558 deletions(-) delete mode 100644 CREDITS.md diff --git a/CREDITS.md b/CREDITS.md deleted file mode 100644 index 2aba05c..0000000 --- a/CREDITS.md +++ /dev/null @@ -1,53 +0,0 @@ -Credits -======= - - - Showdown v2 - * [Estevão Santos](https://github.com/tivie) - * [SyntaxRules](https://github.com/SyntaxRules) - - - Showdown v1 - * [Estevão Santos](https://github.com/tivie) - * [Pascal Deschênes](https://github.com/pdeschen) - - - Showdown v0 - * [Corey Innis](http://github.com/coreyti):
- Original GitHub project maintainer - * [Remy Sharp](https://github.com/remy/):
- CommonJS-compatibility and more - * [Konstantin Käfer](https://github.com/kkaefer/):
- CommonJS packaging - * [Roger Braun](https://github.com/rogerbraun):
- Github-style code blocks - * [Dominic Tarr](https://github.com/dominictarr):
- Documentation - * [Cat Chen](https://github.com/CatChen):
- Export fix - * [Titus Stone](https://github.com/tstone):
- Mocha tests, extension mechanism, and bug fixes - * [Rob Sutherland](https://github.com/roberocity):
- The idea that lead to extensions - * [Pavel Lang](https://github.com/langpavel):
- Code cleanup - * [Ben Combee](https://github.com/unwiredben):
- Regex optimization - * [Adam Backstrom](https://github.com/abackstrom):
- WebKit bugfix - * [Pascal Deschênes](https://github.com/pdeschen):
- Grunt support, extension fixes + additions, packaging improvements, documentation - * [Estevão Santos](https://github.com/tivie)
- Bug fixing and late maintainer - * [Hannah Wolfe](https://github.com/ErisDS)
- Bug fixes - * [Alexandre Courtiol](https://github.com/acourtiol)
- Bug fixes and build optimization - * [Karthik Balakrishnan](https://github.com/torcellite)
- Support for table alignment - * [rheber](https://github.com/rheber)
- Cli - - - - Original Project - * [John Gruber](http://daringfireball.net/projects/markdown/)
- Author of Markdown - * [John Fraser](http://attacklab.net/)
- Author of Showdown diff --git a/README.md b/README.md index c27e7de..b7cef74 100644 --- a/README.md +++ b/README.md @@ -2,541 +2,77 @@ ![Build Status: Linux](https://github.com/showdownjs/showdown/actions/workflows/node.linux.yml/badge.svg) ![Build Status: Windows](https://github.com/showdownjs/showdown/actions/workflows/node.win.yml/badge.svg) -[![Browserstack Tests](https://automate.browserstack.com/badge.svg?badge_key=VTIvTDNqWVdaTHljbS9RNmYrcTBiL0Uxc3dkRDhaN1dPaXpPb2VOc1B2VT0tLU1Ib09kVjVzMjhFcHExbWFSWlJEV3c9PQ==--1fb92e1730e4a00630d17d533822de6403ca65ec)](https://automate.browserstack.com/public-build/VTIvTDNqWVdaTHljbS9RNmYrcTBiL0Uxc3dkRDhaN1dPaXpPb2VOc1B2VT0tLU1Ib09kVjVzMjhFcHExbWFSWlJEV3c9PQ==--1fb92e1730e4a00630d17d533822de6403ca65ec) [![npm version](https://badge.fury.io/js/showdown.svg)](http://badge.fury.io/js/showdown) [![Bower version](https://badge.fury.io/bo/showdown.svg)](http://badge.fury.io/bo/showdown) +[![Join the chat at https://gitter.im/showdownjs/showdown](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/showdownjs/showdown?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/tiviesantos) ------- - Showdown is a JavaScript Markdown to HTML converter, based on the original works by John Gruber. -Showdown can be used client side (in the browser) or server side (with Node.js). -## Live DEMO +Showdown can be used on the client-side (in the browser) or server-side (with Node.js). -Check out a live demo here: http://demo.showdownjs.com/ +---- -As you know, ShowdownJS is a free library and it will remain free forever. However, maintaining and improving the library costs time and money. +## Live demo -If you like our work and find our library useful, please donate through [PayPal](https://www.paypal.me/tiviesantos)! Your contribution will be greatly appreciated and help me continue to develop this awesome library. - -## License - -ShowdownJS v 2.0 is released under the MIT license. -Previous versions are released under BSD. + ## Who uses Showdown (or a fork) - - [GoogleCloudPlatform](https://github.com/GoogleCloudPlatform) - - [Meteor](https://www.meteor.com/) - - [Stackexchange](http://stackexchange.com/) - forked as [PageDown](https://code.google.com/p/pagedown/) - - [docular](https://github.com/Vertafore/docular) - - [md-page](https://github.com/oscarmorrison/md-page) - - [QCObjects](https://qcobjects.dev) - - [and some others...](https://www.npmjs.com/browse/depended/showdown) +* [Antmarky](https://github.com/bandantonio/antmarky) +* [GoogleCloudPlatform](https://github.com/GoogleCloudPlatform) +* [Meteor](https://www.meteor.com/) +* [StackExchange](http://stackexchange.com/) - forked as [PageDown](https://code.google.com/p/pagedown/) +* [docular](https://github.com/Vertafore/docular) +* [md-page](https://github.com/oscarmorrison/md-page) +* [QCObjects](https://qcobjects.dev) +* [and some others](https://www.npmjs.com/browse/depended/showdown) -## Installation +## Quickstart -### Download tarball +Check our documentation for the [quickstart guide][quickstart] +and possible [installation methods][installation-methods]. -You can download the latest release tarball directly from [releases][releases]. +## Showdown features -### Bower +### Platform-agnostic - bower install showdown +Showdown can easily be used on server-side and client-side. -### npm (server-side) +### Two-way conversion - npm install showdown +Showdown not only helps you to convert your Markdown documents into HTML but also can bring them back to Markdown from HTML. -### NuGet package +### Extensions - PM> Install-Package showdownjs +Expand Showdown's functionality using a powerful [extension system][extensions]. Extensions can also be used on server-side and client-side. -The NuGet Packages can be found [here](https://www.nuget.org/packages/showdownjs/). +### CLI -### CDN +Showdown comes bundled with a Command-line interface (CLI) tool that allows you to run Showdown converter from the command line. -You can also use one of several CDNs available: +Check the [CLI][cli] section in the documentation for more information. -* jsDelivr +## Contribution guide - https://cdn.jsdelivr.net/npm/showdown@/dist/showdown.min.js - -* cdnjs - - https://cdnjs.cloudflare.com/ajax/libs/showdown//showdown.min.js - -* unpkg - - https://unpkg.com/showdown/dist/showdown.min.js - -*Note*: replace `` with an actual full length version you're interested in e.g. `1.9.0` -## Browser Compatibility - -Showdown has been tested successfully with: - - * Firefox 1.5 and 2.0 - * Chrome 12.0 - * Internet Explorer 6 and 7 - * Safari 2.0.4 - * Opera 8.54 and 9.10 - * Netscape 8.1.2 - * Konqueror 3.5.4 - -In theory, Showdown will work in any browser that supports ECMA 262 3rd Edition (JavaScript 1.5). -The converter itself might even work in things that aren't web browsers, like Acrobat. No promises. - - -## Node compatibility - -Showdown is intended to work on any supported Node.js version (see the [Node.js releases schedule](https://nodejs.org/en/about/releases/). The code may work with previous versions of Node.js, but no accomidations are made to ensure it does. - - -## Legacy version - -If you're looking for showdown v<1.0.0, you can find it in the [**legacy branch**][legacy-branch]. - -## Changelog - -You can check the full [changelog][changelog] - -## Extended documentation -Check our [wiki pages][wiki] for examples and a more in-depth documentation. - - -## Quick Example - -### Node - -```js -var showdown = require('showdown'), - converter = new showdown.Converter(), - text = '# hello, markdown!', - html = converter.makeHtml(text); -``` - -### Browser - -```js -var converter = new showdown.Converter(), - text = '# hello, markdown!', - html = converter.makeHtml(text); -``` - -### Output - -Both examples should output... - -```html -

hello, markdown!

-``` - -## Options - -You can change some of showdown's default behavior through options. - -### Setting options - -Options can be set: - -#### Globally - -Setting a "global" option affects all instances of showdown - -```js -showdown.setOption('optionKey', 'value'); -``` - -#### Locally -Setting a "local" option only affects the specified Converter object. -Local options can be set: - - * **through the constructor** - ```js - var converter = new showdown.Converter({optionKey: 'value'}); - ``` - - * **through the setOption() method** - ```js - var converter = new showdown.Converter(); - converter.setOption('optionKey', 'value'); - ``` - -### Getting an option - -Showdown provides 2 methods (both local and global) to retrieve previous set options. - -#### getOption() - -```js -// Global -var myOption = showdown.getOption('optionKey'); - -//Local -var myOption = converter.getOption('optionKey'); -``` - -#### getOptions() - -```js -// Global -var showdownGlobalOptions = showdown.getOptions(); - -//Local -var thisConverterSpecificOptions = converter.getOptions(); -``` - -### Retrieve the default options - -You can get showdown's default options with: -```js -var defaultOptions = showdown.getDefaultOptions(); -``` - -### Valid Options - - * **omitExtraWLInCodeBlocks**: (boolean) [default false] Omit the trailing newline in a code block. Ex: - - This: - ```html - 
var foo = 'bar';
-
- ``` - Becomes this: - ```html - 
var foo = 'bar';
 - ``` - - * **noHeaderId**: (boolean) [default false] Disable the automatic generation of header ids. - Setting to true overrides **prefixHeaderId** - - * **customizedHeaderId**: (boolean) [default false] Use text in curly braces as header id. **(since v1.7.0)** - Example: - ``` - ## Sample header {real-id} will use real-id as id - ``` - - * **ghCompatibleHeaderId**: (boolean) [default false] Generate header ids compatible with github style - (spaces are replaced with dashes and a bunch of non alphanumeric chars are removed) **(since v1.5.5)** - - * **prefixHeaderId**: (string/boolean) [default false] Add a prefix to the generated header ids. - Passing a string will prefix that string to the header id. Setting to `true` will add a generic 'section' prefix. - - * **rawPrefixHeaderId**: (boolean) [default false] Setting this option to true will prevent showdown from modifying the prefix. - This might result in malformed IDs (if, for instance, the " char is used in the prefix). - Has no effect if prefixHeaderId is set to false. **(since v 1.7.3)** - - * **rawHeaderId**: (boolean) [default false] Remove only spaces, ' and " from generated header ids (including prefixes), - replacing them with dashes (-). WARNING: This might result in malformed ids **(since v1.7.3)** - - * **headerLevelStart**: (integer) [default 1] Set the header starting level. For instance, setting this to 3 means that - - ```md - # foo - ``` - will be parsed as - - ```html -

foo

- ``` - - * **parseImgDimensions**: (boolean) [default false] Enable support for setting image dimensions from within markdown syntax. - Examples: - ``` - ![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 - ``` - - * **simplifiedAutoLink**: (boolean) [default false] Turning this option on will enable automatic linking to urls. - This means that: - - ```md - some text www.google.com - ``` - will be parsed as - ```html -

some text www.google.com - ``` - - * ~~**excludeTrailingPunctuationFromURLs**: (boolean) [default false] This option excludes trailing punctuation from autolinking urls. - Punctuation excluded: `. ! ? ( )`. Only applies if **simplifiedAutoLink** option is set to `true`.~~ - - * **literalMidWordUnderscores**: (boolean) [default false] Turning this on will stop showdown from interpreting - underscores in the middle of words as `` and `` and instead treat them as literal underscores. - - Example: - - ```md - some text with__underscores__in middle - ``` - will be parsed as - ```html -

some text with__underscores__in middle

- ``` - - * ~~**literalMidWordAsterisks**: (boolean) [default false] Turning this on will stop showdown from interpreting asterisks - in the middle of words as `` and `` and instead treat them as literal asterisks.~~ - - * **strikethrough**: (boolean) [default false] Enable support for strikethrough syntax. - `~~strikethrough~~` as `strikethrough` - - * **tables**: (boolean) [default false] Enable support for tables syntax. Example: - - ```md - | h1 | h2 | h3 | - |:------|:-------:|--------:| - | 100 | [a][1] | ![b][2] | - | *foo* | **bar** | ~~baz~~ | - ``` - - See the wiki for more info - - * **tablesHeaderId**: (boolean) [default false] If enabled adds an id property to table headers tags. - - * **ghCodeBlocks**: (boolean) [default true] Enable support for GFM code block style. - - * **tasklists**: (boolean) [default false] Enable support for GFM tasklists. Example: - - ```md - - [x] This task is done - - [ ] This is still pending - ``` - * **smoothLivePreview**: (boolean) [default false] Prevents weird effects in live previews due to incomplete input - - * **smartIndentationFix**: (boolean) [default false] Tries to smartly fix indentation problems related to es6 template - strings in the midst of indented code. - - * **disableForced4SpacesIndentedSublists**: (boolean) [default false] Disables the requirement of indenting sublists - by 4 spaces for them to be nested, effectively reverting to the old behavior where 2 or 3 spaces were enough. - **(since v1.5.0)** - - * **simpleLineBreaks**: (boolean) [default false] Parses line breaks as `
`, without - needing 2 spaces at the end of the line **(since v1.5.1)** - - ```md - a line - wrapped in two - ``` - - turns into: - - ```html -

a line
- wrapped in two

- ``` - - * **requireSpaceBeforeHeadingText**: (boolean) [default false] Makes adding a space between `#` and the header text mandatory **(since v1.5.3)** - - * **ghMentions**: (boolean) [default false] Enables github @mentions, which link to the username mentioned **(since v1.6.0)** - - * **ghMentionsLink**: (string) [default `https://github.com/{u}`] Changes the link generated by @mentions. - Showdown will replace `{u}` with the username. Only applies if ghMentions option is enabled. - Example: `@tivie` with ghMentionsOption set to `//mysite.com/{u}/profile` will result in `@tivie` - - * **encodeEmails**: (boolean) [default true] Enable e-mail addresses encoding through the use of Character Entities, transforming ASCII e-mail addresses into its equivalent decimal entities. (since v1.6.1) - - NOTE: Prior to version 1.6.1, emails would always be obfuscated through dec and hex encoding. - - * **openLinksInNewWindow**: (boolean) [default false] Open all links in new windows - (by adding the attribute `target="_blank"` to `` tags) **(since v1.7.0)** - - * **backslashEscapesHTMLTags**: (boolean) [default false] Support for HTML Tag escaping. ex: `\
foo\
` **(since v1.7.2)** - - * **emoji**: (boolean) [default false] Enable emoji support. Ex: `this is a :smile: emoji` - For more info on available emojis, see https://github.com/showdownjs/showdown/wiki/Emojis **(since v.1.8.0)** - - * **underline**: (boolean) [default false] ***EXPERIMENTAL FEATURE*** Enable support for underline. - Syntax is **double** or **triple** **underscores** ex: `__underlined word__`. With this option enabled, underscores are no longer parses into `` and ``. - - * **ellipsis**: (boolean) [default true] Replaces three dots with the ellipsis unicode character. - - * **completeHTMLDocument**: (boolean) [default false] Outputs a complete html document, - including ``, `` and `` tags' instead of an HTML fragment. (since v.1.8.5) - - * **metadata**: (boolean) [default false] Enable support for document metadata (defined at the top of the document - between `«««` and `»»»` or between `---` and `---`). (since v.1.8.5) - - ```js - var conv = new showdown.Converter({metadata: true}); - var html = conv.makeHtml(someMd); - var metadata = conv.getMetadata(); // returns an object with the document metadata - ``` - - * **splitAdjacentBlockquotes**: (boolean) [default false] Split adjacent blockquote blocks.(since v.1.8.6) - - * **moreStyling**: (boolean) [default false] Adds some useful classes for css styling. (since v2.0.1) - - - Tasklists: Adds the class `task-list-item-complete` to completed tasks items in GFM tasklists. - -**NOTE**: Please note that until **version 1.6.0**, all of these options are ***DISABLED*** by default in the cli tool. - - -## Flavors - -You can also use flavors or presets to set the correct options automatically, so that showdown behaves like popular markdown flavors. - -Currently, the following flavors are available: - - * original - original markdown flavor as in [John Gruber's spec](https://daringfireball.net/projects/markdown/) - * vanilla - showdown base flavor (as from v1.3.1) - * github - GFM (GitHub Flavored Markdown) - - -### Global -```javascript -showdown.setFlavor('github'); -``` - -### Instance -```javascript -converter.setFlavor('github'); -``` - - -## CLI Tool - -Showdown also comes bundled with a Command Line Interface tool. You can check the [CLI wiki page][cli-wiki] for more info - -## Integration with AngularJS - -ShowdownJS project also provides seamlessly integration with AngularJS via a "plugin". -Please visit https://github.com/showdownjs/ngShowdown for more information. - -## Integration with TypeScript - -If you're using TypeScript you maybe want to use the types from [DefinitelyTyped][definitely-typed] - -## Integration with SystemJS/JSPM - -Integration with SystemJS can be obtained via the third party ["system-md" plugin](https://github.com/guybedford/system-md). - -## Integration with VueJS - -To use ShowdownJS as a Vue component quickly, you can check [vue-showdown](https://vue-showdown.js.org/). - -## XSS vulnerability - -Showdown doesn't sanitize the input. This is by design since markdown relies on it to allow certain features to be correctly parsed into HTML. -This, however, means XSS injection is quite possible. - -Please refer to the wiki article [Markdown's XSS Vulnerability (and how to mitigate it)][xss-wiki] -for more information. - -## Extensions - -Showdown allows additional functionality to be loaded via extensions. (you can find a list of known showdown extensions [here][ext-wiki]) -You can also find a boilerplate, to create your own extensions in [this repository][boilerplate-repo] - -### Client-side Extension Usage - -```js -