diff --git a/docs/README.md b/docs/README.md index 75bf7f9b4..fec5e851b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # PDFKit Guide -The PDFKit guide can be read a number of ways. The first is online at [pdfkit.org](http://pdfkit.org/). +The PDFKit guide can be read a number of ways. The first is online at [pdfkit.org](http://pdfkit.org/). You can also read the guide in PDF form, in this directory or [online](http://pdfkit.org/docs/guide.pdf). Both the website and the PDF guide are generated from the Markdown files @@ -9,18 +9,18 @@ You will need to have ImageMagick 7 installed so the `magick` command is on your `$PATH`. The examples are actually run when generating the PDF in order to show the results inline. -The `generate.js` file in this directory is actually quite short. It parses the markdown files into a +The `generate.js` file in this directory is actually quite short. It parses the markdown files into a tree structure using [markdown-js](https://github.com/evilstreak/markdown-js), syntax highlights the code examples using [codemirror](https://github.com/marijnh/codemirror), compiles and runs the code examples and puts the results -inline, and generates the PDF using PDFKit. You can read the generator script source code to get a feeling for +inline, and generates the PDF using PDFKit. You can read the generator script source code to get a feeling for how you might do something slightly more complex than the guide itself shows. The markdown syntax used is pretty much standard, with a couple tweaks. -1. Code example output is references using the image notation, using the alt text as the example number starting from - zero in the current file, and the title as the example output height. E.g. ``. - +1. Code example output is references using the image notation, using the alt text as the example number starting from + zero in the current file, and the title as the example output height. E.g. ``. + 2. Page breaks are added before `h1` and `h2`s, unless there are two in a row. `h3` is treated the same as `h2` but - can be used to avoid this in the case you need multiple `h2`s on the same page. + can be used to avoid this in the case you need multiple `h2`s on the same page. 3. The horizontal rule syntax (`* * *`) denotes an explicit page break diff --git a/docs/accessibility.md b/docs/accessibility.md index 79de1e413..53c977611 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -11,29 +11,29 @@ Some other simpler tasks are also required. This checklist covers everything that is required to create a conformant PDF/UA (PDF for Universal Accessibility) document (which is an extension of Tagged PDF): - * Pass the option `pdfVersion: '1.5'` (or a higher version) when creating your `PDFDocument` - (depending on the features you use, you may only need 1.4; refer to the PDF reference for - details). - * Pass the option `subset: 'PDF/UA'` when creating your `PDFDocument` (if you wish the PDF to - be identified as PDF/UA-1). - * Pass the option `tagged: true` when creating your `PDFDocument` (technically, this sets the - `Marked` property in the `Markings` dictionary to `true` in the PDF). - * Provide a `Title` in the `info` option, and pass `displayTitle: true` when creating your - `PDFDocument`. - * Specify natural language in the document options and/or logical structure and/or - non-structure marked `Span` content. - * Add logical structure with all significant content included. - * Include accessibility information (such as alternative text, actual text, etc.) in the - logical structure and/or non-structure marked `Span` content. - * Include all spaces which separate words/sentences/etc. in your marked structure content, - even at the ends of lines, paragraphs, etc.. I.e. don't do `doc.text("Hello, world!")` but - instead do `doc.text("Hello, world! ")`. - * Mark all non-structure content as artifacts. - * As well as creating the logical structure, write objects to the PDF in the natural - "reading order". - * Do not convey information solely using visuals (such as colour, - contrast or position on the page). - * No flickering or flashing content. +- Pass the option `pdfVersion: '1.5'` (or a higher version) when creating your `PDFDocument` + (depending on the features you use, you may only need 1.4; refer to the PDF reference for + details). +- Pass the option `subset: 'PDF/UA'` when creating your `PDFDocument` (if you wish the PDF to + be identified as PDF/UA-1). +- Pass the option `tagged: true` when creating your `PDFDocument` (technically, this sets the + `Marked` property in the `Markings` dictionary to `true` in the PDF). +- Provide a `Title` in the `info` option, and pass `displayTitle: true` when creating your + `PDFDocument`. +- Specify natural language in the document options and/or logical structure and/or + non-structure marked `Span` content. +- Add logical structure with all significant content included. +- Include accessibility information (such as alternative text, actual text, etc.) in the + logical structure and/or non-structure marked `Span` content. +- Include all spaces which separate words/sentences/etc. in your marked structure content, + even at the ends of lines, paragraphs, etc.. I.e. don't do `doc.text("Hello, world!")` but + instead do `doc.text("Hello, world! ")`. +- Mark all non-structure content as artifacts. +- As well as creating the logical structure, write objects to the PDF in the natural + "reading order". +- Do not convey information solely using visuals (such as colour, + contrast or position on the page). +- No flickering or flashing content. ## Marked Content @@ -57,18 +57,18 @@ Tags to use are listed in a later section. When marking content, you can provide options (take care to use correct capitalisation): - * `type` - used for artifact content; may be `Pagination` (e.g. headers and footers), - `Layout` (e.g. rules and backgrounds) or `Page` (cut marks etc.) - * `bbox` - bounding box for artifact content: `[left, top, right, bottom]` in default - coordinates - * `attached` - used for `Pagination` artifact content, array of one or more strings: - `Top`, `Bottom`, `Left`, `Right` - * `lang` - used for `Span` content: human language code (e.g. `en-AU`) which overrides default - document language, and any enclosing structure element language - * `alt` - used for `Span` content: alternative text for an image or other visual content - * `expanded` - used for `Span` content: the expanded form of an abbreviation or acronym - * `actual` - used for `Span` content: the actual text the content represents (e.g. if it is - rendered as vector graphics) +- `type` - used for artifact content; may be `Pagination` (e.g. headers and footers), + `Layout` (e.g. rules and backgrounds) or `Page` (cut marks etc.) +- `bbox` - bounding box for artifact content: `[left, top, right, bottom]` in default + coordinates +- `attached` - used for `Pagination` artifact content, array of one or more strings: + `Top`, `Bottom`, `Left`, `Right` +- `lang` - used for `Span` content: human language code (e.g. `en-AU`) which overrides default + document language, and any enclosing structure element language +- `alt` - used for `Span` content: alternative text for an image or other visual content +- `expanded` - used for `Span` content: the expanded form of an abbreviation or acronym +- `actual` - used for `Span` content: the actual text the content represents (e.g. if it is + rendered as vector graphics) It is advisable not to use `Span` content for specifying alternative text, expanded form, or actual text, especially if there is a possibility of the content automatically wrapping, which @@ -169,10 +169,10 @@ you cannot mix atomic and incremental styles for the same structure element. For an element to be flushed out, it must: - * be ended, - * have been added to its parent, and - * if it has content defined through closures (see next section), be attached to the document's - structure (through its ancestors) +- be ended, +- have been added to its parent, and +- if it has content defined through closures (see next section), be attached to the document's + structure (through its ancestors) When you call `doc.end()`, the document's structure is recursively ended, resulting in all elements being flushed out. If you created elements but forgot to add them to the document's @@ -200,8 +200,8 @@ This is equivalent to: myStruct.add(myStructContent); myStruct.end(); -Note that the content is marked and the closure is executed *if/when the element is attached to -the document's structure*. This means that you can do something like this: +Note that the content is marked and the closure is executed _if/when the element is attached to +the document's structure_. This means that you can do something like this: const myParagraph = doc.struct('P', [ () => { doc.text("Please see ", { continued: true }); }, @@ -231,11 +231,11 @@ It's best to add elements to their parents as you go. When creating a structure element, you can provide options: - * `title` - title of the structure element (e.g. "Chapter 1") - * `lang` - human language code (e.g. `en-AU`) which overrides default document language - * `alt` - alternative text for an image or other visual content - * `expanded` - the expanded form of an abbreviation or acronym - * `actual` - the actual text the content represents (e.g. if it is rendered as vector graphics) +- `title` - title of the structure element (e.g. "Chapter 1") +- `lang` - human language code (e.g. `en-AU`) which overrides default document language +- `alt` - alternative text for an image or other visual content +- `expanded` - the expanded form of an abbreviation or acronym +- `actual` - the actual text the content represents (e.g. if it is rendered as vector graphics) Example of a structure tree with options specified: @@ -308,69 +308,69 @@ ensure you give them with the correct capitalisation. Non-structure tags: - * `Artifact` - used to mark all content not part of the logical structure - * `ReversedChars` - every string of text has characters in reverse order for technical reasons - (due to how fonts work for right-to-left languages); strings may have spaces at the - beginning or end to separate words, but may not have spaces in the middle +- `Artifact` - used to mark all content not part of the logical structure +- `ReversedChars` - every string of text has characters in reverse order for technical reasons + (due to how fonts work for right-to-left languages); strings may have spaces at the + beginning or end to separate words, but may not have spaces in the middle "Grouping" elements: - * `Document` - whole document; must be used if there are multiple parts or articles - * `Part` - part of a document - * `Art` - article - * `Sect` - section; may nest - * `Div` - generic division - * `BlockQuote` - block quotation - * `Caption` - describing a figure or table - * `TOC` - table of contents, may be nested, and may be used for lists of figures, tables, etc. - * `TOCI` - table of contents (leaf) item - * `Index` - index (text with accompanying `Reference` content) - * `NonStruct` - non-structural grouping element (element itself not intended to be exported to - other formats like HTML, but 'transparent' to its content which is processed normally) - * `Private` - content only meaningful to the creator (element and its content not intended to - be exported to other formats like HTML) +- `Document` - whole document; must be used if there are multiple parts or articles +- `Part` - part of a document +- `Art` - article +- `Sect` - section; may nest +- `Div` - generic division +- `BlockQuote` - block quotation +- `Caption` - describing a figure or table +- `TOC` - table of contents, may be nested, and may be used for lists of figures, tables, etc. +- `TOCI` - table of contents (leaf) item +- `Index` - index (text with accompanying `Reference` content) +- `NonStruct` - non-structural grouping element (element itself not intended to be exported to + other formats like HTML, but 'transparent' to its content which is processed normally) +- `Private` - content only meaningful to the creator (element and its content not intended to + be exported to other formats like HTML) "Block" elements: - * `H` - heading (first element in a section, etc.) - * `H1` to `H6` - heading of a particular level intended for use only if nesting sections - is not possible for some reason - * `P` - paragraph - * `L` - list; should include optional `Caption`, and list items - * `LI` - list item; should contain `Lbl` and/or `LBody` - * `Lbl` - label (bullet, number, or "dictionary headword") - * `LBody` - list body (item text, or "dictionary definition"); may have nested lists or other blocks +- `H` - heading (first element in a section, etc.) +- `H1` to `H6` - heading of a particular level intended for use only if nesting sections + is not possible for some reason +- `P` - paragraph +- `L` - list; should include optional `Caption`, and list items +- `LI` - list item; should contain `Lbl` and/or `LBody` +- `Lbl` - label (bullet, number, or "dictionary headword") +- `LBody` - list body (item text, or "dictionary definition"); may have nested lists or other blocks "Table" elements: - * `Table` - table; should either contain `TR`, or `THead`, `TBody` and/or `TFoot` - * `TR` - table row - * `TH` - table heading cell - * `TD` - table data cell - * `THead` - table header row group - * `TBody` - table body row group; may have more than one per table - * `TFoot` - table footer row group +- `Table` - table; should either contain `TR`, or `THead`, `TBody` and/or `TFoot` +- `TR` - table row +- `TH` - table heading cell +- `TD` - table data cell +- `THead` - table header row group +- `TBody` - table body row group; may have more than one per table +- `TFoot` - table footer row group "Inline" elements: - * `Span` - generic inline content - * `Quote` - inline quotation - * `Note` - e.g. footnote; may have a `Lbl` (see "block" elements) - * `Reference` - content in a document that refers to other content (e.g. page number in an index) - * `BibEntry` - bibliography entry; may have a `Lbl` (see "block" elements) - * `Code` - code - * `Link` - hyperlink; should contain a link annotation - * `Annot` - annotation (other than a link) - * `Ruby` - Chinese/Japanese pronunciation/explanation - * `RB` - Ruby base text - * `RT` - Ruby annotation text - * `RP` - Ruby punctuation - * `Warichu` - Japanese/Chinese longer description - * `WT` - Warichu text - * `WP` - Warichu punctuation +- `Span` - generic inline content +- `Quote` - inline quotation +- `Note` - e.g. footnote; may have a `Lbl` (see "block" elements) +- `Reference` - content in a document that refers to other content (e.g. page number in an index) +- `BibEntry` - bibliography entry; may have a `Lbl` (see "block" elements) +- `Code` - code +- `Link` - hyperlink; should contain a link annotation +- `Annot` - annotation (other than a link) +- `Ruby` - Chinese/Japanese pronunciation/explanation +- `RB` - Ruby base text +- `RT` - Ruby annotation text +- `RP` - Ruby punctuation +- `Warichu` - Japanese/Chinese longer description +- `WT` - Warichu text +- `WP` - Warichu punctuation "Illustration" elements (should have `alt` and/or `actualtext` set): - * `Figure` - figure - * `Formula` - formula - * `Form` - form widget +- `Figure` - figure +- `Formula` - formula +- `Form` - form widget diff --git a/docs/annotations.md b/docs/annotations.md index 2bc43c07b..7ec86d62b 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -6,17 +6,17 @@ underline or strikeout portions of text. Annotations are added using the various helper methods, and each type of annotation is defined by a rectangle and some other properties. Here is a list of the available annotation methods: -* `note(x, y, width, height, contents, options)` -* `link(x, y, width, height, url, options)` -* `goTo(x, y, w, h, name, options)` -* `highlight(x, y, width, height, options)` -* `underline(x, y, width, height, options)` -* `strike(x, y, width, height, options)` -* `lineAnnotation(x1, y1, x2, y2, options)` -* `rectAnnotation(x, y, width, height, options)` -* `ellipseAnnotation(x, y, width, height, options)` -* `textAnnotation(x, y, width, height, text, options)` -* `fileAnnotation(x, y, width, height, file, options)` +- `note(x, y, width, height, contents, options)` +- `link(x, y, width, height, url, options)` +- `goTo(x, y, w, h, name, options)` +- `highlight(x, y, width, height, options)` +- `underline(x, y, width, height, options)` +- `strike(x, y, width, height, options)` +- `lineAnnotation(x1, y1, x2, y2, options)` +- `rectAnnotation(x, y, width, height, options)` +- `ellipseAnnotation(x, y, width, height, options)` +- `textAnnotation(x, y, width, height, text, options)` +- `fileAnnotation(x, y, width, height, file, options)` Many of the annotations have a `color` option that you can specify. You can use an array of RGB values, a hex color, a named CSS color value, or a named @@ -39,7 +39,7 @@ more than one annotation on a single area and one of those annotations is a link, make sure that the link is the last one you add, otherwise it will be covered by another annotation and the user won't be able to click it. -* * * +--- Here is an example that uses a few of the annotation types. @@ -89,7 +89,7 @@ The output of this example looks like this. Annotations are currently not the easiest things to add to PDF documents, but that is the fault of the PDF spec itself. Calculating a rectangle manually isn't fun, but PDFKit makes it easier for a few common annotations applied to text, including -links, underlines, and strikes. Here's an example showing two of them: +links, underlines, and strikes. Here's an example showing two of them: doc.fontSize(20) .fillColor('red') diff --git a/docs/attachments.md b/docs/attachments.md index 78ff1d680..3de45b88f 100644 --- a/docs/attachments.md +++ b/docs/attachments.md @@ -18,13 +18,13 @@ When embedding a data URL, the `type` option will be set to the data URL's MIME There are a few other options for `doc.file`: -* `name` - specify the embedded file's name -* `type` - specify the embedded file's subtype as a [MIME-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) -* `description` - add descriptive text for the embedded file -* `hidden` - if true, do not show file in the list of embedded files -* `creationDate` - override the date and time the file was created -* `modifiedDate` - override the date and time the file was last updated -* `relationship` - relationship between the PDF document and its attached file. Can be 'Alternative', 'Data', 'Source', 'Supplement' or 'Unspecified'. +- `name` - specify the embedded file's name +- `type` - specify the embedded file's subtype as a [MIME-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) +- `description` - add descriptive text for the embedded file +- `hidden` - if true, do not show file in the list of embedded files +- `creationDate` - override the date and time the file was created +- `modifiedDate` - override the date and time the file was last updated +- `relationship` - relationship between the PDF document and its attached file. Can be 'Alternative', 'Data', 'Source', 'Supplement' or 'Unspecified'. If you are attaching a file from your file system, creationDate and modifiedDate will be set to the source file's creationDate and modifiedDate. diff --git a/docs/destinations.md b/docs/destinations.md index 30becbe6f..651c89845 100644 --- a/docs/destinations.md +++ b/docs/destinations.md @@ -16,7 +16,6 @@ Examples of creating anchor: // Insert anchor for this text doc.text('End of paragraph', { destination: 'ENDP' }); - Examples of go to link to anchor: // Go to annotation @@ -24,6 +23,7 @@ Examples of go to link to anchor: // Go to annotation for this text doc.text('Another goto', 20, 0, { - goTo: 'ENDP', - underline: true - }); + +goTo: 'ENDP', +underline: true +}); diff --git a/docs/forms.md b/docs/forms.md index 6d2de6399..589f12633 100644 --- a/docs/forms.md +++ b/docs/forms.md @@ -70,8 +70,8 @@ doc.formText('leaf2', 10, 60, 200, 40, { align: 'right', format: { type: 'date', - params: 'm/d' - } + params: 'm/d', + }, }); ``` @@ -88,7 +88,7 @@ opts = { select: ['', 'github', 'bitbucket', 'gitlab'], value: '', defaultValue: '', - align: 'left' + align: 'left', }; doc.formCombo('ch1', 10, y, 100, 20, opts); ``` @@ -101,7 +101,7 @@ doc.formCombo('ch1', 10, y, 100, 20, opts); ```js var opts = { backgroundColor: 'yellow', - label: 'Test Button' + label: 'Test Button', }; doc.formPushButton('btn1', 10, 200, 100, 30, opts); ``` @@ -145,8 +145,8 @@ doc.formText('field.date', 10, 60, 200, 40, { align: 'center', format: { type: 'date', - param: 'mmmm d, yyyy' - } + param: 'mmmm d, yyyy', + }, }); ``` @@ -161,8 +161,8 @@ doc.formText('field.time', 10, 60, 200, 40, { align: 'center', format: { type: 'time', - param: 2 - } + param: 2, + }, }); ``` @@ -185,8 +185,8 @@ doc.formText('leaf2', 10, 60, 200, 40, { sepComma: true, negStyle: 'ParensRed', currency: '$', - currencyPrepend: true - } + currencyPrepend: true, + }, }); ``` @@ -227,23 +227,23 @@ let child2Field = doc.formField('child2Field', { parent: rootField }); // Add text form annotation 'rootField.child1Field.leaf1' doc.formText('leaf1', 10, 10, 200, 40, { parent: child1Field, - multiline: true + multiline: true, }); // Add text form annotation 'rootField.child1Field.leaf2' doc.formText('leaf2', 10, 60, 200, 40, { parent: child1Field, - multiline: true + multiline: true, }); // Add text form annotation 'rootField.child2Field.leaf1' doc.formText('leaf1', 10, 110, 200, 80, { parent: child2Field, - multiline: true + multiline: true, }); // Add push button form annotation 'btn1' var opts = { backgroundColor: 'yellow', - label: 'Test Button' + label: 'Test Button', }; doc.formPushButton('btn1', 10, 200, 100, 30, opts); ``` diff --git a/docs/generate.js b/docs/generate.js index 67e66a6e1..e674684f8 100644 --- a/docs/generate.js +++ b/docs/generate.js @@ -16,52 +16,52 @@ const styles = { h1: { font: 'fonts/Alegreya-Bold.ttf', fontSize: 25, - padding: 15 + padding: 15, }, h2: { font: 'fonts/Alegreya-Bold.ttf', fontSize: 18, - padding: 10 + padding: 10, }, h3: { font: 'fonts/Alegreya-Bold.ttf', fontSize: 18, - padding: 10 + padding: 10, }, para: { font: 'fonts/Merriweather-Regular.ttf', fontSize: 10, - padding: 10 + padding: 10, }, code: { font: 'fonts/SourceCodePro-Regular.ttf', - fontSize: 9 + fontSize: 9, }, code_block: { padding: 10, - background: '#2c2c2c' + background: '#2c2c2c', }, inlinecode: { font: 'fonts/SourceCodePro-Bold.ttf', - fontSize: 10 + fontSize: 10, }, listitem: { font: 'fonts/Merriweather-Regular.ttf', fontSize: 10, - padding: 6 + padding: 6, }, link: { font: 'fonts/Merriweather-Regular.ttf', fontSize: 10, color: 'blue', - underline: true + underline: true, }, example: { font: 'Helvetica', fontSize: 9, color: 'black', - padding: 10 - } + padding: 10, + }, }; // syntax highlighting colors @@ -89,7 +89,7 @@ const colors = { quote: '#93a1a1', link: '#93a1a1', special: '#6c71c4', - default: '#002b36' + default: '#002b36', }; // shared lorem ipsum text so we don't need to copy it into every example @@ -135,7 +135,7 @@ class Node { const color = colors[style] || colors.default; const opts = { color, - continued: text !== '\n' + continued: text !== '\n', }; return this.content.push(new Node(['code', opts, text])); @@ -164,7 +164,7 @@ class Node { } // sets the styles on the document for this node - setStyle (doc) { + setStyle(doc) { if (this.style.font) { doc.font(this.style.font); } @@ -189,7 +189,7 @@ class Node { } // renders this node and its subnodes to the document - render (doc, continued) { + render(doc, continued) { let y; if (continued == null) { continued = false; @@ -210,7 +210,7 @@ class Node { // run the example code with the document vm.runInNewContext(this.code, { doc, - lorem + lorem, }); // restore points and styles @@ -257,7 +257,7 @@ class Node { } else { fragment.render( doc, - index < this.content.length - 1 && this.type !== 'bulletlist' + index < this.content.length - 1 && this.type !== 'bulletlist', ); } @@ -286,7 +286,7 @@ const render = (doc, filename) => { }; // renders the title page of the guide -const renderTitlePage = doc => { +const renderTitlePage = (doc) => { const title = 'PDFKit Guide'; const author = 'By Devon Govett'; const version = `Version ${require('../package.json').version}`; @@ -301,13 +301,13 @@ const renderTitlePage = doc => { doc.y -= 10; doc.text(author, { align: 'center', - indent: w - doc.widthOfString(author) + indent: w - doc.widthOfString(author), }); doc.font(styles.para.font, 10); doc.text(version, { align: 'center', - indent: w - doc.widthOfString(version) + indent: w - doc.widthOfString(version), }); doc.addPage(); diff --git a/docs/generate_website.js b/docs/generate_website.js index c0cc9c29c..701d17afa 100644 --- a/docs/generate_website.js +++ b/docs/generate_website.js @@ -24,14 +24,14 @@ const files = [ 'destinations.md', 'attachments.md', 'accessibility.md', - 'you_made_it.md' + 'you_made_it.md', ]; // shared lorem ipsum text so we don't need to copy it into every example const lorem = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam in suscipit purus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Vivamus nec hendrerit felis. Morbi aliquam facilisis risus eu lacinia. Sed eu leo in turpis fringilla hendrerit. Ut nec accumsan nisl. Suspendisse rhoncus nisl posuere tortor tempus et dapibus elit porta. Cras leo neque, elementum a rhoncus ut, vestibulum non nibh. Phasellus pretium justo turpis. Etiam vulputate, odio vitae tincidunt ultricies, eros odio dapibus nisi, ut tincidunt lacus arcu eu elit. Aenean velit erat, vehicula eget lacinia ut, dignissim non tellus. Aliquam nec lacus mi, sed vestibulum nunc. Suspendisse potenti. Curabitur vitae sem turpis. Vestibulum sed neque eget dolor dapibus porttitor at sit amet sem. Fusce a turpis lorem. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;'; -const getNodeName = function(node) { +const getNodeName = function (node) { if (node.length === 3) { return node[2]; } @@ -48,7 +48,7 @@ const getNodeName = function(node) { return words.join(''); }; -const extractHeaders = function(tree) { +const extractHeaders = function (tree) { const headers = []; for (let index = 0; index < tree.length; index++) { @@ -62,7 +62,7 @@ const extractHeaders = function(tree) { node[1].id = hash; headers.push({ hash, - title: name + title: name, }); } } @@ -71,7 +71,7 @@ const extractHeaders = function(tree) { }; let imageIndex = 0; -const generateImages = function(tree) { +const generateImages = function (tree) { // find code blocks const codeBlocks = []; for (var node of tree) { @@ -99,7 +99,7 @@ const generateImages = function(tree) { vm.runInNewContext(code, { doc, - lorem + lorem, }); delete attrs.title; @@ -118,7 +118,7 @@ const generateImages = function(tree) { console.error(err); } fs.unlinkSync(`${f}.pdf`); - } + }, ); }); @@ -134,7 +134,7 @@ for (let file of Array.from(files)) { // turn github highlighted code blocks into normal markdown code blocks content = content.replace( /^```javascript\n((:?.|\n)*?)\n```/gm, - (m, $1) => ` ${$1.split('\n').join('\n ')}` + (m, $1) => ` ${$1.split('\n').join('\n ')}`, ); const tree = markdown.parse(content); @@ -148,7 +148,7 @@ for (let file of Array.from(files)) { url: `/docs/${file}.html`, title: headers[0].title, headers: headers.slice(1), - content: markdown.toHTML(tree) + content: markdown.toHTML(tree), }); } diff --git a/docs/getting_started.md b/docs/getting_started.md index 5538b9b65..8ff4dd967 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -108,7 +108,7 @@ By default, using a number this will be in points (the default PDF unit), however you can provide any of the following units inside a string and this will be converted for you: `em`, `in`, `px`, `cm`, `mm`, `pc`, `ex`, `ch`, `rem`, `vw`, `vmin`, `vmax`, `%`, `pt`. -For those which are based on text sizes this will take the size of the font for the page +For those which are based on text sizes this will take the size of the font for the page (excluding `rem` which is always the document root font size) The default is a 1 inch (72 point) margin on all sides. diff --git a/docs/outline.md b/docs/outline.md index 7ee46da2e..17fee9432 100644 --- a/docs/outline.md +++ b/docs/outline.md @@ -2,7 +2,7 @@ Outlines are the heirachical bookmarks that display in some PDF readers. Currently only page bookmarks are supported, but more may be added in the future. They are simple to add and only require a single method: -* `addItem(title, options)` +- `addItem(title, options)` Here is an example of adding a bookmark with a single child bookmark. @@ -17,7 +17,7 @@ Here is an example of adding a bookmark with a single child bookmark. ## Options -The `options` parameter currently only has one property: `expanded`. If this value is set to `true` then all of that section's children will be visible by default. This value defaults to `false`. +The `options` parameter currently only has one property: `expanded`. If this value is set to `true` then all of that section's children will be visible by default. This value defaults to `false`. In this example the 'Top Level' section will be expanded to show 'Sub-section'. @@ -25,4 +25,4 @@ In this example the 'Top Level' section will be expanded to show 'Sub-section'. const top = outline.addItem('Top Level', { expanded: true }); // Add a sub-section - top.addItem('Sub-section'); \ No newline at end of file + top.addItem('Sub-section'); diff --git a/docs/paper_sizes.md b/docs/paper_sizes.md index 93df22019..522bc6599 100644 --- a/docs/paper_sizes.md +++ b/docs/paper_sizes.md @@ -1,88 +1,88 @@ # Paper Sizes -When creating a new document or adding a new page to your current document, PDFKit allows you to set the page dimensions. To improve convenience, PDFKit has a number of predefined page sizes. These sizes are based on the most commonly used standard page sizes. +When creating a new document or adding a new page to your current document, PDFKit allows you to set the page dimensions. To improve convenience, PDFKit has a number of predefined page sizes. These sizes are based on the most commonly used standard page sizes. ### Predefined Page Sizes -The following predefined sizes are based on the ISO (International) standards. All the dimensions in brackets are in PostScript points. +The following predefined sizes are based on the ISO (International) standards. All the dimensions in brackets are in PostScript points. #### A-series -* A0 (2383.94 x 3370.39) -* A1 (1683.78 x 2383.94) -* A2 (1190.55 x 1683.78) -* A3 (841.89 x 1190.55) -* A4 (595.28 x 841.89) -* A5 (419.53 x 595.28) -* A6 (297.64 x 419.53) -* A7 (209.76 x 297.64) -* A8 (147.40 x 209.76) -* A9 (104.88 x 147.40) -* A10 (73.70 x 104.88) +- A0 (2383.94 x 3370.39) +- A1 (1683.78 x 2383.94) +- A2 (1190.55 x 1683.78) +- A3 (841.89 x 1190.55) +- A4 (595.28 x 841.89) +- A5 (419.53 x 595.28) +- A6 (297.64 x 419.53) +- A7 (209.76 x 297.64) +- A8 (147.40 x 209.76) +- A9 (104.88 x 147.40) +- A10 (73.70 x 104.88) #### B-series -* B0 (2834.65 x 4008.19) -* B1 (2004.09 x 2834.65) -* B2 (1417.32 x 2004.09) -* B3 (1000.63 x 1417.32) -* B4 (708.66 x 1000.63) -* B5 (498.90 x 708.66) -* B6 (354.33 x 498.90) -* B7 (249.45 x 354.33) -* B8 (175.75 x 249.45) -* B9 (124.72 x 175.75) -* B10 (87.87 x 124.72) +- B0 (2834.65 x 4008.19) +- B1 (2004.09 x 2834.65) +- B2 (1417.32 x 2004.09) +- B3 (1000.63 x 1417.32) +- B4 (708.66 x 1000.63) +- B5 (498.90 x 708.66) +- B6 (354.33 x 498.90) +- B7 (249.45 x 354.33) +- B8 (175.75 x 249.45) +- B9 (124.72 x 175.75) +- B10 (87.87 x 124.72) #### C-series -* C0 (2599.37 x 3676.54) -* C1 (1836.85 x 2599.37) -* C2 (1298.27 x 1836.85) -* C3 (918.43 x 1298.27) -* C4 (649.13 x 918.43) -* C5 (459.21 x 649.13) -* C6 (323.15 x 459.21) -* C7 (229.61 x 323.15) -* C8 (161.57 x 229.61) -* C9 (113.39 x 161.57) -* C10 (79.37 x 113.39) +- C0 (2599.37 x 3676.54) +- C1 (1836.85 x 2599.37) +- C2 (1298.27 x 1836.85) +- C3 (918.43 x 1298.27) +- C4 (649.13 x 918.43) +- C5 (459.21 x 649.13) +- C6 (323.15 x 459.21) +- C7 (229.61 x 323.15) +- C8 (161.57 x 229.61) +- C9 (113.39 x 161.57) +- C10 (79.37 x 113.39) #### RA-series -* RA0 (2437.80 x 3458.27) -* RA1 (1729.13 x 2437.80) -* RA2 (1218.90 x 1729.13) -* RA3 (864.57 x 1218.90) -* RA4 (609.45 x 864.57) +- RA0 (2437.80 x 3458.27) +- RA1 (1729.13 x 2437.80) +- RA2 (1218.90 x 1729.13) +- RA3 (864.57 x 1218.90) +- RA4 (609.45 x 864.57) #### SRA-series -* SRA0 (2551.18 x 3628.35) -* SRA1 (1814.17 x 2551.18) -* SRA2 (1275.59 x 1814.17) -* SRA3 (907.09 x 1275.59) -* SRA4 (637.80 x 907.09) +- SRA0 (2551.18 x 3628.35) +- SRA1 (1814.17 x 2551.18) +- SRA2 (1275.59 x 1814.17) +- SRA3 (907.09 x 1275.59) +- SRA4 (637.80 x 907.09) -The following predefined sizes are based on the common paper sizes used mainly in the United States of America and Canada. The dimensions in brackets are in PostScript points. +The following predefined sizes are based on the common paper sizes used mainly in the United States of America and Canada. The dimensions in brackets are in PostScript points. -* EXECUTIVE (521.86 x 756.00) -* LEGAL (612.00 x 1008.00) -* LETTER (612.00 X 792.00) -* TABLOID (792.00 X 1224.00) +- EXECUTIVE (521.86 x 756.00) +- LEGAL (612.00 x 1008.00) +- LETTER (612.00 X 792.00) +- TABLOID (792.00 X 1224.00) -PDFKit supports also the following paper sizes. The dimensions in brackets are in PostScript points. +PDFKit supports also the following paper sizes. The dimensions in brackets are in PostScript points. -* 4A0 (4767.89 x 6740.79) -* 2A0 (3370.39 x 4767.87) -* FOLIO (612.00 X 936.00) +- 4A0 (4767.89 x 6740.79) +- 2A0 (3370.39 x 4767.87) +- FOLIO (612.00 X 936.00) ### Setting the page size -In order to use the predefined sizes, the name of the size (as named in the lists above) should be passed to either the `PDFDocument` constructor or the `addPage()` function in the `size` property of the `options` object, as shown in the example below, using `A7` as the preferred size. +In order to use the predefined sizes, the name of the size (as named in the lists above) should be passed to either the `PDFDocument` constructor or the `addPage()` function in the `size` property of the `options` object, as shown in the example below, using `A7` as the preferred size. // Passing size to the constructor const doc = new PDFDocument({size: 'A7'}); - + // Passing size to the addPage function doc.addPage({size: 'A7'}); diff --git a/docs/publish_website.js b/docs/publish_website.js index 2a96180af..4fbbf9214 100644 --- a/docs/publish_website.js +++ b/docs/publish_website.js @@ -14,14 +14,14 @@ ghpages.publish( 'docs/guide.pdf', 'examples/browserify/browser.html', 'examples/browserify/bundle.js', - 'examples/kitchen-sink.pdf' + 'examples/kitchen-sink.pdf', ], add: true, - message + message, }, - function(err) { + function (err) { if (err) { console.error(err); } - } + }, ); diff --git a/docs/text.md b/docs/text.md index 411505ae9..28e9c458d 100644 --- a/docs/text.md +++ b/docs/text.md @@ -72,7 +72,6 @@ showing their use in a text box. // draw bounding rectangle doc.rect(doc.x, 0, 410, doc.y).stroke(); - The output of this example, looks like this:  @@ -83,36 +82,36 @@ PDFKit has many options for controlling the look of text added to PDF documents, which can be passed to the `text` method. They are enumerated below. -* `lineBreak` - set to `false` to disable line wrapping all together -* `width` - the width that text should be wrapped to (by default, the page width minus the left and right margin) -* `height` - the maximum height that text should be clipped to -* `rotation` - the rotation of the text in degrees (by default 0) -* `ellipsis` - the character to display at the end of the text when it is too long. Set to `true` to use the default character. -* `columns` - the number of columns to flow the text into -* `columnGap` - the amount of space between each column (1/4 inch by default) -* `indent` - the amount in PDF points (72 per inch) to indent each paragraph of text -* `indentAllLines` - wheter to indent all lines of a paragraph (`false` by default - indents only the first line) -* `paragraphGap` - the amount of space between each paragraph of text -* `lineGap` - the amount of space between each line of text -* `wordSpacing` - the amount of space between each word in the text -* `characterSpacing` - the amount of space between each character in the text -* `horizontalScaling` - ability to scale text horizontally (`100` percent by default) -* `fill` - whether to fill the text (`true` by default) -* `stroke` - whether to stroke the text -* `link` - a URL to link this text to (shortcut to create an annotation) -* `goTo` - go to anchor (shortcut to create an annotation) -* `destination` - create anchor to this text -* `underline` - whether to underline the text -* `strike` - whether to strike out the text -* `oblique` - whether to slant the text (angle in degrees or `true`) -* `baseline` - the vertical alignment of the text with respect to its insertion point (values as [canvas textBaseline](https://www.w3schools.com/tags/canvas_textbaseline.asp)) -* `continued` - whether the text segment will be followed immediately by another segment. Useful for changing styling in the middle of a paragraph. -* `features` - an array of [OpenType feature tags](https://www.microsoft.com/typography/otspec/featuretags.htm) to apply. Can also be provided as an object with features as keys and boolean values. If not provided, a set of defaults is used. To deactivate default font features, you have to explicitly set them to false (`{ liga: false }`). When providing an empty array the default font features will still be used. +- `lineBreak` - set to `false` to disable line wrapping all together +- `width` - the width that text should be wrapped to (by default, the page width minus the left and right margin) +- `height` - the maximum height that text should be clipped to +- `rotation` - the rotation of the text in degrees (by default 0) +- `ellipsis` - the character to display at the end of the text when it is too long. Set to `true` to use the default character. +- `columns` - the number of columns to flow the text into +- `columnGap` - the amount of space between each column (1/4 inch by default) +- `indent` - the amount in PDF points (72 per inch) to indent each paragraph of text +- `indentAllLines` - wheter to indent all lines of a paragraph (`false` by default - indents only the first line) +- `paragraphGap` - the amount of space between each paragraph of text +- `lineGap` - the amount of space between each line of text +- `wordSpacing` - the amount of space between each word in the text +- `characterSpacing` - the amount of space between each character in the text +- `horizontalScaling` - ability to scale text horizontally (`100` percent by default) +- `fill` - whether to fill the text (`true` by default) +- `stroke` - whether to stroke the text +- `link` - a URL to link this text to (shortcut to create an annotation) +- `goTo` - go to anchor (shortcut to create an annotation) +- `destination` - create anchor to this text +- `underline` - whether to underline the text +- `strike` - whether to strike out the text +- `oblique` - whether to slant the text (angle in degrees or `true`) +- `baseline` - the vertical alignment of the text with respect to its insertion point (values as [canvas textBaseline](https://www.w3schools.com/tags/canvas_textbaseline.asp)) +- `continued` - whether the text segment will be followed immediately by another segment. Useful for changing styling in the middle of a paragraph. +- `features` - an array of [OpenType feature tags](https://www.microsoft.com/typography/otspec/featuretags.htm) to apply. Can also be provided as an object with features as keys and boolean values. If not provided, a set of defaults is used. To deactivate default font features, you have to explicitly set them to false (`{ liga: false }`). When providing an empty array the default font features will still be used. Additionally, the fill and stroke color and opacity methods described in the [vector graphics section](vector.html) are applied to text content as well. -* * * +--- Here is an example combining some of the options above, wrapping a piece of text into three columns, in a specified width and height. @@ -147,9 +146,9 @@ The `list` method creates a bulleted list. It accepts as arguments an array of s and the optional `x`, `y` position. You can create complex multilevel lists by using nested arrays. Lists use the following additional options: -* `bulletRadius` -* `textIndent` -* `bulletIndent` +- `bulletRadius` +- `textIndent` +- `bulletIndent` ## Rich Text @@ -159,7 +158,7 @@ when you call text again after changing the text styles, the wrapping will conti where it left off. The options given to the first `text` call are also retained for subsequent calls after a -`continued` one, but of course you can override them. In the following example, the `width` +`continued` one, but of course you can override them. In the following example, the `width` option from the first `text` call is retained by the second call. doc.fillColor('green') @@ -200,20 +199,20 @@ The PDF format defines 14 standard fonts that can be used in PDF documents. PDFK Besides Symbol and Zapf Dingbats this includes 4 styles (regular, bold, italic/oblique, bold+italic) of Helvetica, Courier, and Times. To switch between standard fonts, call the `font` method with the corresponding Label: -* `'Courier'` -* `'Courier-Bold'` -* `'Courier-Oblique'` -* `'Courier-BoldOblique'` -* `'Helvetica'` -* `'Helvetica-Bold'` -* `'Helvetica-Oblique'` -* `'Helvetica-BoldOblique'` -* `'Symbol'` -* `'Times-Roman'` -* `'Times-Bold'` -* `'Times-Italic'` -* `'Times-BoldItalic'` -* `'ZapfDingbats'` +- `'Courier'` +- `'Courier-Bold'` +- `'Courier-Oblique'` +- `'Courier-BoldOblique'` +- `'Helvetica'` +- `'Helvetica-Bold'` +- `'Helvetica-Oblique'` +- `'Helvetica-BoldOblique'` +- `'Symbol'` +- `'Times-Roman'` +- `'Times-Bold'` +- `'Times-Italic'` +- `'Times-BoldItalic'` +- `'ZapfDingbats'` The PDF format also allows fonts to be embedded right in the document. PDFKit supports embedding TrueType (`.ttf`), OpenType (`.otf`), WOFF, WOFF2, TrueType Collection (`.ttc`), diff --git a/docs/vector.md b/docs/vector.md index 07138d651..c00317404 100644 --- a/docs/vector.md +++ b/docs/vector.md @@ -27,7 +27,7 @@ example that illustrates defining a path. The output of this example looks like this: - + One thing to notice about this example is the use of method chaining. All methods in PDFKit are chainable, meaning that you can call one method right @@ -46,7 +46,7 @@ syntax like this. doc.path('M 0,20 L 100,160 Q 130,200 150,120 C 190,-40 200,200 300,150 L 400,90') .stroke() - + The PDFKit SVG parser supports all of the command types supported by SVG, so any valid SVG path you throw at it should work as expected. @@ -56,11 +56,11 @@ any valid SVG path you throw at it should work as expected. PDFKit also includes some helpers that make defining common shapes much easier. Here is a list of the helpers. -* `rect(x, y, width, height)` -* `roundedRect(x, y, width, height, cornerRadius)` -* `ellipse(centerX, centerY, radiusX, radiusY = radiusX)` -* `circle(centerX, centerY, radius)` -* `polygon(points...)` +- `rect(x, y, width, height)` +- `roundedRect(x, y, width, height, cornerRadius)` +- `ellipse(centerX, centerY, radiusX, radiusY = radiusX)` +- `circle(centerX, centerY, radius)` +- `polygon(points...)` The last one, `polygon`, allows you to pass in a list of points (arrays of x,y pairs), and it will create the shape by moving to the first point, and then @@ -72,7 +72,7 @@ with the polygon helper. The output of this example looks like this: - + ## Fill and stroke styles @@ -86,16 +86,16 @@ path. In order to make our drawings interesting, we really need to give them some style. PDFKit has many methods designed to do just that. - * `lineWidth` - * `lineCap` - * `lineJoin` - * `miterLimit` - * `dash` - * `fillColor` - * `strokeColor` - * `opacity` - * `fillOpacity` - * `strokeOpacity` +- `lineWidth` +- `lineCap` +- `lineJoin` +- `miterLimit` +- `dash` +- `fillColor` +- `strokeColor` +- `opacity` +- `fillOpacity` +- `strokeOpacity` Some of these are pretty self explanatory, but let's go through a few of them. @@ -139,7 +139,7 @@ should do. This is best illustrated by an example. The output of this example looks like this. - + ## Dashed lines @@ -162,7 +162,7 @@ between the dashes is double the length of each dash. The output of this example looks like this: - + ## Color @@ -186,19 +186,19 @@ that you don't have to call `fillColor` or `strokeColor` beforehand. The This example produces the following output: - + ## Gradients -PDFKit also supports gradient fills. Gradients can be used just like color fills, -and are applied with the same methods (e.g. `fillColor`, or just `fill`). Before +PDFKit also supports gradient fills. Gradients can be used just like color fills, +and are applied with the same methods (e.g. `fillColor`, or just `fill`). Before you can apply a gradient with these methods, however, you must create a gradient object. There are two types of gradients: linear and radial. They are created by the `linearGradient` -and `radialGradient` methods. Their function signatures are listed below: +and `radialGradient` methods. Their function signatures are listed below: -* `linearGradient(x1, y1, x2, y2)` - `x1,y1` is the start point, `x2,y2` is the end point -* `radialGradient(x1, y1, r1, x2, y2, r2)` - `r1` is the inner radius, `r2` is the outer radius +- `linearGradient(x1, y1, x2, y2)` - `x1,y1` is the start point, `x2,y2` is the end point +- `radialGradient(x1, y1, r1, x2, y2, r2)` - `r1` is the inner radius, `r2` is the outer radius Once you have a gradient object, you need to create color stops at points along that gradient. Stops are defined at percentage values (0 to 1), and take a color value (any usable by the @@ -251,7 +251,7 @@ You'll notice that I used the `scale` and `translate` transformations in this example. We'll cover those in a minute. The output of this example, with some added labels, is below. - + ## Saving and restoring the graphics stack @@ -298,7 +298,7 @@ rotation to the center of the rectangle. This example produces the following effect. - + ## Clipping @@ -323,7 +323,7 @@ example that clips a checkerboard pattern to the shape of a circle. The result of this example is the following: - + If you want to "unclip", you can use the `save` method before the clipping, and then use `restore` to retrieve access to the whole page. diff --git a/docs/you_made_it.md b/docs/you_made_it.md index baaa2c80e..14b0ca2a5 100644 --- a/docs/you_made_it.md +++ b/docs/you_made_it.md @@ -12,4 +12,4 @@ a parser for Markdown and a syntax highlighter. If you have any questions about what you've learned in this guide, please don't hesitate to [ask the author](https://twitter.com/devongovett) or post an issue -on [Github](https://github.com/foliojs/pdfkit/issues). Enjoy! \ No newline at end of file +on [Github](https://github.com/foliojs/pdfkit/issues). Enjoy! diff --git a/examples/attachment.js b/examples/attachment.js index 5d45a4d8e..cbbfb6e49 100644 --- a/examples/attachment.js +++ b/examples/attachment.js @@ -12,7 +12,7 @@ doc.info['Title'] = 'Attachment Test'; doc.file(path.join(__dirname, 'images', 'test.png'), { name: 'test.png', type: 'image/png', - description: 'this is a test image' + description: 'this is a test image', }); // add some text @@ -26,7 +26,7 @@ hover over the paperclip to see its description!`); const file = { src: Buffer.from('buffered input!'), name: 'embedded.txt', - creationDate: new Date(2020, 3, 1) + creationDate: new Date(2020, 3, 1), }; // then, add the annotation doc.fileAnnotation(100, 150, 10, doc.currentLineHeight(), file); @@ -36,7 +36,7 @@ doc.fileAnnotation(100, 150, 10, doc.currentLineHeight(), file); // be aware that some PDF Viewers may not render the icon correctly — or not at all doc.fileAnnotation(150, 150, 10, doc.currentLineHeight(), file, { Name: 'Paperclip', - Contents: 'Paperclip attachment' + Contents: 'Paperclip attachment', }); doc.end(); diff --git a/examples/browserify/browser.html b/examples/browserify/browser.html index 73f8cf759..1f9e80785 100644 --- a/examples/browserify/browser.html +++ b/examples/browserify/browser.html @@ -1,52 +1,67 @@ +
+ + + - #editor { - width: 600px; - height: 775px; - margin-right: 20px; - display: inline-block; - } - - iframe { - border: 1px solid black; - } - - - - -Bundled with Browserify
- - - - - - - -