@vipzhichengfork/pretty-markdown-pdf

Pretty Markdown PDF

Easy to use tool to convert a markdown file to a pretty looking PDF.

The majority of the code is based on the vscode-markdown-pdf Visual Studio Code extension, which provides the pretty styles and extra markdown features.

CAUTION

This package is a fork of pretty-markdown-pdf, I just fork it to update old dependencies and do a little fix, maybe later i will drop it to use the original, if the original getting better.

Features

Supports the following features

• Supports export from MD to PDF, HTML, PNG and JPEG

• Syntax highlighting

• emoji

• markdown-it-checkbox

• markdown-it-container

• PlantUML

  • markdown-it-plantuml

• Sample pdf file

• Sample html file

• Sample png file

• Sample jpeg file

markdown-it-container

INPUT

::: warning
*here be dragons*
:::

OUTPUT

<div class="warning">
<p><em>here be dragons</em></p>
</div>

markdown-it-plantuml

INPUT

@startuml
Bob -[#red]> Alice : hello
Alice -[#0000FF]->Bob : ok
@enduml

OUTPUT

Usage

Install this project from the NPM package repository:

npm install -g pretty-markdown-pdf

Command Line

To convert a markdown file to PDF, simply run:

pretty-md-pdf -i my-doc.md

Run with --help to see all the options available.

This will output a file my-doc.pdf in the directory where my-doc.md resides.

To specify an output path as my-exported-doc.pdf, run:

pretty-md-pdf -i my-doc.md -o my-exported-doc.pdf

Other Export Types

To specify an output type other than PDF, run:

pretty-md-pdf -i my-doc.md -t png

Javascript

You can programmatically call this package, example:

const prettyMdPdf = require("pretty-markdown-pdf")

// output to `my-doc.pdf`
prettyMdPdf.convertMdToPdf({ markdownFilePath: "my-doc.md" })

// specify an output file path
prettyMdPdf.convertMdToPdf({ markdownFilePath: "my-doc.md", outputFilePath: "output.pdf" })

// specify an output file type, outputs to `my-doc.html`
prettyMdPdf.convertMdToPdf({ markdownFilePath: "my-doc.md", outputFileType: "html" })

Configuration

Advanced configuration is done using a JSON file. By default the tools uses the one shipped with this package, which has defaults set.

To specify a config file when running the tool:

pretty-md-pdf -i my-doc.md -c /tmp/config.json

From JavaScript you can do:

prettyMdPdf.convertMdToPdf({ markdownFilePath: "my-doc.md", configFilePath: "/tmp/config.json")

Example

Below is the default config JSON file as an example:

{
    "type": [
        "pdf"
    ],
    "outputDirectory": "",
    "outputDirectoryRelativePathFile": false,
    "styles": [],
    "stylesRelativePathFile": false,
    "includeDefaultStyles": true,
    "highlight": true,
    "highlightStyle": "",
    "breaks": false,
    "emoji": true,
    "executablePath": "",
    "scale": 1,
    "displayHeaderFooter": true,
    "headerTemplate": "<div style=\"font-size: 9px; margin-left: 1cm;\"> <span class='title'></span></div> <div style=\"font-size: 9px; margin-left: auto; margin-right: 1cm; \"> <span class='date'></span></div>",
    "footerTemplate": "<div style=\"font-size: 9px; margin: 0 auto;\"> <span class='pageNumber'></span> / <span class='totalPages'></span></div>",
    "printBackground": true,
    "orientation": "portrait",
    "pageRanges": "",
    "format": "A4",
    "width": "",
    "height": "",
    "margin": "1cm",
    "quality": 100,
    "clip": {
        "height": null
    },
    "omitBackground": false
}

Options

Category	Option name
Save options	type
	outputDirectory
	outputDirectoryRelativePathFile
Styles options	styles
	stylesRelativePathFile
	includeDefaultStyles
Syntax highlight options	highlight
	highlightStyle
Markdown options	breaks
Emoji options	emoji
Configuration options	executablePath
Common Options	scale
PDF options	displayHeaderFooter
	headerTemplate
	footerTemplate
	printBackground
	orientation
	pageRanges
	format
	width
	height
	margin.top
	margin.bottom
	margin.right
	margin.left
PNG JPEG options	quality
	clip.x
	clip.y
	clip.width
	clip.height
	omitBackground

Save options

type

• Output format: pdf, html, png, jpeg
• Multiple output formats support
• Default: pdf

"type": [
  "pdf",
  "html",
  "png",
  "jpeg"
],

outputDirectory

• Output Directory
• All \ need to be written as \\ (Windows)

"outputDirectory": "C:\\work\\output",

Relative Paths

"outputDirectory": "~/output",

• If you set a directory with a relative path, it will be created if the directory does not exist
• If you set a directory with an absolute path, an error occurs if the directory does not exist

outputDirectoryRelativePathFile

• If outputDirectoryRelativePathFile option is set to true, the relative path set with outputDirectory is interpreted as relative from the file
• boolean. Default: false

Styles options

styles

• A list of local paths to the stylesheets to use from pretty-markdown-pdf
• If the file does not exist, it will be skipped
• All \ need to be written as \\ (Windows)

"styles": [
  "C:\\Users\\<USERNAME>\\Documents\\css",
  "/home/<USERNAME>/settings/css",
],

"styles": [
  "css",
],

"styles": [
  "~/.config/Code/User/css"
],

• Remote CSS (https://xxx/xxx.css) is applied correctly for JPG and PNG, but problems occur with PDF

"styles": [
  "https://xxx/css"
],

stylesRelativePathFile

• If stylesRelativePathFile option is set to true, the relative path set with styles is interpreted as relative from the file
• boolean. Default: false

includeDefaultStyles

• Enable the inclusion of default Markdown styles
• boolean. Default: true

Syntax highlight options

highlight

• Enable Syntax highlighting
• boolean. Default: true

highlightStyle

• Set the style file name. for example: github.css, monokai.css ...
• file name list
• demo site : https://highlightjs.org/static/demo/

"highlightStyle": "github.css",

Markdown options

breaks

• Enable line breaks
• boolean. Default: false

Emoji options

emoji

• Enable emoji. EMOJI CHEAT SHEET
• boolean. Default: true

Configuration options

executablePath

• Path to a Chromium or Chrome executable to run instead of the bundled Chromium
• All \ need to be written as \\ (Windows)

"executablePath": "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"

Common Options

scale

• Scale of the page rendering
• number. default: 1

"scale": 1

PDF options

• pdf only. puppeteer page.pdf options

displayHeaderFooter

• Enable display header and footer
• boolean. Default: true

headerTemplate

footerTemplate

• HTML template for the print header and footer
• <span class='date'></span> : formatted print date
• <span class='title'></span> : markdown file name
• <span class='url'></span> : markdown full path name
• <span class='pageNumber'></span> : current page number
• <span class='totalPages'></span> : total pages in the document

"headerTemplate": "<div style=\"font-size: 9px; margin-left: 1cm;\"> <span class='title'></span></div> <div style=\"font-size: 9px; margin-left: auto; margin-right: 1cm; \"> <span class='date'></span></div>",

"footerTemplate": "<div style=\"font-size: 9px; margin: 0 auto;\"> <span class='pageNumber'></span> / <span class='totalPages'></span></div>",

printBackground

• Print background graphics
• boolean. Default: true

orientation

• Paper orientation
• portrait or landscape
• Default: portrait

pageRanges

• Paper ranges to print, e.g., '1-5, 8, 11-13'
• Default: all pages

"pageRanges": "1,4-",

format

• Paper format
• Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6
• Default: A4

"format": "A4",

width

height

• Paper width / height, accepts values labeled with units(mm, cm, in, px)
• If it is set, it overrides the format option

"width": "10cm",
"height": "20cm",

margin.top

margin.bottom

margin.right

margin.left

• Paper margins.units(mm, cm, in, px)

"margin.top": "1.5cm",
"margin.bottom": "1cm",
"margin.right": "1cm",
"margin.left": "1cm",

PNG JPEG options

• png and jpeg only. puppeteer page.screenshot options

quality

• jpeg only. The quality of the image, between 0-100. Not applicable to png images

"quality": 100,

clip.x

clip.y

clip.width

clip.height

• An object which specifies clipping region of the page
• number

//  x-coordinate of top-left corner of clip area
"clip.x": 0,

// y-coordinate of top-left corner of clip area
"clip.y": 0,

// width of clipping area
"clip.width": 1000,

// height of clipping area
"clip.height": 1000,

omitBackground

• Hides default white background and allows capturing screenshots with transparency
• boolean. Default: false

FAQ

How can I change emoji size ?

1. Add the following to your stylesheet, which you can specified in the styles field

.emoji {
  height: 2em;
}

Output directory

If you want to always output to a directory path relative from the Markdown file.

For example, to output to the "output" directory in the same directory as the Markdown file, set it as follows.

"outputDirectory" : "output",
"outputDirectoryRelativePathFile": true,

Page Break

Please use the following to insert a page break.

<div class="page"/>

Note on Chromium

Chromium download starts automatically before the first conversion; this is a one time operation, only if your reinstall this package will it be downloaded again.

This isa time-consuming task depending on the environment because of its large size (~ 170Mb Mac, ~ 282Mb Linux, ~ 280Mb Win).

During the Chromuim download, the message Installing Chromium will be displayed in the console.