Handles image references involved in markdown files during the webpack processing.
Last updated 2 years ago by lucsorel .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install markdown-image-loader 
SYNC missed versions from official npm registry.
Markdown logo Webpack logo

Markdown image loader

Handles image references involved in markdown files during the webpack processing.

Highly inspired from the Webpack: A simple loader article by Michael "Z" Goddard, rewritten with some ES6 flavor, use-case documentation and unit testing.


  • the loader does not impact references to online images (eg: image path starting with http://, https:// or //)
  • the loader handles markdown image references with a title


Install the markdown-image-loader along other webpack development dependencies:

# via yarn
yarn add -D webpack file-loader markdown-image-loader

# via npm
npm i -D webpack file-loader markdown-image-loader

How it works

In the webpack process, this loader etracts image references of markdown documents with a regular expression, then converts them into image file requirements so that the file-loader can process them in your build chain.

Use cases

Web-based slideshows

This loader was originally designed to quickly setup web-based slideshows using markdown to build the content, webpack to produce the static files and webpack-dev-server to display the slideshow with live-reload, which can be interesting when editing the content while interacting with the audience.

Two full setups are given in the examples/ folder of this repository:

Both slideshow examples share the same philosophy, adapted to the technical choices of each framework:

The folder structure of such projects is:

dist // folder containing the static files generated by the webpack build (and served by webpack-dev-server)
┣ index.html
┣ [your slideshow app name]-slideshow.js
┣ slides.css // your personal style additions
┣ fonts // folder containing the fonts required in the slides.css file, if any
┣ img // folder containing the images referenced in
┃ ┗ markdown-logo.svg, webpack-logo.svg, etc.
webpack.config.js // involves this markdown-image-loader and the file-loader
package.json // devDependencies to make the slideshow framework and webpack work together
  • src/index.html:
<!doctype html>
    <meta charset="utf-8">
    <!-- the title header can be dynamically set by bundled-app.js -->
    <title>My slideshow</title>
    <!-- RemarkJS expects the markdown content to be included by the webapp this way -->
    <textarea id="source" style="display: none"></textarea>
    <!-- RevealJS expects the markdown content to be included by the webapp this way -->
    <div class="reveal">
      <div class="slides">
        <!-- horizontal and vertical separators are my choices, tune them as you want -->
        <section data-markdown data-separator="^---" data-separator-vertical="^--">
          <textarea id="source" data-template></textarea>

    <!-- the bundled webapp will be injected here by the html-webpack-plugin -->
  • src/[slideshow app name]-slideshow.js:
// customize your CSS here

// loads the markdown content with the markdown-image-loader (which processes its image references)
document.getElementById('source').innerHTML = require('./')

// starts the slideshow with a specific configuration object
remark.create({ ... })
// or
Reveal.initialize({ ... })
  • src/ (each slideshow engine has its specific syntax, see the files in the examples):
# Slide 1 with a jpg reference



# Slide 2 with an inline png reference

In line ![test2](img/test2.png) image reference.
  • webpack.config.js. Loaders defined in the module.rules section are called from bottom to top: the file-loader must be called after the markdown-image-loader produces new file requirements: :
const path = require('path')

module.exports = {
  entry: path.join(__dirname, 'src', '[slideshow app name]-slideshow.js'),
  output: {
    filename: 'bundled-app.js',
    path: path.join(__dirname, 'dist')
  module: {
    rules: [
        test: /\.(svg|png|jpg|gif)$/,
        use: [
            loader: 'file-loader',
            options: {} // produces {hash}.[ext] files by default
        test: /\.(md|markdown)$/,
        use: 'markdown-image-loader'
  • package.json. Use the to produce the static files ready to be served in production, for which you must include these mandatory dependencies in your project: webpack, file-loader and markdown-image-loader. You can optionally include the webpack-dev-server to serve your slideshow with live-reload with the scripts.start command.
  "scripts": {
    "build": "rm -rf dist && webpack",
    "start": "webpack-dev-server",
    "lint": "standard"
  "devDependencies": {
    "file-loader": "...",
    "markdown-image-loader": "...",
    "webpack": "...",
    "webpack-dev-server": "..."

The outputs generated in the dist folder will be:

  • the bundled-app.js file, handling the markdown content as follows:
// ...
/* 0 */
/***/ (function(module, exports, __webpack_require__) {
module.exports = [
"# Slide 1 with a jpg reference\n\n",
"![test1](" + __webpack_require__(1) + ")",
"\n\n---\n\n# Slide 2 with an inline png reference\n\nIn line ",
"![test2](" + __webpack_require__(2) + ")",
" image reference.\n"
/***/ }),
/* 1 */
/***/ (function(module, exports, __webpack_require__) {
module.exports = __webpack_require__.p + "05bf210f71dda8913b3e9ac296da171f.jpg";
/***/ }),
/* 2 */
/***/ (function(module, exports, __webpack_require__) {
module.exports = __webpack_require__.p + "e3989c3353cceb13f5bb1ecf343f22a6.png";
/***/ })
  • the images referenced by the markdown content, processed by the file-loader plugin:
    • the dist/05bf210f71dda8913b3e9ac296da171f.jpg file (referenced in slide 1)
    • the dist/e3989c3353cceb13f5bb1ecf343f22a6.png file (referenced in slide 2)

Unit tests

Unit tests can be run with the npm test command.

Despite these efforts, should you find an issue or spot a vital feature, you are welcome to report bugs and submit code requests!

Change log

  • 2.0.0: [config] dependencies update, for webpack 3.x and 4.x. Webpack configurations for RemarkJS and RevealJS slideshows in the /examples folder have been updated for Webpack 4.x support
  • 1.0.5: [feature] the loader handles image references with an optional title
  • 1.0.4: [doc] added sample slideshows for RemarkJS and RevealJS in the /examples folder
  • 1.0.3: [perf] made the loader outputs cacheable, [doc] added this change log section
  • 1.0.2: [fix] removed the comma surrounding image requirements in the exported module content
  • 1.0.1: [fix] the loader should not not require URLed-image references
  • 1.0.0: initial release with unit-tests and documentation, for webpack 3.x


May be freely distributed under the MIT license.

Copyright (c) 2017-2018 Luc Sorel-Giffo

Current Tags

  • 2.0.0                                ...           latest (2 years ago)

6 Versions

  • 2.0.0                                ...           2 years ago
  • 1.0.5                                ...           3 years ago
  • 1.0.4                                ...           3 years ago
  • 1.0.2                                ...           3 years ago
  • 1.0.1                                ...           3 years ago
  • 1.0.0                                ...           3 years ago
Maintainers (1)
Today 4
This Week 7
This Month 18
Last Day 1
Last Week 4
Last Month 24
Dependencies (0)
Dev Dependencies (3)

Copyright 2014 - 2016 © |