simple-markdown

In simple-markdown, elements are created from rules. A rule is an object that defines how to identify, parse, and render a specific markdown pattern.

To create a custom extension, you must define a rule object with the following lifecycle methods:

1. match(source, state): Determines if the current source matches the rule. It should return a capture object (like the result of RegExp.exec) if successful, or null if not. Note: Regexes used in match should always begin with ^ to avoid infinite loops.
2. parse(capture, recurseParse, state): Transforms the capture into a syntax tree node. It uses recurseParse to handle nested content.
3. react(node, recurseOutput, state) OR html(node, recurseOutput, state): Transforms the syntax node into the final output format. You typically implement one or the other depending on whether you are building a React or HTML outputter.

To transform a raw string into React or HTML, follow these steps:

1. Define Rules: Create a rules object by spreading SimpleMarkdown.defaultRules and overriding specific rules if needed.
2. Initialize Parser: Create a parser using SimpleMarkdown.parserFor(rules).
3. Initialize Outputter: Create an output function using SimpleMarkdown.outputFor(rules, 'react') or SimpleMarkdown.outputFor(rules, 'html').
4. Process Input:
   • Append \n\n to the source string (many block rules require this trailing newline to trigger correctly).
   • Call the parser with {inline: false} to generate the syntax tree.
   • Pass the tree to the output function.

var rules = {
    ...SimpleMarkdown.defaultRules,
    paragraph: {
        ...SimpleMarkdown.defaultRules.paragraph,
        react: (node, output, state) => {
            return <p key={state.key}>{output(node.content, state)}</p>;
        }
    }
};

var parser = SimpleMarkdown.parserFor(rules);
var reactOutput = SimpleMarkdown.outputFor(rules, 'react');
var htmlOutput = SimpleMarkdown.outputFor(rules, 'html');

var blockParseAndOutput = function(source) {
    // Many rules require content to end in \n\n to be interpreted
    // as a block.
    var blockSource = source + "\n\n";
    var parseTree = parser(blockSource, {inline: false});
    var outputResult = htmlOutput(parseTree);
    // Or for react output, use:
    // var outputResult = reactOutput(parseTree);
    return outputResult;
};

To add a custom extension (e.g., an underline rule __text__), follow these steps:

1. Define a rule object with order, match, parse, and an output method (react or html).
2. Extend the default rules using the new rule.
3. Build a custom parser and outputter using SimpleMarkdown.parserFor and SimpleMarkdown.outputFor.

// 1. Define the rule
var underlineRule = {
  order: SimpleMarkdown.defaultRules.em.order - 0.5,
  match: function (source) {
    return /^__([SS]+?)__(?!_)/.exec(source);
  },
  parse: function (capture, parse, state) {
    return { content: parse(capture[1], state) };
  },
  html: function (node, output) {
    return "<u>" + output(node.content) + "</u>";
  }
};

// 2. Extend default rules
var rules = _.extend({}, SimpleMarkdown.defaultRules, {
  underline: underlineRule,
});

// 3. Build custom parser/outputter
var rawBuiltParser = SimpleMarkdown.parserFor(rules);
var parse = function (source) {
  return rawBuiltParser(source + "\n\n", { inline: false });
};
var htmlOutput = SimpleMarkdown.outputFor(rules, "html");

// Usage
var tree = parse("__hello__");
var html = htmlOutput(tree);

var underlineRule = {
  order: SimpleMarkdown.defaultRules.em.order - 0.5,
  match: function (source) {
    return /^__([\s\S]+?)__(?!_)/.exec(source);
  },
  parse: function (capture, parse, state) {
    return { content: parse(capture[1], state) };
  },
  html: function (node, output) {
    return "<u>" + output(node.content) + "</u>";
  },
};

var rules = _.extend({}, SimpleMarkdown.defaultRules, {
  underline: underlineRule,
});

var rawBuiltParser = SimpleMarkdown.parserFor(rules);
var parse = function (source) {
  var blockSource = source + "\n\n";
  return rawBuiltParser(blockSource, { inline: false });
};
var htmlOutput = SimpleMarkdown.outputFor(rules, "html");

var syntaxTree = parse("__hello underlines__");
var html = htmlOutput(syntaxTree);

Rules in simple-markdown can define how they are rendered into different formats by providing html or react properties.

• HTML Output: Provide an html function that takes (node, nestedOutput, state) and returns a string.
• React Output: Provide a react function that takes (node, nestedOutput, state) and returns a ReactElement.

When outputting arrays of nodes (like in the Array rule), the library automatically handles grouping adjacent text nodes to prevent unnecessary fragmentation.

// Example of a rule with both HTML and React output
const myRule = {
  order: 5,
  match: inlineRegex(/\*\*/),
  parse: (capture, parse, state) => ({ type: 'bold', content: capture[0] }),
  html: (node, output, state) => `<strong>${output(node.content, state)}</strong>`,
  react: (node, output, state) => reactElement('strong', state.key, { children: output(node.content, state) })
};

Detailed signatures for the methods within a rule object:

match(source, state, [lookbehind])

• source: The upcoming string starting at the current position.
• state: A mutable state object. state.inline is true in inline scope and false/undefined in block scope.
• lookbehind (Deprecated): The string previously captured. Use state.prevCapture instead.
• Returns: A capture object (e.g., from RegExp.exec) if matched, otherwise null.

parse(capture, recurseParse, state)

• capture: The non-null result returned from match.
• recurseParse: A function to recursively parse sub-content. Returns an array.
• state: The mutable state object.
• Returns: A node object. The type field is reserved and used for output.

react(node, recurseOutput, state) / html(node, recurseOutput, state)

• node: The object returned by parse.
• recurseOutput: A function to recursively output sub-tree nodes.
• state: The mutable state object.