1 | # PDFKit
|
2 |
|
3 | A JavaScript PDF generation library for Node and the browser.
|
4 |
|
5 | ## Description
|
6 |
|
7 | PDFKit is a PDF document generation library for Node and the browser that makes creating complex, multi-page, printable documents easy.
|
8 | It's written in CoffeeScript, but you can choose to use the API in plain 'ol JavaScript if you like. The API embraces
|
9 | chainability, and includes both low level functions as well as abstractions for higher level functionality. The PDFKit API
|
10 | is designed to be simple, so generating complex documents is often as simple as a few function calls.
|
11 |
|
12 | Check out some of the [documentation and examples](http://pdfkit.org/docs/getting_started.html) to see for yourself!
|
13 | You can also read the guide as a [self-generated PDF](http://pdfkit.org/docs/guide.pdf) with example output displayed inline.
|
14 | If you'd like to see how it was generated, check out the README in the [docs](https://github.com/devongovett/pdfkit/tree/master/docs)
|
15 | folder.
|
16 |
|
17 | You can also try out an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html).
|
18 |
|
19 | ## Installation
|
20 |
|
21 | Installation uses the [npm](http://npmjs.org/) package manager. Just type the following command after installing npm.
|
22 |
|
23 | npm install pdfkit
|
24 |
|
25 | ## Features
|
26 |
|
27 | * Vector graphics
|
28 | * HTML5 canvas-like API
|
29 | * Path operations
|
30 | * SVG path parser for easy path creation
|
31 | * Transformations
|
32 | * Linear and radial gradients
|
33 | * Text
|
34 | * Line wrapping
|
35 | * Text alignments
|
36 | * Bulleted lists
|
37 | * Font embedding
|
38 | * Supports TrueType (.ttf), TrueType Collections (.ttc), and Datafork TrueType (.dfont) fonts
|
39 | * Font subsetting
|
40 | * Image embedding
|
41 | * Supports JPEG and PNG files (including indexed PNGs, and PNGs with transparency)
|
42 | * Annotations
|
43 | * Links
|
44 | * Notes
|
45 | * Highlights
|
46 | * Underlines
|
47 | * etc.
|
48 |
|
49 | ## Coming soon!
|
50 |
|
51 | * Patterns fills
|
52 | * Outlines
|
53 | * PDF Security
|
54 | * Higher level APIs for creating tables and laying out content
|
55 | * More performance optimizations
|
56 | * Even more awesomeness, perhaps written by you! Please fork this repository and send me pull requests.
|
57 |
|
58 | ## Example
|
59 |
|
60 | ```coffeescript
|
61 | PDFDocument = require 'pdfkit'
|
62 |
|
63 | # Create a document
|
64 | doc = new PDFDocument
|
65 |
|
66 | # Pipe it's output somewhere, like to a file or HTTP response
|
67 | # See below for browser usage
|
68 | doc.pipe fs.createWriteStream('output.pdf')
|
69 |
|
70 | # Embed a font, set the font size, and render some text
|
71 | doc.font('fonts/PalatinoBold.ttf')
|
72 | .fontSize(25)
|
73 | .text('Some text with an embedded font!', 100, 100)
|
74 |
|
75 | # Add another page
|
76 | doc.addPage()
|
77 | .fontSize(25)
|
78 | .text('Here is some vector graphics...', 100, 100)
|
79 |
|
80 | # Draw a triangle
|
81 | doc.save()
|
82 | .moveTo(100, 150)
|
83 | .lineTo(100, 250)
|
84 | .lineTo(200, 250)
|
85 | .fill("#FF3300")
|
86 |
|
87 | # Apply some transforms and render an SVG path with the 'even-odd' fill rule
|
88 | doc.scale(0.6)
|
89 | .translate(470, -380)
|
90 | .path('M 250,75 L 323,301 131,161 369,161 177,301 z')
|
91 | .fill('red', 'even-odd')
|
92 | .restore()
|
93 |
|
94 | # Add some text with annotations
|
95 | doc.addPage()
|
96 | .fillColor("blue")
|
97 | .text('Here is a link!', 100, 100)
|
98 | .underline(100, 100, 160, 27, color: "#0000FF")
|
99 | .link(100, 100, 160, 27, 'http://google.com/')
|
100 |
|
101 | # Finalize PDF file
|
102 | doc.end()
|
103 | ```
|
104 |
|
105 | [The PDF output from this example](http://pdfkit.org/demo/out.pdf) (with a few additions) shows the power of PDFKit — producing
|
106 | complex documents with a very small amount of code. For more, see the `demo` folder and the
|
107 | [PDFKit programming guide](http://pdfkit.org/docs/getting_started.html).
|
108 |
|
109 | ## Browser Usage
|
110 |
|
111 | There are two ways to use PDFKit in the browser. The first is to use [Browserify](http://browserify.org/),
|
112 | which is a Node module packager for the browser with the familiar `require` syntax. The second is to use
|
113 | a prebuilt version of PDFKit, which you can [download from Github](https://github.com/devongovett/pdfkit/releases).
|
114 |
|
115 | In addition to PDFKit, you'll need somewhere to stream the output to. HTML5 has a
|
116 | [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object which can be used to store binary data, and
|
117 | get URLs to this data in order to display PDF output inside an iframe, or upload to a server, etc. In order to
|
118 | get a Blob from the output of PDFKit, you can use the [blob-stream](https://github.com/devongovett/blob-stream)
|
119 | module.
|
120 |
|
121 | The following example uses Browserify to load `PDFKit` and `blob-stream`, but if you're not using Browserify,
|
122 | you can load them in whatever way you'd like (e.g. script tags).
|
123 |
|
124 | ```coffeescript
|
125 | # require dependencies
|
126 | PDFDocument = require 'pdfkit'
|
127 | blobStream = require 'blob-stream'
|
128 |
|
129 | # create a document the same way as above
|
130 | doc = new PDFDocument
|
131 |
|
132 | # pipe the document to a blob
|
133 | stream = doc.pipe(blobStream())
|
134 |
|
135 | # add your content to the document here, as usual
|
136 |
|
137 | # get a blob when you're done
|
138 | doc.end()
|
139 | stream.on 'finish', ->
|
140 | # get a blob you can do whatever you like with
|
141 | blob = stream.toBlob('application/pdf')
|
142 |
|
143 | # or get a blob URL for display in the browser
|
144 | url = stream.toBlobURL('application/pdf')
|
145 | iframe.src = url
|
146 | ```
|
147 |
|
148 | You can see an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html).
|
149 |
|
150 | Note that in order to Browserify a project using PDFKit, you need to install the `brfs` module with npm,
|
151 | which is used to load built-in font data into the package. It is listed as a `devDependency` in
|
152 | PDFKit's `package.json`, so it isn't installed by default for Node users.
|
153 | If you forget to install it, Browserify will print an error message.
|
154 |
|
155 | ## Documentation
|
156 |
|
157 | For complete API documentation and more examples, see the [PDFKit website](http://pdfkit.org/).
|
158 |
|
159 | ## License
|
160 |
|
161 | PDFKit is available under the MIT license. |
\ | No newline at end of file |