Options

The loader accepts some options to configure.

• Mode
  • Default
  • Raw markdown
  • Metadata
  • React component
  • Vue component
  • Vue's render functions
• Markdown compilation
  • Configure markdown-it
  • Custom compiler
• Vue Compilation
  • Class name for root div element
  • Assets transformation
• React Compilation
  • Class name for root div element

Mode

options.mode option requests what you can import from frontmatter markdown data.

This option is added since 2.0.0. So see Migration Guide if you are using 1.x.

import Mode from 'frontmatter-markdown-loader/mode'

will provide constats. Mode.NAME_OF_MODE.

Plain string is available

You may not want to import frontmatter-markdown-loader/mode. Then you can just give string instead.

• Mode.HTML -> "html"
• Mode.BODY -> "body"
• Mode.META -> "meta"
• Mode.VUE_COMPONENT -> "vue-component"
• Mode.VUE_RENDER_FUNCTIONS -> "vue-render-functions"
• Mode.REACT -> "react-component"

Default

By default (When we don't specify any mode option), attributes and html are only available.

That's equivalent to:

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.HTML]
  }
}

import fm from "something.md"

fm.attributes //=> { subject: "Hello", tags: ["tag1", "tag2"] }
fm.html //=> "<h1>Title</h1>\n<p>message</p>\n"

Raw markdown

Mode.BODY gives raw string of Markdown part on frontmatter markdown.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.BODY]
  }
}

import fm from "something.md"

fm.attributes //=> { subject: "Hello", tags: ["tag1", "tag2"] }
fm.html //=> undefined
fm.body //=> "# Title\n\nmessage\n"

Metadata

Mode.META shows the metadata of the frontmatter markdown file.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.META]
  }
}

import fm from "something.md"

fm.meta //=> { resourcePath: "/somepath/something.md" }

Currently, only resourcePath is available which returns the path for the file in Webpack's context (opens new window).

React component

Mode.REACT requests to get function which renders React component.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.REACT]
  }
}

How to use in React

To see the usage of fm.react, see this page.

Vue component

Mode.VUE_COMPONENT requests to get the extendable component object of Vue.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.VUE_COMPONENT]
  }
}

import fm from "something.md"

fm.vue.component //=> The object which can be extendable as Vue component which has compiled HTML as the template

How to use in Vue

To see the usage of fm.vue.component, see this page.

Vue's render functions

Mode.VUE_RENDER_FUNCTIONS requests to get functions which are required to build Vue component. The function is having the compiled markdown as template of component.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.VUE_RENDER_FUNCTIONS]
  }
}

import fm from "something.md"

fm.vue.render
fm.vue.staticRenderFns

How to use in Vue

To see the usage of fm.vue.component, see this page.

import fm from "something.md"

fm.react //=> The function which is renderable as React component which has compiled markdown as template

How to use in React

To see the usage of fm.react, see this page.

Markdown compilation

Configure markdown-it

By default, the loader compiles markdown with markdown-it (opens new window) package. markdownIt option accepts the configuration to overwrite the default.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    markdownIt: {
      html: true,
      linkify: true,
      breaks: true
    }
  }
}

Refer markdown-it document for the further about the configuration (opens new window).

If markdownIt option isn't given, the loader uses markdown-it with just { html: true} as default. (If enabled Mode.REACT, { html: true, xhtmlOut: true })

markdonIt option also accepts the instance of a markdown-it rederer (with plugins (opens new window), for instance):

const markdownIt = require('markdown-it');
const markdownItPrism = require('markdown-it-prism'); // https://github.com/jGleitz/markdown-it-prism
{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    markdownIt: markdownIt({ html: true }).use(markdownItPrism)
  }
}

Btw, you need to load a stylesheet of Prism on your project (opens new window) for this case 😉

Custom compiler

To provide the custom compilation logic, markdown option accepts the callback function which takes the string of the markdown source for its argument. And expects the function returns compiled HTML.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    markdown: (body) => {
      return compileWithCustomCompiler(body)
    }
  }
}

Vue Compilation

Class name for root div element

vue.root option configures the class name of the root div element on Vue component's template.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.VUE_COMPONENT],
    vue: {
      root: 'dynamicContent'
    }
  }
}

By this configuration, the HTML in the below will be rendered by the Vue component.

<div class="dynamicContent">
  <h1>Title</h1>
  <p>Main sentences</p>
</div>

Default is frontmatter-markdown.

Assets transformation

vue.transformAssetUrls configures assets handling on HTML which expects an key-value pair with element's name for key, an attribute names as array for value.

Thus, { img: ['src', 'data-src'] } means, img tag's src attribute and data-src attribute.

Matched attributes are replaced with require(originalValue) on Vue template compilation. So, Webpack treats them as other resources. Typically, file-loader, url-loader gives Base 64 string, another path with asset's id. Vue CLI App (opens new window) and Nuxt.js (opens new window) works with this behavior harmonically.

Default is true which means:

{
  audio: 'src',
  video: ['src', 'poster'],
  source: 'src',
  img: 'src',
  image: ['xlink:href', 'href'],
  use: ['xlink:href', 'href']
}

Depends on the version of @vue/component-compiler-utils

audio: 'src' is added after @vue/component-compiler-utils@v3.1.0

This option will be merged with the default.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.VUE_COMPONENT],
    vue: {
      transformAssetUrls: {
        img: ['src', 'data-src']
      }
    }
  }
}

So, the configuration becomes eventually:

{
  audio: 'src',
  video: ['src', 'poster'],
  source: 'src',
- img: 'src',
+ img: ['src', 'data-src']
  image: ['xlink:href', 'href'],
  use: ['xlink:href', 'href']
}

To disable all completely, just give false.

React Compilation

Class name for root div element

react.root option configures the class name of the root div element on React component's HTML.

{
  test: /\.md$/,
  loader: 'frontmatter-markdown-loader',
  options: {
    mode: [Mode.REACT],
    react: {
      root: 'dynamicContent'
    }
  }
}

By this configuration, the HTML in the below will be rendered by the React component.

<div class="dynamicContent">
  <h1>Title</h1>
  <p>Main sentences</p>
</div>

Default is frontmatter-markdown.