` elements. Useful for allowing inline markdown\nformatting in one-line fields where paragraphs, lists, etc. are\ndisallowed.\n\n#### `SimpleMarkdown.defaultImplicitParse(source)`\n\nParses `source` as block if it ends with `\\n\\n`, or inline if not.\n\n#### `SimpleMarkdown.defaultOutput(syntaxTree)`\n\nReturns React-renderable output for `syntaxTree`.\n\n*Note: raw html output will be coming soon*\n\n\n## Extension Overview\n\nElements in simple-markdown are generally created from rules.\nFor parsing, rules must specify `match` and `parse` methods.\nFor output, rules must specify a `react` or `html` method\n(or both), depending on which outputter you create afterwards.\n\nHere is an example rule, a slightly modified version of what\nsimple-markdown uses for parsing **strong** (**bold**) text:\n\n```javascript\n strong: {\n match: function(source, state, lookbehind) {\n return /^\\*\\*([\\s\\S]+?)\\*\\*(?!\\*)/.exec(source);\n },\n parse: function(capture, recurseParse, state) {\n return {\n content: recurseParse(capture[1], state)\n };\n },\n react: function(node, recurseOutput) {\n return React.DOM.strong(null, recurseOutput(node.content));\n },\n html: function(node, recurseOutput) {\n return '' + recurseOutput(node.content) + '';\n },\n },\n```\n\nLet's look at those three methods in more detail.\n\n#### `match(source, state, lookbehind)`\n\nsimple-markdown calls your `match` function to determine whether the\nupcoming markdown source matches this rule or not.\n\n`source` is the upcoming source, beginning at the current position of\nparsing (source[0] is the next character).\n\n`state` is a mutable state object to allow for more complicated matching\nand parsing. The most common field on `state` is `inline`, which all of\nthe default rules set to true when we are in an inline scope, and false\nor undefined when we are in a block scope.\n\n**DEPRECATED - use `state.prevCapture` instead.** `lookbehind` is the string previously captured at this parsing level, to\nallow for lookbehind. For example, lists check that lookbehind ends with\n`/^$|\\n *$/` to ensure that lists only match at the beginning of a new\nline.\n\nIf this rule matches, `match` should return an object, array, or\narray-like object, which we'll call `capture`, where `capture[0]`\nis the full matched source, and any other fields can be used in the\nrule's `parse` function. The return value from `Regexp.prototype.exec`\nfits this requirement, and the common use case is to return the result\nof `someRegex.exec(source)`.\n\nIf this rule does not match, `match` should return null.\n\nNOTE: If you are using regexes in your match function, your regex\nshould always begin with `^`. Regexes without leading `^`s can\ncause unexpected output or infinite loops.\n\n#### `parse(capture, recurseParse, state)`\n\n`parse` takes the output of `match` and transforms it into a syntax\ntree node object, which we'll call `node` here.\n\n`capture` is the non-null result returned from match.\n\n`recurseParse` is a function that can be called on sub-content and\nstate to recursively parse the sub-content. This returns an array.\n\n`state` is the mutable state threading object, which can be examined\nor modified, and should be passed as the third argument to any\n`recurseParse` calls.\n\nFor example, to parse inline sub-content, you can add `inline: true`\nto state, or `inline: false` to force block parsing (to leave the\nparsing scope alone, you can just pass `state` with no modifications).\nFor example:\n\n```javascript\n var innerText = capture[1];\n recurseParse(innerText, _.defaults({\n inline: true\n }, state));\n```\n\n`parse` should return a `node` object, which can have custom fields\nthat will be passed to `output`, below. The one reserved field is\n`type`, which designates the type of the node, which will be used\nfor output. If no type is specified, simple-markdown will use the\ncurrent rule's type (the common case). If you have multiple ways\nto parse a single element, it can be useful to have multiple rules\nthat all return nodes of the same type.\n\n#### `react(node, recurseOutput, state)`\n\n`react` takes a syntax tree `node` and transforms it into\nReact-renderable output.\n\n`node` is the return value from `parse`, which has a type\nfield of the same type as the current rule, as well as any\ncustom fields created by `parse`.\n\n`recurseOutput` is a function to recursively output sub-tree\nnodes created by using `recurseParse` in `parse`.\n\n`state` is the mutable state threading object, which can be\nexamined or modified, and should be passed as the second\nargument to any recurseOutput calls.\n\nThe simple-markdown API contains several helper methods for\ncreating rules, as well as methods for creating parsers and\noutputters from rules.\n\n## Extension API\n\nsimple-markdown includes access to the default list of rules,\nas well as several functions to allow you to create parsers and\noutputters from modifications of those default rules, or even\nfrom a totally custom rule list.\n\nThese functions are separated so that you can customize\nintermediate steps in the parsing/output process, if necessary.\n\n#### `SimpleMarkdown.defaultRules`\n\nThe default rules, specified as an object, where the keys are\nthe rule types, and the values are objects containing `order`,\n`match`, `parse`, `react`, and `html` fields (these rules can\nbe used for both parsing and outputting).\n\n#### `SimpleMarkdown.parserFor(rules)`\n\nTakes a `rules` object and returns a parser for the rule types\nin the rules object, in order of increasing `order` fields,\nwhich must be present and a finite number for each rule.\nIn the case of order field ties, rules are ordered\nlexicographically by rule name. Each of the rules in the `rules`\nobject must contain a `match` and a `parse` function.\n\n#### `SimpleMarkdown.outputFor(rules, key)`\n\nTakes a `rules` object and a `key` that indicates which key in\nthe rules object is mapped to the function that generates the\noutput type you want. This will be `'react'` or `'html'` unless\nyou are defining a custom output type.\n\nIt returns a function that outputs a single syntax tree node of\nany type that is in the `rules` object, given a node and a\nrecursive output function.\n\n#### Putting it all together\n\nGiven a set of rules, one can create a single function\nthat takes an input content string and outputs a\nReact-renderable as follows. Note that since many rules\nexpect blocks to end in `\"\\n\\n\"`, we append that to source\ninput manually, in addition to specifying `inline: false`\n(`inline: false` is technically optional for all of the\ndefault rules, which assume `inline` is false if it is\nundefined).\n\n```javascript\nvar rules = {\n ...SimpleMarkdown.defaultRules,\n paragraph: {\n ...SimpleMarkdown.defaultRules.paragraph,\n react: (node, output, state) => {\n return
{output(node.content, state)}
;\n }\n }\n};\n\nvar parser = SimpleMarkdown.parserFor(rules);\nvar reactOutput = SimpleMarkdown.outputFor(rules, 'react'));\nvar htmlOutput = SimpleMarkdown.outputFor(rules, 'html'));\n\nvar blockParseAndOutput = function(source) {\n // Many rules require content to end in \\n\\n to be interpreted\n // as a block.\n var blockSource = source + \"\\n\\n\";\n var parseTree = parser(blockSource, {inline: false});\n var outputResult = htmlOutput(parseTree);\n // Or for react output, use:\n // var outputResult = reactOutput(parseTree);\n return outputResult;\n};\n```\n\n## LICENSE\nMIT. See the LICENSE file for text.\n","_attachments":{},"homepage":"https://github.com/Khan/perseus#readme","bugs":{"url":"https://github.com/Khan/perseus/issues"},"license":"MIT"}