Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Conversion of documentation to yuidoc. #54

Closed
wants to merge 2 commits into from

2 participants

@jshirley

As discussed with Ash, I've migrated and edited some of the documentation to be compatible with yuidoc (http://yui.github.com/yuidoc/syntax/index.html), which supports full markdown and more programmatic documentation.

You can see the generated documentation here:
http://j.shirley.im/tech/yui/gallery-markdown/docs/classes/Markdown.html

(It's all node-based, very easy to setup).

Thanks!

@evilstreak evilstreak closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 191 additions and 107 deletions.
  1. +191 −107 lib/markdown.js
View
298 lib/markdown.js
@@ -1,37 +1,52 @@
-// Released under MIT license
-// Copyright (c) 2009-2010 Dominic Baggott
-// Copyright (c) 2009-2010 Ash Berlin
-// Copyright (c) 2011 Christoph Dorn <christoph@christophdorn.com> (http://www.christophdorn.com)
+/**
+A wrapper for an all purpose Markdown renderer with multiple dialect support.
-(function( expose ) {
+@module gallery-markdown
+**/
/**
- * class Markdown
- *
- * Markdown processing in Javascript done right. We have very particular views
- * on what constitutes 'right' which include:
- *
- * - produces well-formed HTML (this means that em and strong nesting is
- * important)
- *
- * - has an intermediate representation to allow processing of parsed data (We
- * in fact have two, both as [JsonML]: a markdown tree and an HTML tree).
- *
- * - is easily extensible to add new dialects without having to rewrite the
- * entire parsing mechanics
- *
- * - has a good test suite
- *
- * This implementation fulfills all of these (except that the test suite could
- * do with expanding to automatically run all the fixtures from other Markdown
- * implementations.)
- *
- * ##### Intermediate Representation
- *
- * *TODO* Talk about this :) Its JsonML, but document the node names we use.
- *
- * [JsonML]: http://jsonml.org/ "JSON Markup Language"
- **/
+A YUI wrapper around the fantastic Markdown library at https://github.com/evilstreak/markdown-js.
+This supports several dialects and works very well. I (jshirley) am not the author, merely the one maintaining the YUI wrapper.
+
+Below is the original documentation:
+
+Markdown processing in Javascript done right. We have very particular views
+on what constitutes 'right' which include:
+
+* produces well-formed HTML (this means that em and strong nesting is
+ important)
+* has an intermediate representation to allow processing of parsed data (We
+ in fact have two, both as [JsonML]: a markdown tree and an HTML tree).
+* is easily extensible to add new dialects without having to rewrite the
+ entire parsing mechanics
+* has a good test suite
+
+This implementation fulfills all of these (except that the test suite could
+do with expanding to automatically run all the fixtures from other Markdown
+implementations.)
+
+### Intermediate Representation
+
+*TODO* Talk about this :) Its JsonML, but document the node names we use.
+
+[JsonML, the JSON Markup Language](http://jsonml.org/)
+
+### Copyright & License of Original
+
+Released under MIT license by the following original authors:
+
+Copyright (c) 2009-2010 Dominic Baggott
+
+Copyright (c) 2009-2010 Ash Berlin
+
+Copyright (c) 2011 [Christoph Dorn &lt;christoph@christophdorn.com&gt;](http://www.christophdorn.com)
+
+@class Markdown
+@static
+**/
+
+(function( expose ) {
+
var Markdown = expose.Markdown = function Markdown(dialect) {
switch (typeof dialect) {
case "undefined":
@@ -55,12 +70,13 @@ var Markdown = expose.Markdown = function Markdown(dialect) {
};
/**
- * parse( markdown, [dialect] ) -> JsonML
- * - markdown (String): markdown string to parse
- * - dialect (String | Dialect): the dialect to use, defaults to gruber
- *
- * Parse `markdown` and return a markdown document as a Markdown.JsonML tree.
- **/
+Parse `markdown` and return a markdown document as a Markdown.JsonML tree.
+
+@method parse
+@param markdown {String} The Markdown string to parse
+@param dialect {String | Object} The Markdown dialect to use, defaults to gruber. Must exist in the `Markdown.dialect` object.
+@static
+**/
expose.parse = function( source, dialect ) {
// dialect will default if undefined
var md = new Markdown( dialect );
@@ -68,14 +84,16 @@ expose.parse = function( source, dialect ) {
};
/**
- * toHTML( markdown, [dialect] ) -> String
- * toHTML( md_tree ) -> String
- * - markdown (String): markdown string to parse
- * - md_tree (Markdown.JsonML): parsed markdown tree
- *
- * Take markdown (either as a string or as a JsonML tree) and run it through
- * [[toHTMLTree]] then turn it into a well-formated HTML fragment.
- **/
+Take markdown (either as a string or as a JsonML tree) and run it
+through {{#crossLink "toHTMLTree"}}{{/crossLink}} then turn it into a
+well-formated HTML fragment.
+
+@method toHTML
+@static
+@param source {String} markdown string to parse
+@param dialect {String | Object} The Markdown dialect to use, defaults to gruber. Must exist in the `Markdown.dialect` property.
+
+**/
expose.toHTML = function toHTML( source , dialect , options ) {
var input = expose.toHTMLTree( source , dialect , options );
@@ -83,16 +101,15 @@ expose.toHTML = function toHTML( source , dialect , options ) {
};
/**
- * toHTMLTree( markdown, [dialect] ) -> JsonML
- * toHTMLTree( md_tree ) -> JsonML
- * - markdown (String): markdown string to parse
- * - dialect (String | Dialect): the dialect to use, defaults to gruber
- * - md_tree (Markdown.JsonML): parsed markdown tree
- *
- * Turn markdown into HTML, represented as a JsonML tree. If a string is given
- * to this function, it is first parsed into a markdown tree by calling
- * [[parse]].
- **/
+Turn markdown into HTML, represented as a JsonML tree. If a string is given
+to this function, it is first parsed into a markdown tree by calling
+{{#crossLink "parse"}}{{{/crossLink}}.
+
+@method toHTMLTree
+@static
+@param markdown {String | Object } markdown string to parse or already parsed tree
+@param dialect {String | Object} The Markdown dialect to use, defaults to gruber. Must exist in the `Markdown.dialect` property.
+**/
expose.toHTMLTree = function toHTMLTree( input, dialect , options ) {
// convert string input to an MD tree
if ( typeof input ==="string" ) input = this.parse( input, dialect );
@@ -112,7 +129,13 @@ expose.toHTMLTree = function toHTMLTree( input, dialect , options ) {
return html;
};
-// For Spidermonkey based engines
+/**
+Returns JavaScript for parsing markdown for Spidermonkey based engines
+
+@method mk_block_toSource
+@static
+@private
+**/
function mk_block_toSource() {
return "Markdown.mk_block( " +
uneval(this.toString()) +
@@ -123,7 +146,13 @@ function mk_block_toSource() {
" )";
}
-// node
+/**
+Returns JavaScript for parsing markdown under node.
+
+@method mk_block_inspect
+@static
+@private
+**/
function mk_block_inspect() {
var util = require('util');
return "Markdown.mk_block( " +
@@ -136,6 +165,17 @@ function mk_block_inspect() {
}
+/**
+Returns a string based on a block of Markdown.
+
+@method mk_block
+@static
+@private
+@param block {String} Block of markdown
+@param trail=\n\n {String} How to trail the block, defaults to two newline characters.
+@param line {Number} The line number for this block.
+@return {String} The constructed, inspected and sourced JavaScript version of the string.
+**/
var mk_block = Markdown.mk_block = function(block, trail, line) {
// Be helpful for default case in tests.
if ( arguments.length == 1 ) trail = "\n\n";
@@ -152,13 +192,30 @@ var mk_block = Markdown.mk_block = function(block, trail, line) {
return s;
};
+/**
+Returns the number of lines in a string, based on how many new lines exist.
+
+@method mk_block
+@static
+@private
+@param str {String} A string
+@return {Number} Number of lines (counted by newlines)
+**/
function count_lines( str ) {
var n = 0, i = -1;
while ( ( i = str.indexOf('\n', i+1) ) !== -1) n++;
return n;
}
-// Internal - split source into rough blocks
+/**
+Split input into rough blocks.
+
+@method split_blocks
+@static
+@private
+@param input {String} Chunk of Markdown as text
+@return {Array} An array of Markdown blocks
+**/
Markdown.prototype.split_blocks = function splitBlocks( input, startLine ) {
// [\s\S] matches _anything_ (newline or space)
var re = /([\s\S]+?)($|\n(?:\s*\n|$)+)/g,
@@ -182,26 +239,29 @@ Markdown.prototype.split_blocks = function splitBlocks( input, startLine ) {
};
/**
- * Markdown#processBlock( block, next ) -> undefined | [ JsonML, ... ]
- * - block (String): the block to process
- * - next (Array): the following blocks
- *
- * Process `block` and return an array of JsonML nodes representing `block`.
- *
- * It does this by asking each block level function in the dialect to process
- * the block until one can. Succesful handling is indicated by returning an
- * array (with zero or more JsonML nodes), failure by a false value.
- *
- * Blocks handlers are responsible for calling [[Markdown#processInline]]
- * themselves as appropriate.
- *
- * If the blocks were split incorrectly or adjacent blocks need collapsing you
- * can adjust `next` in place using shift/splice etc.
- *
- * If any of this default behaviour is not right for the dialect, you can
- * define a `__call__` method on the dialect that will get invoked to handle
- * the block processing.
- */
+Process `block` and return an array of JsonML nodes representing `block`.
+
+It does this by asking each block level function in the dialect to process
+the block until one can. Succesful handling is indicated by returning an
+array (with zero or more JsonML nodes), failure by a false value.
+
+Blocks handlers are responsible for calling [[Markdown#processInline]]
+themselves as appropriate.
+
+If the blocks were split incorrectly or adjacent blocks need collapsing you
+can adjust `next` in place using shift/splice etc.
+
+If any of this default behaviour is not right for the dialect, you can
+define a `__call__` method on the dialect that will get invoked to handle
+the block processing.
+
+@method processBlock
+@protected
+@private
+@static
+@param block {String} the block to process
+@param next {Array} following blocks
+**/
Markdown.prototype.processBlock = function processBlock( block, next ) {
var cbs = this.dialect.block,
ord = cbs.__order__;
@@ -226,17 +286,28 @@ Markdown.prototype.processBlock = function processBlock( block, next ) {
return [];
};
+/**
+Process a block inline based on the selected dialect.
+
+@method processInline
+@private
+@param block {Object} A rough block to process
+**/
Markdown.prototype.processInline = function processInline( block ) {
return this.dialect.inline.__call__.call( this, String( block ) );
};
/**
- * Markdown#toTree( source ) -> JsonML
- * - source (String): markdown source to parse
- *
- * Parse `source` into a JsonML tree representing the markdown document.
- **/
-// custom_tree means set this.tree to `custom_tree` and restore old value on return
+Parse `source` into a JsonML tree representing the markdown document.
+Passing in `custom_tree` in the options means set `this.tree` to
+`custom_tree` and restore old value on return.
+
+@method toTree
+@protected
+@static
+@param source {String} markdown source to parse.
+@param custom_root {Object} A previous tree to append to
+**/
Markdown.prototype.toTree = function toTree( source, custom_root ) {
var blocks = source instanceof Array ? source : this.split_blocks( source );
@@ -286,20 +357,23 @@ Markdown.prototype.loop_re_over_block = function( re, block, cb ) {
};
/**
- * Markdown.dialects
- *
- * Namespace of built-in dialects.
- **/
+Namespace of built-in dialects.
+
+@property Markdown.dialects
+@type Object
+**/
Markdown.dialects = {};
/**
- * Markdown.dialects.Gruber
- *
- * The default dialect that follows the rules set out by John Gruber's
- * markdown.pl as closely as possible. Well actually we follow the behaviour of
- * that script which in some places is not exactly what the syntax web page
- * says.
- **/
+
+The default dialect that follows the rules set out by John Gruber's
+markdown.pl as closely as possible. Well actually we follow the behaviour of
+that script which in some places is not exactly what the syntax web page
+says.
+
+@property Markdown.dialects.Gruber
+@type Object
+**/
Markdown.dialects.Gruber = {
block: {
atxHeader: function atxHeader( block, next ) {
@@ -1111,6 +1185,13 @@ Markdown.subclassDialect = function( d ) {
Markdown.buildBlockOrder ( Markdown.dialects.Gruber.block );
Markdown.buildInlinePatterns( Markdown.dialects.Gruber.inline );
+/**
+
+Alternative using the [Maruku](http://maruku.rubyforge.org/) dialect of Markdown.
+
+@property Markdown.dialects.Maruku
+@type Object
+**/
Markdown.dialects.Maruku = Markdown.subclassDialect( Markdown.dialects.Gruber );
Markdown.dialects.Maruku.processMetaHash = function processMetaHash( meta_string ) {
@@ -1364,18 +1445,21 @@ function extract_attr( jsonml ) {
/**
- * renderJsonML( jsonml[, options] ) -> String
- * - jsonml (Array): JsonML array to render to XML
- * - options (Object): options
- *
- * Converts the given JsonML into well-formed XML.
- *
- * The options currently understood are:
- *
- * - root (Boolean): wether or not the root node should be included in the
- * output, or just its children. The default `false` is to not include the
- * root itself.
- */
+
+Converts the given JsonML into well-formed XML.
+
+The options currently understood are:
+
+* root (Boolean): wether or not the root node should be included in the
+ output, or just its children. The default `false` is to not include the
+ root itself.
+
+@method renderJsonML
+@static
+@private
+@param jsonml {Array} JsonML array to render to XML
+@param options {Object} options to render
+**/
expose.renderJsonML = function( jsonml, options ) {
options = options || {};
// include the root element in the rendered output?
Something went wrong with that request. Please try again.