Permalink
Browse files

Added a README

  • Loading branch information...
1 parent 9827b00 commit 2b54920b28c6795bc747150ac58aca8293a1f24a @evilstreak evilstreak committed Jan 12, 2010
Showing with 64 additions and 0 deletions.
  1. +64 −0 README.markdown
View
@@ -0,0 +1,64 @@
+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"
+
+## Usage
+
+The simple way to use it with CommonJS is:
+
+ var input = "# Heading\n\nParagraph";
+ var output = require( "markdown" ).toHTML( input );
+ print( output );
+
+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.
+
+We're yet to try it out in a browser, though it's high up on our list of
+things to sort out for this project.
+
+[lib/markdown.js]: http://github.com/evilstreak/markdown-js/blob/master/lib/markdown.js
+
+## 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.

0 comments on commit 2b54920

Please sign in to comment.