mirror of
https://github.com/showdownjs/showdown.git
synced 2024-03-22 13:30:55 +08:00
minor README cleanup
This commit is contained in:
Corey Innis
parent
c0d6f9fb21
commit
57fa69eff5
87
README.md
87
README.md
|
|
@ -1,5 +1,4 @@
|
|||
NOTE -- Showdown on GitHub
|
||||
==========================
|
||||
# NOTE -- Showdown on GitHub
|
||||
|
||||
**Please note** that I, Corey, am not the author of Showdown. Rather, I found it
|
||||
some time back at <http://attacklab.net/showdown/>
|
||||
|
|
@ -20,8 +19,7 @@ Cheers,<br/>
|
|||
Corey
|
||||
|
||||
|
||||
Showdown -- A JavaScript port of Markdown
|
||||
=========================================
|
||||
# Showdown -- A JavaScript port of Markdown
|
||||
|
||||
Showdown Copyright (c) 2007 John Fraser.
|
||||
<http://www.attacklab.net/>
|
||||
|
|
@ -33,32 +31,29 @@ Redistributable under a BSD-style open source license.
|
|||
See license.txt for more information.
|
||||
|
||||
|
||||
Quick Example
|
||||
-------------
|
||||
## Quick Example
|
||||
|
||||
``` js
|
||||
```js
|
||||
var Showdown = require('showdown');
|
||||
var converter = new Showdown.converter();
|
||||
|
||||
converter.makeHtml('#hello markdown!');
|
||||
|
||||
// <h1 id="hellomarkdown">hello, markdown</h1>
|
||||
|
||||
```
|
||||
|
||||
What's it for?
|
||||
--------------
|
||||
## What's it for?
|
||||
|
||||
Developers can use Showdown to:
|
||||
|
||||
* Add in-browser preview to existing Markdown apps
|
||||
* Add in-browser preview to existing Markdown apps
|
||||
|
||||
Showdown's output is (almost always) identical to
|
||||
markdown.pl's, so the server can reproduce exactly
|
||||
the output that the user saw. (See below for
|
||||
exceptions.)
|
||||
|
||||
* Add Markdown input to programs that don't support it
|
||||
* Add Markdown input to programs that don't support it
|
||||
|
||||
Any app that accepts HTML input can now be made to speak
|
||||
Markdown by modifying the input pages's HTML. If your
|
||||
|
|
@ -68,7 +63,7 @@ Developers can use Showdown to:
|
|||
uses -- and you can do it with just a two-line
|
||||
`onsubmit` function!
|
||||
|
||||
* Add Markdown input to closed-source web apps
|
||||
* Add Markdown input to closed-source web apps
|
||||
|
||||
You can write bookmarklets or userscripts to extend
|
||||
any standard textarea on the web so that it accepts
|
||||
|
|
@ -76,7 +71,7 @@ Developers can use Showdown to:
|
|||
the same can probably be done with many rich edit
|
||||
controls.
|
||||
|
||||
* Build new web apps from scratch
|
||||
* Build new web apps from scratch
|
||||
|
||||
A Showdown front-end can send back text in Markdown,
|
||||
HTML or both, so you can trade bandwidth for server
|
||||
|
|
@ -89,23 +84,21 @@ Developers can use Showdown to:
|
|||
Markdown.)
|
||||
|
||||
|
||||
Browser Compatibility
|
||||
---------------------
|
||||
## Browser Compatibility
|
||||
|
||||
Showdown has been tested successfully with:
|
||||
|
||||
- Firefox 1.5 and 2.0
|
||||
- Internet Explorer 6 and 7
|
||||
- Safari 2.0.4
|
||||
- Opera 8.54 and 9.10
|
||||
- Netscape 8.1.2
|
||||
- Konqueror 3.5.4
|
||||
* Firefox 1.5 and 2.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.
|
||||
|
||||
|
||||
Extensions
|
||||
----------
|
||||
## Extensions
|
||||
|
||||
Showdown allows additional functionality to be loaded via extensions.
|
||||
|
||||
|
|
@ -131,14 +124,11 @@ var converter = new Showdown().converter({ extensions: ['twitter', mine] });
|
|||
```
|
||||
|
||||
|
||||
## Known Differences in Output
|
||||
|
||||
Known Differences in Output
|
||||
---------------------------
|
||||
In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7. What follows is a list of all known deviations. Please file an issue if you find more.
|
||||
|
||||
In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7. What follows is a list of all known deviations. Please email me if you find more.
|
||||
|
||||
|
||||
* This release uses the HTML parser from Markdown 1.0.2b2,
|
||||
* This release uses the HTML parser from Markdown 1.0.2b2,
|
||||
which means it fails `Inline HTML (Advanced).text` from
|
||||
the Markdown test suite:
|
||||
|
||||
|
|
@ -148,8 +138,7 @@ In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7.
|
|||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
* Showdown doesn't support the markdown="1" attribute:
|
||||
* Showdown doesn't support the markdown="1" attribute:
|
||||
|
||||
<div markdown="1">
|
||||
Markdown does *not* work in here.
|
||||
|
|
@ -162,7 +151,7 @@ In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7.
|
|||
way to make markdown="1" the default.
|
||||
|
||||
|
||||
* You can only nest square brackets in link titles to a
|
||||
* You can only nest square brackets in link titles to a
|
||||
depth of two levels:
|
||||
|
||||
[[fine]](http://www.attacklab.net/)
|
||||
|
|
@ -171,7 +160,7 @@ In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7.
|
|||
If you need more, you can escape them with backslashes.
|
||||
|
||||
|
||||
* When sublists have paragraphs, Showdown produces equivalent
|
||||
* When sublists have paragraphs, Showdown produces equivalent
|
||||
HTML with a slightly different arrangement of newlines:
|
||||
|
||||
+ item
|
||||
|
|
@ -192,7 +181,7 @@ In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7.
|
|||
|
||||
|
||||
|
||||
* Markdown.pl creates empty title attributes for
|
||||
* Markdown.pl creates empty title attributes for
|
||||
inline-style images:
|
||||
|
||||
Here's an empty title on an inline-style
|
||||
|
|
@ -208,7 +197,7 @@ In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7.
|
|||
[images]: http://w3.org/Icons/valid-xhtml10
|
||||
|
||||
|
||||
* With crazy input, Markdown will mistakenly put
|
||||
* With crazy input, Markdown will mistakenly put
|
||||
`<strong>` or `<em>` tags in URLs:
|
||||
|
||||
<a href="<*Markdown adds em tags in here*>">
|
||||
|
|
@ -218,8 +207,7 @@ In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7.
|
|||
Showdown won't. But still, don't do that.
|
||||
|
||||
|
||||
Tests
|
||||
---------------------------
|
||||
## Tests
|
||||
A suite of tests is available which require node.js. Once node is installed, run the following command from the project root to install the development dependencies:
|
||||
|
||||
npm install --dev
|
||||
|
|
@ -231,21 +219,20 @@ Once installed the tests can be run from the project root using:
|
|||
New test cases can easily be added. Create a markdown file (ending in `.md`) which contains the markdown to test. Create a `.html` file of the exact same name. It will automatically be tested when the tests are executed with `mocha`.
|
||||
|
||||
|
||||
Creating Markdown Extensions
|
||||
----------------------------
|
||||
## Creating Markdown Extensions
|
||||
|
||||
A showdown extension is simply a function which returns an array of extensions. Each single extension can be one of two types:
|
||||
|
||||
- Language Extension -- Language extensions are ones that that add new markdown syntax to showdown. For example, say you wanted `^^youtube http://www.youtube.com/watch?v=oHg5SJYRHA0` to automatically render as an embedded YouTube video, that would be a language extension.
|
||||
- Output Modifiers -- After showdown has run, and generated HTML, an output modifier would change that HTML. For example, say you wanted to change `<div class="header">` to be `<header>`, that would be an output modifier.
|
||||
* Language Extension -- Language extensions are ones that that add new markdown syntax to showdown. For example, say you wanted `^^youtube http://www.youtube.com/watch?v=oHg5SJYRHA0` to automatically render as an embedded YouTube video, that would be a language extension.
|
||||
* Output Modifiers -- After showdown has run, and generated HTML, an output modifier would change that HTML. For example, say you wanted to change `<div class="header">` to be `<header>`, that would be an output modifier.
|
||||
|
||||
Each extension can provide two combinations of interfaces for showdown.
|
||||
|
||||
#### Regex/Replace
|
||||
### Regex/Replace
|
||||
|
||||
Regex/replace style extensions are very similar to javascripts `string.replace` function. Two properties are given, `regex` and `replace`. `regex` is a string and `replace` can be either a string or a function. If `replace` is a string, it can use the `$1` syntax for group substituation, exactly as if it were making use of `string.replace` (internally it does this actually); The value of `regex` is assumed to be a global replacement.
|
||||
Regex/replace style extensions are very similar to javascripts `string.replace` function. Two properties are given, `regex` and `replace`. `regex` is a string and `replace` can be either a string or a function. If `replace` is a string, it can use the `$1` syntax for group substitution, exactly as if it were making use of `string.replace` (internally it does this actually); The value of `regex` is assumed to be a global replacement.
|
||||
|
||||
#### Regex/Replace Example
|
||||
**Example:**
|
||||
|
||||
``` js
|
||||
var demo = function(converter) {
|
||||
|
|
@ -256,11 +243,11 @@ var demo = function(converter) {
|
|||
}
|
||||
```
|
||||
|
||||
#### Filter
|
||||
### Filter
|
||||
|
||||
Alternately, if you'd just like to do everything yourself, you can specify a filter which is a callback with a single input parameter, text (the current source text within the showdown engine).
|
||||
|
||||
#### Filter Example
|
||||
**Example:**
|
||||
|
||||
``` js
|
||||
var demo = function(converter) {
|
||||
|
|
@ -273,9 +260,9 @@ var demo = function(converter) {
|
|||
}
|
||||
```
|
||||
|
||||
#### Implementation Concerns
|
||||
### Implementation Concerns
|
||||
|
||||
One bit which should be taken into account is maintaining both client-side and server-side compatibility. This can be achieved with a few lines of boilerplate code. First, to prevent polluting the global scope for client-side code, the extension definition should be wrapped in a self executing function.
|
||||
One bit which should be taken into account is maintaining both client-side and server-side compatibility. This can be achieved with a few lines of boilerplate code. First, to prevent polluting the global scope for client-side code, the extension definition should be wrapped in a self-executing function.
|
||||
|
||||
``` js
|
||||
(function(){
|
||||
|
|
@ -298,7 +285,7 @@ Second, client-side extensions should add a property onto `Showdown.extensions`
|
|||
}());
|
||||
```
|
||||
|
||||
#### Testing Extensions
|
||||
### Testing Extensions
|
||||
|
||||
The showdown test runner is setup to automatically test cases for extensions. To add test cases for an extension, create a new folder under `./test/extensions` which matches the name of the `.js` file in `./src/extensions`. Place any test cases into the filder using the md/html format and they will automatically be run when tests are run.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user