mdimg

A tool that can be used to convert Markdown or HTML format text to an image.

How does it work?

First, the script calls marked to parse Markdown into a HTML document. Next, use Puppeteer to start a headless browser and render the document with preset HTML and CSS files. Finally, export our image through Puppeteer's screenshot API.

Preview

| Preview | HTML Template | CSS Template | Notes | | ------------------------------------------------------------------------ | ------------- | ------------ | ------------------------------------------------- | | | Default | Default | | | Default | Empty | Not using any CSS presets | | | Default | Github | | | Default | Github Dark | | | Words | Words | It is recommended to use with plain text only |

Requirements

This tool requires an LTS Node version (v12.0.0+).

Installation

CLI:

npm install -g mdimg

In Node.js project:

npm install mdimg

Usage

CLI

Example:

mdimg -i input.md -o output.png -w 600 --css github

mdimg will read text from input.md and convert it to an image file output.png.

When using the command, you must specify either -i (input file, recommended) or -t (directly input text).

When using -t to input Markdown text directly, escape characters will not be available. To fix this, for example, you should replace \n with <br>.

You can always call mdimg -h to get complete help.

In Node.js project

Import mdimg to your project:

const { convert2img } = require("mdimg");

// or use import
import { convert2img } from "mdimg";

Convert markdown text or file to image:

const convertRes = await convert2img({
  mdFile: "path/to/input.md",
  outputFilename: "path/to/output.png",
  width: 600,
  cssTemplate: "github",
});

console.log(`Convert to image successfully!\nFile: ${convertRes.data}`);

When using convert2img() method, you must specify either mdFile (input file) or mdText (directly input text).

Options:

| Argument | Type | Default | Notes | | -------------- | --------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | mdText | String | undefined | Input Markdown or HTML text directly. This option has no effect if mdFile is specified | | mdFile | String | undefined | Read Markdown or HTML text from a file | | outputFilename | String | ./mdimg_output/mdimg_${new Date()}.${type} | Output binary image filename. File type can be jpeg, png or webp. Available when encoding option is binary | | type | String | png | The file type of the image. Type can be one of jpeg, png or webp, defaults to png. Type will be inferred from outputFilename if available | | width | Number | 800 | The width of output image | | encoding | String | binary | The encoding of output image. Available value can be binary or base64. | | quality | Number | 100 | The quality of the image, between 0-100. Not applicable to png image. | | htmlTemplate | String | default | HTML rendering template. Available templates can be found in template/html | | cssTemplate | String | default | CSS rendering template. Available templates can be found in template/css | | log | Boolean | false | Show preset console log | | puppeteerProps | LaunchOptions | undefined | Launch options of Puppeteer |

Returns: Promise<object>

| Key | Value Type | Notes | | ---- | -------------------- | --------------------------------------------------------------------------------------------------------- | | data | string | Buffer | Buffer (encoding is binary) or a BASE64 encoded string (encoding is base64) with the output image | | path | string | The path of output iamge. Available when encoding is binary | | html | string | The rendered HTML document |

Custom template

Templates are stored in the template directory.

Now, if you run the following command:

mdimg -i input.md --html custom --css custom

The mdimg will read custom.html from template/html directory as HTML template and custom.css from template/css directory as CSS template to render the image of input.md.

HTML template

Create a new .html file in template/html directory.

There is only one rule you need to follow: an element with id mdimg-body wrapping an element with class markdown-body.

The simplest example:

<div id="mdimg-body">
  <div class="markdown-body" />
</div>

The mdimg will put the parsed HTML content in the element with class markdown-body (elements inside will be replaced), and finally generate the image for the whole element whose id is mdimg-body.

CSS template

Create a new .css file in template/css directory and then make your style!

For further development, it is recommended that write .scss or .sass files in the template/scss directory, and use the following command to generate CSS templates:

# Build .scss and .sass files
npm run rollup:sass

CSS templates with the corresponding name will be generated in template/css directory.

Development

git clone https://github.com/LolipopJ/mdimg.git
cd mdimg
yarn
# npm install

Lint

# Check .js syntax only
npm run lint
# Check and fix syntax
npm run prettier

Build

# Build .js, .scss and .sass files
npm run build

Test

# You should build before testing
# npm run build
npm run test

Inspired by

• md2img. Provided me the idea and a complete feasible solution.
• marked. Learned a possible method to write a JavaScript library.