mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-27 18:40:28 +00:00
186 lines
6.0 KiB
Markdown
186 lines
6.0 KiB
Markdown
|
# markdown-js
|
|||
|
|
|
|||
|
|
Yet another markdown parser, this time for JavaScript. There's a few
|
|||
|
|
options that precede this project but they all treat markdown to HTML
|
|||
|
|
conversion as a single step process. You pass markdown in and get HTML
|
|||
|
|
out, end of story. We had some pretty particular views on how the
|
|||
|
|
process should actually look, which include:
|
|||
|
|
|
|||
|
|
* producing well-formed HTML. This means that `em` and `strong` nesting
|
|||
|
|
is important, as is the ability to output as both HTML and XHTML
|
|||
|
|
|
|||
|
|
* having an intermediate representation to allow processing of parsed
|
|||
|
|
data (we in fact have two, both [JsonML]: a markdown tree and an HTML tree)
|
|||
|
|
|
|||
|
|
* being easily extensible to add new dialects without having to
|
|||
|
|
rewrite the entire parsing mechanics
|
|||
|
|
|
|||
|
|
* having a good test suite. The only test suites we could find tested
|
|||
|
|
massive blocks of input, and passing depended on outputting the HTML
|
|||
|
|
with exactly the same whitespace as the original implementation
|
|||
|
|
|
|||
|
|
[JsonML]: http://jsonml.org/ "JSON Markup Language"
|
|||
|
|
|
|||
|
|
## Installation
|
|||
|
|
|
|||
|
|
Just the `markdown` library:
|
|||
|
|
|
|||
|
|
npm install markdown
|
|||
|
|
|
|||
|
|
Optionally, install `md2html` into your path
|
|||
|
|
|
|||
|
|
npm install -g markdown
|
|||
|
|
|
|||
|
|
## Usage
|
|||
|
|
|
|||
|
|
### Node
|
|||
|
|
|
|||
|
|
The simple way to use it with node is:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
var markdown = require( "markdown" ).markdown;
|
|||
|
|
console.log( markdown.toHTML( "Hello *World*!" ) );
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Browser
|
|||
|
|
|
|||
|
|
It also works in a browser; here is a complete example:
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
<html>
|
|||
|
|
<body>
|
|||
|
|
<textarea id="text-input" oninput="this.editor.update()"
|
|||
|
|
rows="6" cols="60">Type **Markdown** here.</textarea>
|
|||
|
|
<div id="preview"> </div>
|
|||
|
|
<script src="lib/markdown.js"></script>
|
|||
|
|
<script>
|
|||
|
|
function Editor(input, preview) {
|
|||
|
|
this.update = function () {
|
|||
|
|
preview.innerHTML = markdown.toHTML(input.value);
|
|||
|
|
};
|
|||
|
|
input.editor = this;
|
|||
|
|
this.update();
|
|||
|
|
}
|
|||
|
|
var $ = function (id) { return document.getElementById(id); };
|
|||
|
|
new Editor($("text-input"), $("preview"));
|
|||
|
|
</script>
|
|||
|
|
</body>
|
|||
|
|
</html>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Command line
|
|||
|
|
|
|||
|
|
Assuming you've installed the `md2html` script (see Installation,
|
|||
|
|
above), you can convert markdown to html:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# read from a file
|
|||
|
|
md2html /path/to/doc.md > /path/to/doc.html
|
|||
|
|
|
|||
|
|
# or from stdin
|
|||
|
|
echo 'Hello *World*!' | md2html
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### More options
|
|||
|
|
|
|||
|
|
If you want more control check out the documentation in
|
|||
|
|
[lib/markdown.js] which details all the methods and parameters
|
|||
|
|
available (including examples!). One day we'll get the docs generated
|
|||
|
|
and hosted somewhere for nicer browsing.
|
|||
|
|
|
|||
|
|
[lib/markdown.js]: http://github.com/evilstreak/markdown-js/blob/master/lib/markdown.js
|
|||
|
|
|
|||
|
|
Meanwhile, here's an example of using the multi-step processing to
|
|||
|
|
make wiki-style linking work by filling in missing link references:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
var md = require( "markdown" ).markdown,
|
|||
|
|
text = "[Markdown] is a simple text-based [markup language]\n" +
|
|||
|
|
"created by [John Gruber]\n\n" +
|
|||
|
|
"[John Gruber]: http://daringfireball.net";
|
|||
|
|
|
|||
|
|
// parse the markdown into a tree and grab the link references
|
|||
|
|
var tree = md.parse( text ),
|
|||
|
|
refs = tree[ 1 ].references;
|
|||
|
|
|
|||
|
|
// iterate through the tree finding link references
|
|||
|
|
( function find_link_refs( jsonml ) {
|
|||
|
|
if ( jsonml[ 0 ] === "link_ref" ) {
|
|||
|
|
var ref = jsonml[ 1 ].ref;
|
|||
|
|
|
|||
|
|
// if there's no reference, define a wiki link
|
|||
|
|
if ( !refs[ ref ] ) {
|
|||
|
|
refs[ ref ] = {
|
|||
|
|
href: "http://en.wikipedia.org/wiki/" + ref.replace(/\s+/, "_" )
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
else if ( Array.isArray( jsonml[ 1 ] ) ) {
|
|||
|
|
jsonml[ 1 ].forEach( find_link_refs );
|
|||
|
|
}
|
|||
|
|
else if ( Array.isArray( jsonml[ 2 ] ) ) {
|
|||
|
|
jsonml[ 2 ].forEach( find_link_refs );
|
|||
|
|
}
|
|||
|
|
} )( tree );
|
|||
|
|
|
|||
|
|
// convert the tree into html
|
|||
|
|
var html = md.renderJsonML( md.toHTMLTree( tree ) );
|
|||
|
|
console.log( html );
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Intermediate Representation
|
|||
|
|
|
|||
|
|
Internally the process to convert a chunk of markdown into a chunk of
|
|||
|
|
HTML has three steps:
|
|||
|
|
|
|||
|
|
1. Parse the markdown into a JsonML tree. Any references found in the
|
|||
|
|
parsing are stored in the attribute hash of the root node under the
|
|||
|
|
key `references`.
|
|||
|
|
|
|||
|
|
2. Convert the markdown tree into an HTML tree. Rename any nodes that
|
|||
|
|
need it (`bulletlist` to `ul` for example) and lookup any references
|
|||
|
|
used by links or images. Remove the references attribute once done.
|
|||
|
|
|
|||
|
|
3. Stringify the HTML tree being careful not to wreck whitespace where
|
|||
|
|
whitespace is important (surrounding inline elements for example).
|
|||
|
|
|
|||
|
|
Each step of this process can be called individually if you need to do
|
|||
|
|
some processing or modification of the data at an intermediate stage.
|
|||
|
|
For example, you may want to grab a list of all URLs linked to in the
|
|||
|
|
document before rendering it to HTML which you could do by recursing
|
|||
|
|
through the HTML tree looking for `a` nodes.
|
|||
|
|
|
|||
|
|
## Running tests
|
|||
|
|
|
|||
|
|
To run the tests under node you will need tap installed (it's listed as a
|
|||
|
|
`devDependencies` so `npm install` from the checkout should be enough), then do
|
|||
|
|
|
|||
|
|
$ npm test
|
|||
|
|
|
|||
|
|
## Contributing
|
|||
|
|
|
|||
|
|
Do the usual github fork and pull request dance. Add yourself to the
|
|||
|
|
contributors section of [package.json](/package.json) too if you want to.
|
|||
|
|
|
|||
|
|
## License
|
|||
|
|
|
|||
|
|
Released under the MIT license.
|
|||
|
|
|
|||
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|||
|
|
this software and associated documentation files (the "Software"), to deal in
|
|||
|
|
the Software without restriction, including without limitation the rights to
|
|||
|
|
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|||
|
|
the Software, and to permit persons to whom the Software is furnished to do so,
|
|||
|
|
subject to the following conditions:
|
|||
|
|
|
|||
|
|
The above copyright notice and this permission notice shall be included in all
|
|||
|
|
copies or substantial portions of the Software.
|
|||
|
|
|
|||
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|||
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|||
|
|
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|||
|
|
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|||
|
|
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|||
|
|
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|