0
# Document Management
1

2
Core document creation, page management, and output control functionality for PDFKit documents.
3

4
## Capabilities
5

6
### PDFDocument Constructor
7

8
Creates a new PDF document with extensive configuration options.
9

10
```javascript { .api }
11
/**
12
 * Creates a new PDF document
13
 * @param options - Document configuration options
14
 */
15
constructor(options?: PDFDocumentOptions);
16

17
interface PDFDocumentOptions {
18
  /** PDF version to generate */
19
  pdfVersion?: '1.3' | '1.4' | '1.5' | '1.6' | '1.7' | '1.7ext3';
20
  /** Enable stream compression (default: true) */
21
  compress?: boolean;
22
  /** Automatically add first page (default: true) */
23
  autoFirstPage?: boolean;
24
  /** Page size as string or [width, height] in points */
25
  size?: PageSize | [number, number];
26
  /** Page orientation */
27
  layout?: 'portrait' | 'landscape';
28
  /** Page margins */
29
  margins?: MarginDefinition;
30
  /** Buffer pages for manipulation */
31
  bufferPages?: boolean;
32
  /** Document metadata */
33
  info?: DocumentInfo;
34
  /** Display document title in viewer */
35
  displayTitle?: boolean;
36
  /** Document language */
37
  lang?: string;
38
  /** PDF subset compliance */
39
  subset?: PDFSubset;
40
  /** Enable tagged PDF for accessibility */
41
  tagged?: boolean;
42
}
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
import PDFDocument from "pdfkit";
49

50
// Basic document
51
const doc = new PDFDocument();
52

53
// A4 document with custom margins
54
const doc2 = new PDFDocument({
55
  size: 'A4',
56
  margins: { top: 50, left: 50, right: 50, bottom: 50 },
57
  info: {
58
    Title: 'My Document',
59
    Author: 'John Doe'
60
  }
61
});
62

63
// Letter size landscape with compression disabled
64
const doc3 = new PDFDocument({
65
  size: 'LETTER',
66
  layout: 'landscape',
67
  compress: false
68
});
69
```
70

71
### Page Management
72

73
Methods for adding, switching between, and managing document pages.
74

75
```javascript { .api }
76
/**
77
 * Add a new page to the document
78
 * @param options - Page-specific options (overrides document defaults)
79
 * @returns Document instance for chaining
80
 */
81
addPage(options?: PageOptions): PDFDocument;
82

83
/**
84
 * Continue on a new page with same settings
85
 * @param options - Page-specific options
86
 * @returns Document instance for chaining
87
 */
88
continueOnNewPage(options?: PageOptions): PDFDocument;
89

90
/**
91
 * Switch to a specific buffered page (requires bufferPages: true)
92
 * @param n - Page number (0-indexed)
93
 * @returns Document instance for chaining
94
 */
95
switchToPage(n: number): PDFDocument;
96

97
/**
98
 * Flush buffered pages to output
99
 * @returns Document instance for chaining
100
 */
101
flushPages(): PDFDocument;
102

103
/**
104
 * Get current buffer range
105
 * @returns Buffer range information
106
 */
107
bufferedPageRange(): { start: number; count: number };
108

109
interface PageOptions {
110
  size?: PageSize | [number, number];
111
  layout?: 'portrait' | 'landscape';
112
  margins?: MarginDefinition;
113
}
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
// Add pages with different sizes
120
doc.addPage()  // Uses document defaults
121
   .addPage({ size: 'A3', layout: 'landscape' })
122
   .addPage({ size: [612, 792], margins: 20 });
123

124
// Working with buffered pages
125
const bufferedDoc = new PDFDocument({ bufferPages: true });
126
bufferedDoc.text('Page 1', 100, 100);
127
bufferedDoc.addPage();
128
bufferedDoc.text('Page 2', 100, 100);
129

130
// Switch back to first page and add more content
131
bufferedDoc.switchToPage(0);
132
bufferedDoc.text('Additional content on page 1', 100, 200);
133

134
// Flush all pages to output
135
bufferedDoc.flushPages();
136
```
137

138
### Document Finalization
139

140
Methods for finalizing and outputting the PDF document.
141

142
```javascript { .api }
143
/**
144
 * Finalize the PDF document and end the stream
145
 * @returns Document instance for chaining
146
 */
147
end(): PDFDocument;
148

149
/**
150
 * Get string representation
151
 * @returns String representation of document
152
 */
153
toString(): string;
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
import fs from 'fs';
160

161
// Output to file
162
const doc = new PDFDocument();
163
doc.pipe(fs.createWriteStream('output.pdf'));
164
doc.text('Hello World', 100, 100);
165
doc.end();
166

167
// Output to buffer
168
const chunks = [];
169
doc.on('data', chunk => chunks.push(chunk));
170
doc.on('end', () => {
171
  const pdfBuffer = Buffer.concat(chunks);
172
  console.log('PDF size:', pdfBuffer.length);
173
});
174
doc.text('Hello World', 100, 100);
175
doc.end();
176
```
177

178
### Reference Management
179

180
Methods for creating PDF object references and managing document structure.
181

182
```javascript { .api }
183
/**
184
 * Create a new PDF reference object
185
 * @param data - Data for the reference
186
 * @returns PDF reference
187
 */
188
ref(data: any): PDFReference;
189

190
/**
191
 * Add content to the current page
192
 * @param data - Content data to add
193
 * @returns Document instance for chaining
194
 */
195
addContent(data: string): PDFDocument;
196
```
197

198
### Named Elements
199

200
Methods for creating named destinations, embedded files, and JavaScript actions.
201

202
```javascript { .api }
203
/**
204
 * Add a named destination for internal linking
205
 * @param name - Destination name
206
 * @param args - Destination arguments
207
 * @returns Document instance for chaining
208
 */
209
addNamedDestination(name: string, ...args: any[]): PDFDocument;
210

211
/**
212
 * Add a named embedded file
213
 * @param name - File name
214
 * @param ref - File reference
215
 * @returns Document instance for chaining
216
 */
217
addNamedEmbeddedFile(name: string, ref: PDFReference): PDFDocument;
218

219
/**
220
 * Add named JavaScript action
221
 * @param name - Action name
222
 * @param js - JavaScript code
223
 * @returns Document instance for chaining
224
 */
225
addNamedJavaScript(name: string, js: string): PDFDocument;
226
```
227

228
## Types
229

230
```javascript { .api }
231
interface DocumentInfo {
232
  Title?: string;
233
  Author?: string;
234
  Subject?: string;
235
  Keywords?: string;
236
  Creator?: string;
237
  Producer?: string;
238
  CreationDate?: Date;
239
  ModDate?: Date;
240
}
241

242
type MarginDefinition = 
243
  | number 
244
  | [number, number] 
245
  | [number, number, number, number] 
246
  | { vertical: number; horizontal: number } 
247
  | { top: number; right: number; bottom: number; left: number };
248

249
type PDFSubset = 
250
  | 'PDF/A-1' | 'PDF/A-1a' | 'PDF/A-1b' 
251
  | 'PDF/A-2' | 'PDF/A-2a' | 'PDF/A-2b' 
252
  | 'PDF/A-3' | 'PDF/A-3a' | 'PDF/A-3b' 
253
  | 'PDF/UA';
254

255
type PageSize = 
256
  | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'A9' | 'A10'
257
  | 'B0' | 'B1' | 'B2' | 'B3' | 'B4' | 'B5' | 'B6' | 'B7' | 'B8' | 'B9' | 'B10'
258
  | 'C0' | 'C1' | 'C2' | 'C3' | 'C4' | 'C5' | 'C6' | 'C7' | 'C8' | 'C9' | 'C10'
259
  | 'RA0' | 'RA1' | 'RA2' | 'RA3' | 'RA4' 
260
  | 'SRA0' | 'SRA1' | 'SRA2' | 'SRA3' | 'SRA4'
261
  | 'EXECUTIVE' | 'FOLIO' | 'LEGAL' | 'LETTER' | 'TABLOID';
262
```
263

264
## Events
265

266
The PDFDocument class emits the following events:
267

268
- `'pageAdded'`: Emitted when a new page is added to the document
269
- `'data'`: Standard Readable stream event for output data chunks
270
- `'end'`: Standard Readable stream event when document is finalized
271
- `'error'`: Standard Readable stream event for errors