mdtopdf

README

mdtopdf

Introduction: Markdown to PDF

This package depends on two other packages:

• The BlackFriday v2 parser to read the markdown source
• The fpdf packace to generate the PDF

Both of the above are documented at Go Docs [http://godocs.org].

The tests included here are from the BlackFriday package. See the "testdata" folder. The tests create PDF files and thus while the tests may complete without errors, visual inspection of the created PDF is the only way to determine if the tests really pass!

The tests create log files that trace the BlackFriday parser callbacks. This is a valuable debug tool showing each callback and data provided in each while the AST is presented.

2019-09-23: It appears that the BlackFriday project is no longer active. There is a fork gomarkdown/markdown that I may be able to move to in the future if needed.

Supported Markdown

The supported elements of markdown are:

• Emphasized and strong text
• Headings 1-6
• Ordered and unordered lists
• Nested lists
• Images
• Tables (but see limitations below)
• Links
• Code blocks and backticked text

How to use of non-Latin fonts/languages is documented in a section below.

Limitations and Known Issues

1. It is common for Markdown to include HTML. HTML is treated as a "code block". There is no attempt to convert raw HTML to PDF.

2. Github-flavored Markdown permits strikethough using tildes. This is not supported at present by fpdf as a font style.

3. The markdown link title, which would show when converted to HTML as hover-over text, is not supported. The generated PDF will show the actual URL that will be used if clicked, but this is a function of the PDF viewer.

4. Currently all levels of unordered lists use a dash for the bullet. This is a planned fix; see here.

5. Definition lists are not supported (not sure that markdown supports them -- I need to research this)

6. The following text features may be tweaked: font, size, spacing, styile, fill color, and text color. These are exported and available via the Styler struct. Note that fill color only works if the text is ouput using CellFormat(). This is the case for: tables, codeblocks, and backticked text.

7. Tables are supported, but no attempt is made to ensure fit. You can, however, change the font size and spacing to make it smaller. See example.

Installation

To install the package, run the usual go get:

go get github.com/mandolyte/mdtopdf

Quick start

In the cmd folder is an example using the package. It demonstrates a number of features. The test PDF was created with this command:

go run convert.go -i test.md -o test.pdf

Using non-ASCII Glyphs/Fonts

In order to use a non-ASCII language there are a number things that must be done. The PDF generator must be configured WithUnicodeTranslator:

pf := mdtopdf.NewPdfRenderer("", "", *output, "trace.log", mdtopdf.WithUnicodeTranslator("cp1251")) // https://en.wikipedia.org/wiki/Windows-1251

In addition, this package's Styler must be used to set the font to match that is configured with the PDF generator.

A complete working example may be found for Russian in the cmd folder nameed russian.go.

Documentation

Overview

Package mdtopdf implements a PDF document generator for markdown documents.

Introduction

This package depends on two other packages:

* The BlackFriday v2 parser to read the markdown source

* The fpdf packace to generate the PDF

The tests included here are from the BlackFriday package. See the "testdata" folder. The tests create PDF files and thus while the tests may complete without errors, visual inspection of the created PDF is the only way to determine if the tests *really* pass!

The tests create log files that trace the BlackFriday parser callbacks. This is a valuable debug tool showing each callback and data provided in each while the AST is presented.

Installation

To install the package:

go get github.com/mandolyte/mdtopdf

Quick start

In the cmd folder is an example using the package. It demonstrates a number of features. The test PDF was created with this command:

go run convert.go -i test.md -o test.pdf

See README for limitations and known issues

Package mdtopdf converts markdown to PDF.

Index

• type Color
• type PdfRenderer
  • func NewPdfRenderer(orient, papersz, pdfFile, tracerFile string, opts ...RenderOption) *PdfRenderer
  • func NewPdfRendererWithDefaultStyler(orient, papersz, pdfFile, tracerFile string, defaultStyler Styler, ...) *PdfRenderer
  • func (r *PdfRenderer) Process(content []byte) error
  • func (r *PdfRenderer) RenderFooter(w io.Writer, ast *bf.Node)
  • func (r *PdfRenderer) RenderHeader(w io.Writer, ast *bf.Node)
  • func (r *PdfRenderer) RenderNode(w io.Writer, node *bf.Node, entering bool) bf.WalkStatus
  • func (r *PdfRenderer) Run(content []byte) error
  • func (r *PdfRenderer) UpdateBlockquoteStyler()
  • func (r *PdfRenderer) UpdateCodeStyler()
  • func (r *PdfRenderer) UpdateParagraphStyler(defaultStyler Styler)
• type RenderOption
  • func WithUnicodeTranslator(cp string) RenderOption
• type Styler

Types

type Color

type Color struct {
	Red, Green, Blue int
}

Color is a RGB set of ints; for a nice picker see https://www.w3schools.com/colors/colors_picker.asp

type PdfRenderer

type PdfRenderer struct {
	// Pdf can be used to access the underlying created fpdf object
	// prior to processing the markdown source
	Pdf *fpdf.Fpdf

	// normal text
	Normal Styler

	// link text
	Link Styler

	// backticked text
	Backtick Styler

	// blockquote text
	Blockquote  Styler
	IndentValue float64

	// Headings
	H1 Styler
	H2 Styler
	H3 Styler
	H4 Styler
	H5 Styler
	H6 Styler

	// Table styling
	THeader Styler
	TBody   Styler

	// code styling
	Code Styler

	// update styling
	NeedCodeStyleUpdate       bool
	NeedBlockquoteStyleUpdate bool
	// contains filtered or unexported fields
}

PdfRenderer is the struct to manage conversion of a markdown object to PDF format.

func NewPdfRenderer

func NewPdfRenderer(orient, papersz, pdfFile, tracerFile string, opts ...RenderOption) *PdfRenderer

NewPdfRenderer creates and configures an PdfRenderer object, which satisfies the Renderer interface.

func NewPdfRendererWithDefaultStyler

func NewPdfRendererWithDefaultStyler(orient, papersz, pdfFile, tracerFile string, defaultStyler Styler, opts ...RenderOption) *PdfRenderer

NewPdfRendererWithDefaultStyler creates and configures an PdfRenderer object, which satisfies the Renderer interface. update default styler for normal

func (*PdfRenderer) Process

func (r *PdfRenderer) Process(content []byte) error

Process takes the markdown content, parses it to generate the PDF

func (*PdfRenderer) RenderFooter

func (r *PdfRenderer) RenderFooter(w io.Writer, ast *bf.Node)

RenderFooter is not supported.

func (*PdfRenderer) RenderHeader

func (r *PdfRenderer) RenderHeader(w io.Writer, ast *bf.Node)

RenderHeader is not supported.

func (*PdfRenderer) RenderNode

func (r *PdfRenderer) RenderNode(w io.Writer, node *bf.Node, entering bool) bf.WalkStatus

RenderNode is a default renderer of a single node of a syntax tree. For block nodes it will be called twice: first time with entering=true, second time with entering=false, so that it could know when it's working on an open tag and when on close. It writes the result to w.

The return value is a way to tell the calling walker to adjust its walk pattern: e.g. it can terminate the traversal by returning Terminate. Or it can ask the walker to skip a subtree of this node by returning SkipChildren. The typical behavior is to return GoToNext, which asks for the usual traversal to the next node. (above taken verbatim from the blackfriday v2 package)

func (*PdfRenderer) Run

func (r *PdfRenderer) Run(content []byte) error

Run takes the markdown content, parses it but don't generate the PDF. you can access the PDF with youRenderer.Pdf

func (*PdfRenderer) UpdateBlockquoteStyler

func (r *PdfRenderer) UpdateBlockquoteStyler()

UpdateBlockquoteStyler - update Blockquote fill styler

func (*PdfRenderer) UpdateCodeStyler

func (r *PdfRenderer) UpdateCodeStyler()

UpdateCodeStyler - update code fill styler

func (*PdfRenderer) UpdateParagraphStyler

func (r *PdfRenderer) UpdateParagraphStyler(defaultStyler Styler)

UpdateParagraphStyler - update with default styler

type RenderOption

type RenderOption func(r *PdfRenderer)

RenderOption allows to define functions to configure the renderer

func WithUnicodeTranslator

func WithUnicodeTranslator(cp string) RenderOption

WithUnicodeTranslator configures a unico translator to support characters for latin, russian, etc..

type Styler

type Styler struct {
	Font      string
	Style     string
	Size      float64
	Spacing   float64
	TextColor Color
	FillColor Color
}

Styler is the struct to capture the styling features for text Size and Spacing are specified in points. The sum of Size and Spacing is used as line height value in the fpdf API