From 9dacd6685720b955db015ad79bc8bb4f9ba56b74 Mon Sep 17 00:00:00 2001 From: Josh Bruce Date: Sun, 25 Feb 2018 15:17:16 -0500 Subject: [PATCH] Add advanced usage --- README.md | 274 +++------------------------------------------- USAGE_ADVANCED.md | 180 ++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+), 260 deletions(-) create mode 100644 USAGE_ADVANCED.md diff --git a/README.md b/README.md index f2fb2226..8d38d5ec 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Marked is 1. built for speed.* 2. a low-level markdown compiler that allows frequent parsing of large chunks of markdown without caching or blocking for long periods of time.** 3. light-weight while implementing all markdown features from the supported flavors & specifications.*** -4. available as a command line interface and running in client- or server-side JavaScript projects. +4. available as a command line interface (CLI) and running in client- or server-side JavaScript projects. - * Still working on metrics for comparative analysis and definition. - ** As few dependencies as possible. @@ -26,48 +26,25 @@ Marked is
  • License
    • -

    Install

    +

    Installation

    -``` bash -npm install marked --save -``` +**CLI:** `npm install -g marked` -or if you want to use the `marked` CLI tool (not necessary when using npm run-scripts): - -``` bash -npm install -g marked -``` +**In-browser:** `npm install marked --save`

    Usage

    -Minimal usage: +**CLI** -```js -var marked = require('marked'); -console.log(marked('I am using __markdown__.')); -// Outputs:

    I am using markdown.

    +``` bash +$ marked -o hello.html +hello world +^D +$ cat hello.html +

    hello world

    ``` -Example setting options: - -```js -var marked = require('marked'); -marked.setOptions({ - renderer: new marked.Renderer(), - gfm: true, - tables: true, - breaks: false, - pedantic: false, - sanitize: false, - smartLists: true, - smartypants: false, - xhtml: false -}); - -console.log(marked('I am using __markdown__.')); -``` - -### Browser +**Browser** ```html @@ -75,7 +52,7 @@ console.log(marked('I am using __markdown__.')); Marked in the browser - +
    @@ -87,221 +64,8 @@ console.log(marked('I am using __markdown__.')); ``` -

    marked(markdownString [,options] [,callback])

    -### markdownString - -Type: `string` - -String of markdown source to be compiled. - -### options - -Type: `object` - -Hash of options. Can also be set using the `marked.setOptions` method as seen -above. - -### callback - -Type: `function` - -Function called when the `markdownString` has been fully parsed when using -async highlighting. If the `options` argument is omitted, this can be used as -the second argument. - -

    Options

    - -### highlight - -Type: `function` - -A function to highlight code blocks. The first example below uses async highlighting with -[node-pygmentize-bundled][pygmentize], and the second is a synchronous example using -[highlight.js][highlight]: - -```js -var marked = require('marked'); - -var markdownString = '```js\n console.log("hello"); \n```'; - -// Async highlighting with pygmentize-bundled -marked.setOptions({ - highlight: function (code, lang, callback) { - require('pygmentize-bundled')({ lang: lang, format: 'html' }, code, function (err, result) { - callback(err, result.toString()); - }); - } -}); - -// Using async version of marked -marked(markdownString, function (err, content) { - if (err) throw err; - console.log(content); -}); - -// Synchronous highlighting with highlight.js -marked.setOptions({ - highlight: function (code) { - return require('highlight.js').highlightAuto(code).value; - } -}); - -console.log(marked(markdownString)); -``` - -#### highlight arguments - -`code` - -Type: `string` - -The section of code to pass to the highlighter. - -`lang` - -Type: `string` - -The programming language specified in the code block. - -`callback` - -Type: `function` - -The callback function to call when using an async highlighter. - -### renderer - -Type: `object` -Default: `new Renderer()` - -An object containing functions to render tokens to HTML. - -#### Overriding renderer methods - -The renderer option allows you to render tokens in a custom manner. Here is an -example of overriding the default heading token rendering by adding an embedded anchor tag like on GitHub: - -```javascript -var marked = require('marked'); -var renderer = new marked.Renderer(); - -renderer.heading = function (text, level) { - var escapedText = text.toLowerCase().replace(/[^\w]+/g, '-'); - - return '' + - text + ''; -}; - -console.log(marked('# heading+', { renderer: renderer })); -``` -This code will output the following HTML: -```html -

    - - - - heading+ -

    -``` - -#### Block level renderer methods - -- code(*string* code, *string* language) -- blockquote(*string* quote) -- html(*string* html) -- heading(*string* text, *number* level) -- hr() -- list(*string* body, *boolean* ordered) -- listitem(*string* text) -- paragraph(*string* text) -- table(*string* header, *string* body) -- tablerow(*string* content) -- tablecell(*string* content, *object* flags) - -`flags` has the following properties: - -```js -{ - header: true || false, - align: 'center' || 'left' || 'right' -} -``` - -#### Inline level renderer methods - -- strong(*string* text) -- em(*string* text) -- codespan(*string* code) -- br() -- del(*string* text) -- link(*string* href, *string* title, *string* text) -- image(*string* href, *string* title, *string* text) -- text(*string* text) - -### gfm - -Type: `boolean` -Default: `true` - -Enable [GitHub flavored markdown][gfm]. - -### tables - -Type: `boolean` -Default: `true` - -Enable GFM [tables][tables]. -This option requires the `gfm` option to be true. - -### breaks - -Type: `boolean` -Default: `false` - -Enable GFM [line breaks][breaks]. -This option requires the `gfm` option to be true. - -### pedantic - -Type: `boolean` -Default: `false` - -Conform to obscure parts of `markdown.pl` as much as possible. Don't fix any of -the original markdown bugs or poor behavior. - -### sanitize - -Type: `boolean` -Default: `false` - -Sanitize the output. Ignore any HTML that has been input. - -### smartLists - -Type: `boolean` -Default: `true` - -Use smarter list behavior than the original markdown. May eventually be -default with the old behavior moved into `pedantic`. - -### smartypants - -Type: `boolean` -Default: `false` - -Use "smart" typographic punctuation for things like quotes and dashes. - -### xhtml - -Type: `boolean` -Default: `false` - -Self-close the tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML. +Marked offers [advanced configurations](https://github.com/markedjs/marked/blob/master/USAGE_ADVANCED.md) and extensibility as well.

    Access to lexer and parser

    @@ -319,16 +83,6 @@ console.log(tokens); console.log(lexer.rules); ``` -

    CLI

    - -``` bash -$ marked -o hello.html -hello world -^D -$ cat hello.html -

    hello world

    -``` -

    Benchmarks

    node v8.9.4 diff --git a/USAGE_ADVANCED.md b/USAGE_ADVANCED.md new file mode 100644 index 00000000..d8e3caf2 --- /dev/null +++ b/USAGE_ADVANCED.md @@ -0,0 +1,180 @@ +## The `marked` function + +```js +marked(markdownString [,options] [,callback]) +``` + +|Argument |Type |Notes | +|:--------------------:|:-----------:|:---------------------------------------------------------------------------------------------------:| +|markdownString |`string` |String of markdown source to be compiled. | +|options|`object`|Hash of options. Can also use `marked.setOptions`. | +|callback |`function` |Called when `markdownString` has been parsed. Can be used as second argument if no `options` present.| + +### Alternative + +```js +// Create reference instance +var myMarked = require('marked'); + +// Set options +// `highlight` example uses `highlight.js` +myMarked.setOptions({ + renderer: new marked.Renderer(), + highlight: function(code) { + return require('highlight.js').highlightAuto(code).value; + }, + pedantic: false, + gfm: true, + tables: true, + breaks: false, + sanitize: false, + smartLists: true, + smartypants: false, + xhtml: false +}); + +// Compile +console.log(myMarked('I am using __markdown__.')); +``` + +

    Options

    + +|Member |Type |Notes | +|:---------:|:--------:|:---------------------------------------------------------------------------------------------------------------------------:| +|highlight |`function`|A function to highlight code blocks. | +|renderer |`object` |An object containing functions to render tokens to HTML. Default: `new Renderer()` | +|pedantic |`boolean` |Conform to obscure parts of `markdown.pl` as much as possible. Don't fix original markdown bugs or behavior. Default: `false`| +|gfm |`boolean` |Use approved [GitHub Flavored Markdown (GFM) specification](https://github.github.com/gfm/). | +|tables |`boolean` |Use [GFM Tables extension](https://github.github.com/gfm/#tables-extension-). Requires `gfm` be `true`. | +|breaks |`boolean` |Use GFM [hard](https://github.github.com/gfm/#hard-line-breaks) and [soft](https://github.github.com/gfm/#soft-line-breaks) line breaks. Requires `gfm` be `true`. Default: `false`| +|sanitize |`boolean` |Ignore HTML passed into `markdownString` (sanitize the input). Default: `false` | +|smartlists |`boolean` |Use smarter list behavior than those found in `markdown.pl`. Default: `true` | +|smartypants|`boolean` |Use "smart" typographic punctuation for things like quotes and dashes. | +|xhtml |`boolean` |Self-close the tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML. Default: `false` | + +### highlight + +Captured...?? + + The first example below uses async highlighting with +[node-pygmentize-bundled][pygmentize], and the second is a synchronous example using +[highlight.js][highlight]: + +```js +var marked = require('marked'); + +var markdownString = '```js\n console.log("hello"); \n```'; + +// Async highlighting with pygmentize-bundled +marked.setOptions({ + highlight: function (code, lang, callback) { + require('pygmentize-bundled')({ lang: lang, format: 'html' }, code, function (err, result) { + callback(err, result.toString()); + }); + } +}); + +// Using async version of marked +marked(markdownString, function (err, content) { + if (err) throw err; + console.log(content); +}); + +// Synchronous highlighting with highlight.js +marked.setOptions({ + highlight: function (code) { + return require('highlight.js').highlightAuto(code).value; + } +}); + +console.log(marked(markdownString)); +``` + +#### highlight arguments + +`code` + +Type: `string` + +The section of code to pass to the highlighter. + +`lang` + +Type: `string` + +The programming language specified in the code block. + +`callback` + +Type: `function` + +The callback function to call when using an async highlighter. + +### renderer + +#### Overriding renderer methods + +The renderer option allows you to render tokens in a custom manner. Here is an +example of overriding the default heading token rendering by adding an embedded anchor tag like on GitHub: + +```javascript +var marked = require('marked'); +var renderer = new marked.Renderer(); + +renderer.heading = function (text, level) { + var escapedText = text.toLowerCase().replace(/[^\w]+/g, '-'); + + return '' + + text + ''; +}; + +console.log(marked('# heading+', { renderer: renderer })); +``` +This code will output the following HTML: +```html +

    + + + + heading+ +

    +``` + +#### Block level renderer methods + +- code(*string* code, *string* language) +- blockquote(*string* quote) +- html(*string* html) +- heading(*string* text, *number* level) +- hr() +- list(*string* body, *boolean* ordered) +- listitem(*string* text) +- paragraph(*string* text) +- table(*string* header, *string* body) +- tablerow(*string* content) +- tablecell(*string* content, *object* flags) + +`flags` has the following properties: + +```js +{ + header: true || false, + align: 'center' || 'left' || 'right' +} +``` + +#### Inline level renderer methods + +- strong(*string* text) +- em(*string* text) +- codespan(*string* code) +- br() +- del(*string* text) +- link(*string* href, *string* title, *string* text) +- image(*string* href, *string* title, *string* text) +- text(*string* text) +