diff --git a/README.md b/README.md index 54fef368..a5fdb546 100644 --- a/README.md +++ b/README.md @@ -184,163 +184,6 @@ 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`. - -## 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. - - * This release uses the HTML parser from Markdown 1.0.2b2, - which means it fails `Inline HTML (Advanced).text` from - the Markdown test suite: - -
-
- unindented == broken -
-
- - * Showdown doesn't support the markdown="1" attribute: - -
- Markdown does *not* work in here. -
- - This is half laziness on my part and half stubbornness. - Markdown is smart enough to process the contents of span- - level tags without screwing things up; shouldn't it be - able to do the same inside block elements? Let's find a - way to make markdown="1" the default. - - - * You can only nest square brackets in link titles to a - depth of two levels: - - [[fine]](http://www.attacklab.net/) - [[[broken]]](http://www.attacklab.net/) - - If you need more, you can escape them with backslashes. - - - * When sublists have paragraphs, Showdown produces equivalent - HTML with a slightly different arrangement of newlines: - - + item - - - subitem - - The HTML has a superfluous newline before this - paragraph. - - - subitem - - The HTML here is unchanged. - - - subitem - - The HTML is missing a newline after this - list subitem. - - - - * Markdown.pl creates empty title attributes for - inline-style images: - - Here's an empty title on an inline-style - ![image](http://w3.org/Icons/valid-xhtml10). - - I tried to replicate this to clean up my diffs during - testing, but I went too far: now Showdown also makes - empty titles for reference-style images: - - Showdown makes an empty title for - reference-style ![images][] too. - - [images]: http://w3.org/Icons/valid-xhtml10 - - - * With crazy input, Markdown will mistakenly put - `` or `` tags in URLs: - - - improbable URL - - - Showdown won't. But still, don't do that. - - -## 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 `
` to be `
`, that would be an output modifier. - -Each extension can provide two combinations of interfaces for showdown. - -### Regex/Replace - -Regex/replace style extensions are very similar to Javascript's `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. - -**Example:** - -```js -var demo = function(converter) { - return [ - // Replace escaped @ symbols - { type: 'lang', regex: '\\@', replace: '@' } - ]; -} -``` - -### 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). - -**Example:** - -```js -var demo = function(converter) { - return [ - // Replace escaped @ symbols - { type: 'lang', filter: function(text) { - return text.replace(/\\@/g, '@'); - }} - ]; -} -``` - -### 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. - -```js -(function(){ - // Your extension here -}()); -``` - -Second, client-side extensions should add a property onto `Showdown.extensions` which matches the name of the file. As an example, a file named `demo.js` should then add `Showdown.extensions.demo`. Server-side extensions can simply export themselves. - -```js -(function(){ - var demo = function(converter) { - // ... extension code here ... - }; - - // Client-side export - if (typeof window !== 'undefined' && window.Showdown && window.Showdown.extensions) { window.Showdown.extensions.demo = demo; } - // Server-side export - if (typeof module !== 'undefined') module.exports = demo; -}()); -``` - -### 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 folder using the md/html format and they will automatically be run when tests are run. - - ## Contributing If you wish to contribute please read the following quick guide.