0
# Document Outline
1

2
PDF bookmarks and navigation structure for creating organized document outlines with hierarchical navigation.
3

4
## Capabilities
5

6
### Outline Management
7

8
Access and manipulate the document outline (bookmarks) for navigation.
9

10
```javascript { .api }
11
/**
12
 * Access the document outline for adding bookmarks
13
 * Available as a property on the PDFDocument instance
14
 */
15
document.outline: PDFOutline;
16

17
interface PDFOutline {
18
  /**
19
   * Add an item to the document outline
20
   * @param title - Display title for the bookmark
21
   * @param options - Outline item options
22
   * @returns The created outline item
23
   */
24
  addItem(title: string, options?: OutlineOptions): PDFOutlineItem;
25
}
26
```
27

28
### Outline Item Creation
29

30
Create bookmarks that link to specific pages and destinations within the document.
31

32
```javascript { .api }
33
interface OutlineOptions {
34
  /** Whether the outline item is expanded by default */
35
  expanded?: boolean;
36
  /** Named destination to link to */
37
  destination?: string;
38
  /** Page number to link to (0-indexed) */
39
  page?: number;
40
  /** Specific coordinates on the page */
41
  x?: number;
42
  y?: number;
43
  /** Zoom level for the destination view */
44
  zoom?: number;
45
}
46

47
interface PDFOutlineItem {
48
  /** The title of this outline item */
49
  title: string;
50
  /** Child outline items */
51
  children: PDFOutlineItem[];
52
  /** Add a child item to this outline item */
53
  addItem(title: string, options?: OutlineOptions): PDFOutlineItem;
54
}
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
// Create basic outline structure
61
const chapter1 = doc.outline.addItem('Chapter 1: Introduction');
62
const chapter2 = doc.outline.addItem('Chapter 2: Getting Started');
63
const chapter3 = doc.outline.addItem('Chapter 3: Advanced Topics');
64

65
// Add sub-sections to chapters
66
chapter1.addItem('1.1 Overview');
67
chapter1.addItem('1.2 Requirements');
68
chapter1.addItem('1.3 Installation');
69

70
chapter2.addItem('2.1 Basic Usage');
71
chapter2.addItem('2.2 Configuration');
72

73
chapter3.addItem('3.1 Advanced Features');
74
chapter3.addItem('3.2 Best Practices');
75
```
76

77
### Named Destinations
78

79
Create named destinations for precise navigation and linking.
80

81
```javascript { .api }
82
/**
83
 * Add a named destination for navigation
84
 * @param name - Unique name for the destination
85
 * @param type - Destination type ('XYZ', 'Fit', 'FitH', etc.)
86
 * @param x - X coordinate (optional)
87
 * @param y - Y coordinate (optional)  
88
 * @param zoom - Zoom level (optional)
89
 * @returns Document instance for chaining
90
 */
91
addNamedDestination(name: string, type?: string, x?: number, y?: number, zoom?: number): PDFDocument;
92
```
93

94
**Destination Types:**
95
- `'XYZ'` - Display page with specific coordinates and zoom
96
- `'Fit'` - Fit entire page in window
97
- `'FitH'` - Fit page width in window
98
- `'FitV'` - Fit page height in window  
99
- `'FitR'` - Fit rectangle in window
100
- `'FitB'` - Fit bounding box in window
101
- `'FitBH'` - Fit bounding box width in window
102
- `'FitBV'` - Fit bounding box height in window
103

104
**Usage Examples:**
105

106
```javascript
107
// Create named destinations for different sections
108
doc.addNamedDestination('intro', 'XYZ', 100, 700, 1.0);
109
doc.addNamedDestination('chapter1', 'FitH', null, 600);
110
doc.addNamedDestination('conclusion', 'Fit');
111

112
// Link outline items to named destinations
113
doc.outline.addItem('Introduction', { destination: 'intro' });
114
doc.outline.addItem('Chapter 1', { destination: 'chapter1' });
115
doc.outline.addItem('Conclusion', { destination: 'conclusion' });
116
```
117

118
### Hierarchical Outline Structure
119

120
Create complex nested outline structures for comprehensive document navigation.
121

122
**Usage Examples:**
123

124
```javascript
125
// Create comprehensive document outline
126
const titlePage = doc.outline.addItem('Title Page', { page: 0 });
127

128
const toc = doc.outline.addItem('Table of Contents', { page: 1 });
129

130
const part1 = doc.outline.addItem('Part I: Fundamentals', { expanded: true });
131
const chapter1 = part1.addItem('Chapter 1: Introduction');
132
chapter1.addItem('1.1 What is PDFKit?', { destination: 'section_1_1' });
133
chapter1.addItem('1.2 Key Features', { destination: 'section_1_2' });
134
chapter1.addItem('1.3 Getting Started', { destination: 'section_1_3' });
135

136
const chapter2 = part1.addItem('Chapter 2: Basic Usage');
137
chapter2.addItem('2.1 Creating Documents', { destination: 'section_2_1' });
138
chapter2.addItem('2.2 Adding Content', { destination: 'section_2_2' });
139

140
const part2 = doc.outline.addItem('Part II: Advanced Topics', { expanded: false });
141
const chapter3 = part2.addItem('Chapter 3: Advanced Features');
142
chapter3.addItem('3.1 Custom Fonts', { destination: 'section_3_1' });
143
chapter3.addItem('3.2 Vector Graphics', { destination: 'section_3_2' });
144
chapter3.addItem('3.3 Interactive Elements', { destination: 'section_3_3' });
145

146
const appendix = doc.outline.addItem('Appendices');
147
appendix.addItem('Appendix A: API Reference', { destination: 'appendix_a' });
148
appendix.addItem('Appendix B: Examples', { destination: 'appendix_b' });
149
```
150

151
### Outline Styling and Behavior
152

153
Control the appearance and behavior of outline items.
154

155
**Usage Examples:**
156

157
```javascript
158
// Create outline with mixed expansion states
159
const userGuide = doc.outline.addItem('User Guide', { expanded: true });
160
const quickStart = userGuide.addItem('Quick Start', { expanded: true });
161
const advanced = userGuide.addItem('Advanced Usage', { expanded: false });
162

163
// Link to specific page coordinates
164
const figures = doc.outline.addItem('List of Figures');
165
figures.addItem('Figure 1: Architecture', { 
166
  page: 5, 
167
  x: 100, 
168
  y: 400,
169
  zoom: 1.5 
170
});
171
figures.addItem('Figure 2: Workflow', { 
172
  page: 8, 
173
  x: 50, 
174
  y: 300,
175
  zoom: 1.25 
176
});
177
```
178

179
## Best Practices
180

181
### Outline Organization
182

183
```javascript
184
// Use consistent naming conventions
185
const manual = doc.outline.addItem('User Manual');
186

187
// Group related sections
188
const installation = manual.addItem('Installation');
189
installation.addItem('System Requirements');
190
installation.addItem('Download and Install');
191
installation.addItem('Configuration');
192

193
const usage = manual.addItem('Usage');
194
usage.addItem('Basic Operations');
195
usage.addItem('Advanced Features');
196
usage.addItem('Troubleshooting');
197
```
198

199
### Dynamic Outline Generation
200

201
```javascript
202
// Build outline from content structure
203
const sections = [
204
  { title: 'Introduction', page: 0 },
205
  { title: 'Installation', page: 2 },
206
  { title: 'Usage', page: 5 },
207
  { title: 'API Reference', page: 10 }
208
];
209

210
sections.forEach(section => {
211
  doc.outline.addItem(section.title, { page: section.page });
212
});
213
```
214

215
### Cross-Reference Management
216

217
```javascript
218
// Create destinations as content is added
219
doc.addNamedDestination('fig_1', 'XYZ', 100, 400, 1.0);
220
doc.text('Figure 1: System Architecture', 100, 380);
221

222
// Reference in outline
223
doc.outline.addItem('Figures')
224
  .addItem('Figure 1: System Architecture', { destination: 'fig_1' });
225
```