Skip to content

djfdyuruiry/pretty-markdown-pdf

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

PDF

Features

Supports the following features

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

PlantUML

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.convertMd({ markdownFilePath: "my-doc.md" })

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

// specify an output file type, outputs to `my-doc.html`
prettyMdPdf.convertMd({ 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.convertMd({ 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,
    "markdown-it-include": 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
  • Output format: pdf, html, png, jpeg
  • Multiple output formats supported
  • Default: pdf
"type": [
  "pdf",
  "html",
  "png",
  "jpeg"
],
  • 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
  • If outputDirectoryRelativePathFile option is set to true, the relative path set with outputDirectory is interpreted as relative from the file
  • boolean. Default: false
  • 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"
],
  • If stylesRelativePathFile option is set to true, the relative path set with styles is interpreted as relative from the file
  • boolean. Default: false
  • Enable the inclusion of default Markdown styles
  • boolean. Default: true
  • Enable Syntax highlighting
  • boolean. Default: true
"highlightStyle": "github",

Note: You can specify a path to a css file here, ensure your path ends with .css

"highlightStyle": "styles/custom.css",
  • Enable line breaks
  • boolean. Default: false
  • 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"
  • Scale of the page rendering
  • number. default: 1
"scale": 1
  • Enable display header and footer
  • boolean. Default: true

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>",
  • Print background graphics
  • boolean. Default: true
  • Paper orientation
  • portrait or landscape
  • Default: portrait
  • Paper ranges to print, e.g., '1-5, 8, 11-13'
  • Default: all pages
"pageRanges": "1,4-",
  • Paper format
  • Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6
  • Default: A4
"format": "A4",

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.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",
  • jpeg only. The quality of the image, between 0-100. Not applicable to png images
"quality": 100,

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,
  • 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 is a 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.