Non-Printable Material

    @metalsmith/markdown

    1.6.0 • Public • Published

    @metalsmith/markdown

    A Metalsmith plugin to render markdown files to HTML, using Marked.

    metalsmith: core plugin npm: version ci: build code coverage license: MIT

    Installation

    NPM:

    npm install @metalsmith/markdown

    Yarn:

    yarn add @metalsmith/markdown

    Usage

    const markdown = require('@metalsmith/markdown')
    
    metalsmith.use(
      markdown({
        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
      })
    )

    Options

    @metalsmith/markdown is powered by Marked, and you can pass any of the Marked options to it, including the 'pro' options: renderer, tokenizer, walkTokens and extensions.

    You can render markdown to HTML in file metadata keys by specifying the keys option.
    The keys option also supports dot-delimited key-paths.

    metalsmith.use(
      markdown({
        keys: ['html_desc', 'nested.data']
      })
    )

    You can even render all keys at a certain path by setting the wildcard option and using a globstar * in the keypaths.
    This is especially useful for arrays like the faq below:

    metalsmith.use(
      markdown({
        wildcard: true,
        keys: ['html_desc', 'nested.data', 'faq.*.*']
      })
    )

    A file page.md with front-matter:

    ---
    html_desc: A **markdown-enabled** _description_
    nested:
      data: '#metalsmith'
    faq:
      - q: '**Question1?**'
        a: _answer1_
      - q: '**Question2?**'
        a: _answer2_
    ---

    would be transformed into:

    {
      "html_desc": "A <strong>markdown-enabled</strong> <em>description</em>\n",
      "nested": {
        "data": "<h1 id=\"metalsmith\">metalsmith</h1>\n"
      },
      "faq": [
        { "q": "<p><strong>Question1?</strong></p>\n", "a": "<p><em>answer1</em></p>\n"},
        { "q": "<p><strong>Question2?</strong></p>\n", "a": "<p><em>answer2</em></p>\n"}
      ],

    Notes about the wildcard

    • It acts like the single bash globstar. If you specify * this would only match the properties at the first level of the metadata.
    • If a wildcard keypath matches a key whose value is not a string, it will be ignored.
    • It is set to false by default because it can incur some overhead if it is applied too broadly.

    Custom markdown rendering

    You can use a custom renderer by using marked.Renderer()

    const markdown = require('@metalsmith/markdown')
    const marked = require('marked')
    const markdownRenderer = new marked.Renderer()
    
    markdownRenderer.image = function (href, title, text) {
      return `
      <figure>
        <img src="${href}" alt="${title}" title="${title}" />
        <figcaption>
          <p>${text}</p>
        </figcaption>
      </figure>`
    }
    
    metalsmith.use(
      markdown({
        renderer: markdownRenderer,
        pedantic: false,
        gfm: true,
        tables: true,
        breaks: false,
        sanitize: false,
        smartLists: true,
        smartypants: false,
        xhtml: false
      })
    )

    CLI Usage

    Add @metalsmith/markdown key to your metalsmith.json plugins key

    {
      "plugins": {
        "@metalsmith/markdown": {
          "pedantic": false,
          "gfm": true,
          "tables": true,
          "breaks": false,
          "sanitize": false,
          "smartLists": true,
          "smartypants": false,
          "xhtml": false
        }
      }
    }

    License

    MIT

    Install

    npm i @metalsmith/markdown

    DownloadsWeekly Downloads

    313

    Version

    1.6.0

    License

    MIT

    Unpacked Size

    11.3 kB

    Total Files

    5

    Last publish

    Collaborators

    • webketje
    • ismay
    • woodyrew