@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.4

package/docs/pages/recipes/images-and-vectors.md

@@ -0,0 +1,216 @@
+---
+title: "Images and vectors"
+description: "Shapes, a dashed curve, gray, RGB, CMYK and hex colour, transparency, a blend mode, a clip, a rotation, a JPEG and an RGBA image on one page."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/images-and-vectors/"
+---
+
+# Images and vectors
+
+Shapes, a dashed curve, gray, RGB, CMYK and hex colour, transparency, a blend mode, a clip, a rotation, a JPEG and an RGBA image on one page.
+
+You'll draw shapes and images on one A4 page: a rectangle, a circle, a dashed curve, two see-through discs, a photo cut to an ellipse and a rotated gradient that fades out. Start from it for a logo, a chart, the rules of a table or a page with photos.
+
+The function takes a JPEG's bytes, draws the page and returns the PDF's bytes. It draws no text, so in TypeScript it needs only the base module, `init()`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/images-and-vectors.ts`:
+
+```ts
+// Images and vector graphics on one A4 page. It draws shapes and a dashed Bézier curve in gray,
+// RGB, CMYK and hex colour, overlaps two translucent discs with a blend mode, clips a JPEG to an
+// ellipse and rotates an RGBA image with a soft mask. Needs only the base module.
+import { Builder, type BuilderOptions, Image, Matrix, type Surface } from "@laminapdf/sdk";
+
+/** The RGBA gradient's side, in pixels. */
+const GLOW_SIDE = 16;
+
+/**
+ * The document's bytes, with `photo` (a JPEG) on the page.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function imagesAndVectors(photo: Uint8Array, options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const jpeg = Image.jpeg(photo);
+  const glow = Image.rgba(GLOW_SIDE, GLOW_SIDE, gradient());
+  const page = b.page("A4");
+  const s = page.surface();
+  shapes(s);
+  overlappingDiscs(s);
+  images(s, jpeg, glow);
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** A square gradient whose alpha falls off towards the right. */
+function gradient(): Uint8Array {
+  const out = new Uint8Array(GLOW_SIDE * GLOW_SIDE * 4);
+  for (let y = 0; y < GLOW_SIDE; y++) {
+    for (let x = 0; x < GLOW_SIDE; x++) out.set([x * 16, y * 16, 200, 255 - x * 15], (y * GLOW_SIDE + x) * 4);
+  }
+  return out;
+}
+
+/** A rectangle, a circle and a dashed, round-capped Bézier curve. */
+function shapes(s: Surface): void {
+  s.fillColor([0.9, 0.3, 0.2])
+    .path((p) => p.rect([56, 56, 160, 100]))
+    .fill();
+  s.fillColor([0.8, 0.1, 0, 0])
+    .path((p) => p.circle([330, 106], 50))
+    .fill();
+  s.strokeColor("#2a9d8f")
+    .path((p) => p.moveTo(56, 220).cubicTo(180, 140, 300, 300, 539, 200))
+    .stroke({ width: 3, cap: "round", dash: [12, 8] });
+}
+
+/** Two translucent discs, the second multiplied onto the first. */
+function overlappingDiscs(s: Surface): void {
+  s.save().opacity(0.6, 1).fillColor([0.3]);
+  s.path((p) => p.circle([120, 330], 60)).fill();
+  s.blendMode("multiply").fillColor([1, 0.8, 0]);
+  s.path((p) => p.circle([190, 330], 60))
+    .fill()
+    .restore();
+}
+
+/** The photo clipped to an ellipse, and the gradient rotated by 30 degrees. */
+function images(s: Surface, photo: Image, glow: Image): void {
+  s.save()
+    .path((p) => p.ellipse([300, 270, 239, 120]))
+    .clip();
+  s.image(photo, [300, 250, 239, 160]).restore();
+  s.save().transform(Matrix.after(Matrix.translate(150, 520), Matrix.rotate(30)));
+  s.image(glow, [-60, -60, 120, 120]).restore();
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/images_and_vectors.rs`:
+
+````rust
+//! Images and vector graphics on one A4 page.
+//!
+//! It draws shapes and a dashed Bézier curve in gray, RGB, CMYK and hex colour, overlaps two
+//! translucent discs with a blend mode, clips a JPEG to an ellipse and rotates an RGBA image
+//! with a soft mask.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example images_and_vectors -- photo.jpg [out-dir]   # writes images_and_vectors.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BlendMode, BuildOptions, Builder, Color, Dash, FillRule, Image, LineCap, Matrix, PageSize, PathBuilder, PointPt,
+    Pt, RectPt, SaveOptions, StrokeStyle, Surface,
+};
+
+/// The RGBA gradient's side, in pixels.
+const GLOW_SIDE: u8 = 16;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let photo = std::fs::read(args.next().ok_or("usage: images_and_vectors <photo.jpg> [out-dir]")?)?;
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("images_and_vectors.pdf"), build(BuildOptions::new(), photo)?)?;
+    Ok(())
+}
+
+/// The document's bytes, with `photo` (a JPEG) on the page. `options` can fix the file ID, the
+/// producer and the creation date.
+pub(crate) fn build(options: BuildOptions, photo: Vec<u8>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let photo = Image::jpeg(photo)?;
+    let glow = Image::rgba(u32::from(GLOW_SIDE), u32::from(GLOW_SIDE), &gradient())?;
+    let mut page = b.page(PageSize::A4);
+    let s = page.surface();
+    shapes(s)?;
+    overlapping_discs(s);
+    images(s, &photo, &glow);
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+/// A square gradient whose alpha falls off towards the right.
+fn gradient() -> Vec<u8> {
+    (0..GLOW_SIDE)
+        .flat_map(|y| (0..GLOW_SIDE).flat_map(move |x| [x * 16, y * 16, 200, 255 - x * 15]))
+        .collect()
+}
+
+/// A rectangle, a circle and a dashed, round-capped Bézier curve.
+fn shapes(s: &mut Surface) -> Result<(), Box<dyn Error>> {
+    let at = PointPt::from_points;
+    s.fill_color(Color::rgb(0.9, 0.3, 0.2))
+        .path(|p| _ = p.rect(RectPt::from_points(56.0, 56.0, 160.0, 100.0)))
+        .fill(FillRule::NonZero);
+    s.fill_color(Color::cmyk(0.8, 0.1, 0.0, 0.0))
+        .path(|p| _ = p.circle(at(330.0, 106.0), Pt::new(50.0)))
+        .fill(FillRule::NonZero);
+    let dashed = StrokeStyle {
+        width: Pt::new(3.0),
+        cap: LineCap::Round,
+        dash: Some(Dash::new(vec![12.0, 8.0], 0.0)),
+        ..StrokeStyle::default()
+    };
+    s.stroke_color(Color::hex("#2a9d8f")?)
+        .path(|p| {
+            p.move_to(at(56.0, 220.0))
+                .cubic_to(at(180.0, 140.0), at(300.0, 300.0), at(539.0, 200.0));
+        })
+        .stroke(&dashed);
+    Ok(())
+}
+
+/// Two translucent discs, the second multiplied onto the first.
+fn overlapping_discs(s: &mut Surface) {
+    let disc = |x: f64| move |p: &mut PathBuilder| _ = p.circle(PointPt::from_points(x, 330.0), Pt::new(60.0));
+    s.save().opacity(0.6, 1.0).fill_color(Color::gray(0.3));
+    s.path(disc(120.0)).fill(FillRule::NonZero);
+    s.blend_mode(BlendMode::Multiply).fill_color(Color::rgb(1.0, 0.8, 0.0));
+    s.path(disc(190.0)).fill(FillRule::NonZero).restore();
+}
+
+/// The photo clipped to an ellipse, and the gradient rotated by 30 degrees.
+fn images(s: &mut Surface, photo: &Image, glow: &Image) {
+    s.save()
+        .path(|p| _ = p.ellipse(RectPt::from_points(300.0, 270.0, 239.0, 120.0)))
+        .clip(FillRule::NonZero);
+    s.image(photo, RectPt::from_points(300.0, 250.0, 239.0, 160.0))
+        .restore();
+    let placement = Matrix::translate(150.0, 520.0).after(&Matrix::rotate(30.0));
+    s.save().transform(placement);
+    s.image(glow, RectPt::from_points(-60.0, -60.0, 120.0, 120.0)).restore();
+}
+````
+
+**Result:** [images_and_vectors.pdf](https://docs.laminapdf.com/examples/pdf/images_and_vectors.pdf)
+
+The result is one A4 page with every shape and both images. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+- `path(p => …)` builds a shape and returns it unpainted. `fill` and `stroke` paint it, and `clip` limits what's drawn next to its inside. See [Shapes, colour and images](../../pages/guides/images-and-vectors.md).
+- A colour of one, three or four numbers from 0 to 1 is gray, RGB or CMYK, and a string such as `"#2a9d8f"` is hex. Rust has `Color::gray`, `rgb`, `cmyk` and `hex`.
+- `save()` and `restore()` bracket each group of drawings, so the opacity, blend mode, clip and rotation set inside stop at `restore()`.
+- Both discs are 60% opaque, and `multiply` darkens the area where the second disc covers the first.
+- `Image.jpeg` embeds the photo as it is, without decoding it. `Image.rgba` takes raw pixels, and their alpha becomes a soft mask: a second image that holds the transparency.
+- The matrix turns the gradient 30 degrees clockwise, then moves it to (150, 520). The gradient is drawn centred on the origin, so it turns about its own centre. Like every position, the matrix works in [page space](../../pages/reference/glossary.md#page-space).
+
+## What to change
+
+- **A PNG instead of the JPEG:** `Image.png(bytes)` (`Image::png` in Rust) keeps the PNG's transparency.
+- **A shape with a hole:** draw both outlines in one path and fill it with `"evenOdd"` (`FillRule::EvenOdd`), so the inner shape stays empty.
+- **A filled shape with an outline:** `fillStroke(rule, style)` (`fill_stroke` in Rust) paints both at once.
+- **Another blend mode:** `"screen"` lightens where `"multiply"` darkens. `BlendMode` lists all sixteen.
+- **Alternate text:** pass a description as the third argument of `image` (`figure` in Rust), and a screen reader reads it out. See [Accessible PDFs](../../pages/guides/accessible-pdfs.md).
+
+Next: [links and outlines](../../pages/recipes/links-and-outlines.md), with four pages joined by links, an outline and page labels.

package/docs/pages/recipes/invoice.md

@@ -0,0 +1,233 @@
+---
+title: "An invoice"
+description: "A tagged one-page invoice with an embedded font, a table of line items with right-aligned amounts and a total, in TypeScript and Rust."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/invoice/"
+---
+
+# An invoice
+
+A tagged one-page invoice with an embedded font, a table of line items with right-aligned amounts and a total, in TypeScript and Rust.
+
+You'll make a one-page invoice: a heading, an address, a table of line items with right-aligned amounts, and a total. It's tagged, so a screen reader reads it in order. Start from it for any document built around a table, such as a quote or a receipt.
+
+The function takes a font file, draws the invoice and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/invoice.ts`:
+
+```ts
+// An invoice that screen readers can follow, with an embedded font and a table of line items.
+// The heading, the address, the table of items and the total are tagged, so a screen reader
+// reads them in order.
+import { Builder, type BuilderOptions, Font, PAGE_SIZES, type Rect, type Surface } from "@laminapdf/sdk";
+
+const ITEMS: readonly (readonly [item: string, qty: number, price: number])[] = [
+  ["Widgets, blue (W-100)", 3, 12.0],
+  ["Gadget with fine-tuned dials", 1, 79.9],
+  ["Café-grade sprockets", 12, 1.25],
+  ["Delivery", 1, 4.5],
+];
+const ADDRESS = "Acme Widgets Ltd · 1 Example Street · London";
+const PAGE = "A4";
+const [PAGE_WIDTH] = PAGE_SIZES[PAGE];
+const MARGIN = 56;
+const RIGHT_EDGE = PAGE_WIDTH - MARGIN;
+const TITLE_AT = [MARGIN, 80] as const;
+const ADDRESS_AT = [MARGIN, 100] as const;
+const TITLE = 24;
+const BODY = 11;
+const FIRST_ROW = 160;
+const ROW_HEIGHT = 24;
+/** The quantity's and the amount's columns, each a width ending this far left of the right edge. */
+const COLUMNS = [
+  [40, 169],
+  [100, 0],
+] as const;
+/** A cell's box starts this far above its row's baseline and is this tall. */
+const CELL_RISE = 12;
+const CELL_HEIGHT = 16;
+
+/**
+ * The document's bytes, in `fontBytes` (a TrueType or OpenType file). Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function invoice(fontBytes: Uint8Array, options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder({ ...options, tagged: true });
+  const font = Font.fromBytes(fontBytes);
+  const bold = Font.standard("Helvetica-Bold");
+  // Registered up front, in this order, so the embedded font is the document's first.
+  b.font(font);
+  b.font(bold);
+  const page = b.page(PAGE);
+  const s = page.surface();
+  s.text("Invoice 42", { font: bold, size: TITLE, at: TITLE_AT, tag: "H1" });
+  s.text(ADDRESS, { font, size: BODY, at: ADDRESS_AT, tag: "P" });
+  items(s, font);
+  const total = ITEMS.reduce((sum, [, qty, price]) => sum + qty * price, 0);
+  const box = cell(COLUMNS[1], rowBaseline(ITEMS.length));
+  s.textBox(`Total € ${total.toFixed(2)}`, { font, size: BODY, box, align: "end", tag: "P" });
+  page.finish();
+  b.metadata({ title: "Invoice 42", author: "Acme Widgets Ltd" }).lang("en-GB");
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** The table of line items: what, how many, and the amount, right-aligned. */
+function items(s: Surface, font: Font): void {
+  s.tag("Table", (s) => {
+    ITEMS.forEach(([item, qty, price], row) => {
+      const y = rowBaseline(row);
+      const cells = [
+        [String(qty), COLUMNS[0]],
+        [`€ ${(qty * price).toFixed(2)}`, COLUMNS[1]],
+      ] as const;
+      s.tag("TR", (s) => {
+        s.text(item, { font, size: BODY, at: [MARGIN, y], tag: "TD" });
+        for (const [text, column] of cells) {
+          s.textBox(text, { font, size: BODY, box: cell(column, y), align: "end", tag: "TD" });
+        }
+      });
+    });
+  });
+}
+
+/** The baseline of row `row` of the table. */
+function rowBaseline(row: number): number {
+  return FIRST_ROW + ROW_HEIGHT * row;
+}
+
+/** The box of a cell in `column` (width, distance from the right edge) on the row at `baseline`. */
+function cell([width, inset]: readonly [number, number], baseline: number): Rect {
+  return [RIGHT_EDGE - inset - width, baseline - CELL_RISE, width, CELL_HEIGHT];
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/invoice.rs`:
+
+```rust
+//! An invoice that screen readers can follow, with an embedded font and a table of line items.
+//!
+//! The heading, the address, the table of items and the total are tagged, so a screen reader
+//! reads them in order. Run it with `cargo run -p laminapdf --example invoice -- <font.ttf> [out-dir]`.
+
+use laminapdf::{
+    Alignment, BuildError, BuildOptions, Builder, FontHandle, Metadata, PageSize, PointPt, Pt, RectPt, SaveOptions,
+    Standard14, Surface, TagKind, TextBoxOptions,
+};
+
+const ITEMS: [(&str, u32, f64); 4] = [
+    ("Widgets, blue (W-100)", 3, 12.00),
+    ("Gadget with fine-tuned dials", 1, 79.90),
+    ("Café-grade sprockets", 12, 1.25),
+    ("Delivery", 1, 4.50),
+];
+const ADDRESS: &str = "Acme Widgets Ltd · 1 Example Street · London";
+const PAGE: PageSize = PageSize::A4;
+const MARGIN: f64 = 56.0;
+const RIGHT_EDGE: f64 = PAGE.width.get() - MARGIN;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 80.0);
+const ADDRESS_AT: PointPt = PointPt::from_points(MARGIN, 100.0);
+const TITLE: Pt = Pt::new(24.0);
+const BODY: Pt = Pt::new(11.0);
+const FIRST_ROW: f64 = 160.0;
+const ROW_HEIGHT: f64 = 24.0;
+/// The quantity's and the amount's columns, each a width ending this far left of the right edge.
+const COLUMNS: [(f64, f64); 2] = [(40.0, 169.0), (100.0, 0.0)];
+/// A cell's box starts this far above its row's baseline and is this tall.
+const CELL_RISE: f64 = 12.0;
+const CELL_HEIGHT: f64 = 16.0;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let font = std::fs::read(args.next().ok_or("usage: invoice <font.ttf> [out-dir]")?)?;
+    let out = std::path::PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let pdf = build(BuildOptions::new(), font)?;
+    Ok(std::fs::write(out.join("invoice.pdf"), pdf)?)
+}
+
+/// The bytes, in `font` (TrueType or OpenType); `options` can fix the file ID, producer and date.
+pub(crate) fn build(options: BuildOptions, font: Vec<u8>) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
+    let mut b = Builder::new(options.with_tagged(true));
+    draw(&mut b, font)?;
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// Draws the invoice's one page into `b` and sets its title, author and language.
+pub(crate) fn draw(b: &mut Builder, font: Vec<u8>) -> Result<(), Box<dyn std::error::Error>> {
+    let (font, bold) = (b.font_bytes(font)?, b.standard_font(Standard14::HelveticaBold)?);
+    let mut page = b.page(PAGE);
+    let s = page.surface();
+    s.text("Invoice 42", &bold, TITLE, TITLE_AT)?.tag(TagKind::H1);
+    s.text(ADDRESS, &font, BODY, ADDRESS_AT)?.tag(TagKind::P);
+    items(s, &font)?;
+    let total: f64 = ITEMS.iter().map(|(_, qty, price)| f64::from(*qty) * price).sum();
+    let (total, below_items) = (format!("Total € {total:.2}"), u32::try_from(ITEMS.len())?);
+    let area = cell(COLUMNS[1], row_baseline(below_items));
+    s.tag(TagKind::P, |s| right_aligned(s, &font, &total, area))?;
+    page.finish()?;
+    let metadata = Metadata::default().with_title("Invoice 42");
+    b.metadata(metadata.with_author("Acme Widgets Ltd")).lang("en-GB");
+    Ok(())
+}
+
+/// The table of line items: what, how many, and the amount, right-aligned.
+fn items(s: &mut Surface, font: &FontHandle) -> Result<(), BuildError> {
+    s.tag(TagKind::Table, |s| {
+        for (row, (item, qty, price)) in (0_u32..).zip(ITEMS) {
+            let y = row_baseline(row);
+            s.tag(TagKind::TR, |s| {
+                s.text(item, font, BODY, PointPt::from_points(MARGIN, y))?
+                    .tag(TagKind::TD);
+                let amount = format!("€ {:.2}", f64::from(qty) * price);
+                for (text, column) in [qty.to_string(), amount].iter().zip(COLUMNS) {
+                    s.tag(TagKind::TD, |s| right_aligned(s, font, text, cell(column, y)))?;
+                }
+                Ok(())
+            })?;
+        }
+        Ok(())
+    })
+}
+
+/// The baseline of row `row` of the table.
+fn row_baseline(row: u32) -> f64 {
+    FIRST_ROW + ROW_HEIGHT * f64::from(row)
+}
+
+/// The box of a cell in `column` (width, distance from the right edge) on the row at `baseline`.
+fn cell((width, inset): (f64, f64), baseline: f64) -> RectPt {
+    RectPt::from_points(RIGHT_EDGE - inset - width, baseline - CELL_RISE, width, CELL_HEIGHT)
+}
+
+/// `text` in `area`, in the body size, aligned to its right edge.
+fn right_aligned(s: &mut Surface, font: &FontHandle, text: &str, area: RectPt) -> Result<(), BuildError> {
+    let right = TextBoxOptions::new().with_align(Alignment::End);
+    s.text_box(text, font, BODY, area, &right).map(|_| ())
+}
+```
+
+**Result:** [invoice.pdf](https://docs.laminapdf.com/examples/pdf/invoice.pdf)
+
+The result is one A4 page with its body set in Noto Sans. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+- The body uses your font file, and Lamina PDF embeds only the glyphs the invoice draws. The heading uses Helvetica Bold, one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts), so it embeds nothing.
+- Each quantity and amount is a text box aligned to its `end`, so the numbers line up on the right. `cell` works out each box from its column's width and its distance from the right margin.
+- `tagged: true` (`with_tagged(true)` in Rust) gives the document a structure for screen readers. The `tag` option and `s.tag(…)` make the heading an `H1`, the address and the total each a paragraph (`P`), and the items a `Table` of rows (`TR`) and cells (`TD`).
+- `metadata` sets the title and author, and `lang("en-GB")` tells a screen reader which language to speak.
+
+## What to change
+
+- **The line items:** edit `ITEMS`. Each row sits `ROW_HEIGHT` points below the one before, and the total follows the last row.
+- **The columns:** each pair in `COLUMNS` is a column's width and its distance from the right margin, in points.
+- **The currency:** change the `€` in the amount and total strings. Your font needs a glyph for the new symbol, or drawing fails with `missing-glyph`. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+- **A PDF/UA-1 invoice:** add `profiles: ["PDF/UA-1"]` (`with_profile(Profile::PdfUa1)` in Rust) to check the rules for accessible PDFs. PDF/UA-1 needs every font embedded, so load a bold font file for the heading. See [Accessible PDFs](../../pages/guides/accessible-pdfs.md).
+
+Next: [multilingual text](../../pages/recipes/multilingual.md), with five scripts, each in its own embedded font.

package/docs/pages/recipes/links-and-outlines.md

@@ -0,0 +1,222 @@
+---
+title: "Links and outlines"
+description: "Four A5 pages joined by web, page and named links, with a nested outline, page labels that read i, ii, 1, 2 and the outline shown on open."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/links-and-outlines/"
+---
+
+# Links and outlines
+
+Four A5 pages joined by web, page and named links, with a nested outline, page labels that read i, ii, 1, 2 and the outline shown on open.
+
+You'll make four A5 pages joined by links to a website and between pages, an outline (the bookmarks panel) and page numbers that read i, ii, 1, 2. Start from it for a manual, a report or any document longer than a page or two.
+
+The function draws the four pages, links them and returns the PDF's bytes. It draws text, so in TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/links-and-outlines.ts`:
+
+```ts
+// Links and outlines: four A5 pages joined by links, bookmarks and page labels. The title page
+// links to a website, to a page and through a named destination; every other page has a linked
+// text run back to it. The outline is nested and shown when the file opens.
+import { Builder, type BuilderOptions, Font, type LinkTarget, type Surface } from "@laminapdf/sdk";
+
+const TITLES = ["Title page", "Contents", "Chapter 1", "Chapter 2"] as const;
+const MARGIN = 36;
+const TITLE_BASELINE = 60;
+const TITLE_SIZE = 18;
+const LINK_SIZE = 12;
+/** The baselines of the title page's three links. */
+const LINK_BASELINES = [100, 125, 150] as const;
+/** A link's clickable box: this wide, this tall, starting this far above the baseline. */
+const LINK_WIDTH = 220;
+const LINK_HEIGHT = 20;
+const LINK_RISE = 15;
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function linksAndOutlines(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const font = Font.standard("Helvetica");
+  b.font(font);
+  b.destination("chapter-2", 3);
+  TITLES.forEach((title, index) => {
+    const page = b.page("A5");
+    const s = page.surface();
+    s.text(title, { font, size: TITLE_SIZE, at: [MARGIN, TITLE_BASELINE] });
+    if (index === 0) titlePageLinks(s, font);
+    else {
+      const link = { target: { type: "page", index: 0 }, contents: "Title page" } as const;
+      s.text("Back to the title page", { font, size: LINK_SIZE, at: [MARGIN, 100], fill: [0, 0.2, 0.8], link });
+    }
+    page.finish();
+  });
+  navigation(b);
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** The title page's links: to a website, to a page, and to a named destination. */
+function titlePageLinks(s: Surface, font: Font): void {
+  const links: readonly (readonly [label: string, target: LinkTarget, contents?: string])[] = [
+    ["Visit example.com", { type: "uri", uri: "https://example.com/" }, "Example"],
+    ["Go to chapter 1", { type: "page", index: 2 }],
+    ["Go to chapter 2 (named)", { type: "named", name: "chapter-2" }],
+  ];
+  links.forEach(([label, target, contents], i) => {
+    const baseline = LINK_BASELINES[i] ?? 0;
+    s.text(label, { font, size: LINK_SIZE, at: [MARGIN, baseline] });
+    s.link([MARGIN, baseline - LINK_RISE, LINK_WIDTH, LINK_HEIGHT], target, contents);
+  });
+}
+
+/** The outline (bookmarks), the page labels, and the viewer opening with the outline shown. */
+function navigation(b: Builder): void {
+  b.outline([
+    { title: "Title page", target: { type: "page", index: 0 } },
+    { title: "Contents", target: { type: "page", index: 1 }, color: [0, 0, 0.6] },
+    {
+      title: "Chapters",
+      open: true,
+      bold: true,
+      children: [
+        { title: "Chapter 1", target: { type: "page", index: 2 } },
+        { title: "Chapter 2", target: { type: "named", name: "chapter-2" }, italic: true },
+      ],
+    },
+  ]);
+  b.pageLabels([
+    { start: 0, style: "lowerRoman" },
+    { start: 2, style: "decimal" },
+  ]).viewerPreferences({ pageMode: "outlines" });
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/links_and_outlines.rs`:
+
+````rust
+//! Links and outlines: four A5 pages joined by links, bookmarks and page labels.
+//!
+//! The title page has a URI link, a link to a page and one through a named destination; every
+//! other page has a linked text run back to it. The outline (bookmarks) is nested and open in
+//! the viewer, and the pages are labelled i, ii, 1, 2.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example links_and_outlines -- [out-dir]   # writes <out-dir>/links_and_outlines.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BuildOptions, Builder, Color, Fit, FontHandle, LabelStyle, LinkTarget, OutlineEntry, PageLabel, PageMode, PageSize,
+    PointPt, Pt, RectPt, SaveOptions, Standard14, Surface, ViewerPreferences,
+};
+
+const TITLES: [&str; 4] = ["Title page", "Contents", "Chapter 1", "Chapter 2"];
+const MARGIN: f64 = 36.0;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 60.0);
+const BACK_AT: PointPt = PointPt::from_points(MARGIN, 100.0);
+const TITLE_SIZE: Pt = Pt::new(18.0);
+const LINK_SIZE: Pt = Pt::new(12.0);
+/// The baselines of the title page's three links.
+const LINK_BASELINES: [f64; 3] = [100.0, 125.0, 150.0];
+/// A link's clickable box: this wide, this tall, starting this far above the baseline.
+const LINK_WIDTH: f64 = 220.0;
+const LINK_HEIGHT: f64 = 20.0;
+const LINK_RISE: f64 = 15.0;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let out = PathBuf::from(std::env::args().nth(1).unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("links_and_outlines.pdf"), build(BuildOptions::new())?)?;
+    Ok(())
+}
+
+/// The document's bytes. `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    b.destination("chapter-2", 3, Fit::Page);
+    for (index, title) in (0_u32..).zip(TITLES) {
+        let mut page = b.page(PageSize::A5);
+        let s = page.surface();
+        s.text(title, &helvetica, TITLE_SIZE, TITLE_AT)?;
+        if index == 0 {
+            title_page_links(s, &helvetica)?;
+        } else {
+            s.text("Back to the title page", &helvetica, LINK_SIZE, BACK_AT)?
+                .fill(Color::rgb(0.0, 0.2, 0.8))
+                .link(LinkTarget::page(0), Some("Title page".into()));
+        }
+        page.finish()?;
+    }
+    navigation(&mut b)?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+/// The title page's links: to a website, to a page, and to a named destination.
+fn title_page_links(s: &mut Surface, font: &FontHandle) -> Result<(), Box<dyn Error>> {
+    let site = LinkTarget::Uri("https://example.com/".into());
+    let links = [
+        ("Visit example.com", site, Some("Example")),
+        ("Go to chapter 1", LinkTarget::page(2), None),
+        ("Go to chapter 2 (named)", LinkTarget::Named("chapter-2".into()), None),
+    ];
+    for ((label, target, contents), baseline) in links.into_iter().zip(LINK_BASELINES) {
+        s.text(label, font, LINK_SIZE, PointPt::from_points(MARGIN, baseline))?;
+        let area = RectPt::from_points(MARGIN, baseline - LINK_RISE, LINK_WIDTH, LINK_HEIGHT);
+        s.link(area, target, contents.map(String::from));
+    }
+    Ok(())
+}
+
+/// The outline (bookmarks), the page labels, and the viewer opening with the outline shown.
+fn navigation(b: &mut Builder) -> Result<(), Box<dyn Error>> {
+    b.outline(vec![
+        OutlineEntry::new("Title page", LinkTarget::page(0)),
+        OutlineEntry::new("Contents", LinkTarget::page(1)).with_color(0.0, 0.0, 0.6),
+        OutlineEntry::heading("Chapters")
+            .open(true)
+            .bold()
+            .with_child(OutlineEntry::new("Chapter 1", LinkTarget::page(2)))
+            .with_child(OutlineEntry::new("Chapter 2", LinkTarget::Named("chapter-2".into())).italic()),
+    ])?;
+    b.page_labels(vec![
+        PageLabel::new(0, Some(LabelStyle::LowerRoman)),
+        PageLabel::new(2, Some(LabelStyle::Decimal)),
+    ])
+    .viewer_preferences(ViewerPreferences::default().with_page_mode(PageMode::Outlines));
+    Ok(())
+}
+````
+
+**Result:** [links_and_outlines.pdf](https://docs.laminapdf.com/examples/pdf/links_and_outlines.pdf)
+
+The result is four A5 pages with an outline and page labels. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+- `s.link(rect, target, contents)` puts a clickable box over each label on the title page. A target is a web address (`uri`), a page by its index from 0, or a named destination. See [Pages and coordinates](../../pages/concepts/pages-and-coordinates.md#pages-count-from-0).
+- `destination("chapter-2", 3)` names the fourth page, so a link or an outline entry can go there by name. When the builder finishes, a missing page fails with `page-index-out-of-range` and a missing name with `unknown-destination`.
+- On the other pages, the `link` option of `text` (`.link(…)` on the run in Rust) makes the blue run itself the link, with no box to work out.
+- `contents` describes a link in words, for viewers and screen readers. Accessible PDFs need one on every link.
+- `outline` builds the bookmarks. "Chapters" has no target, so it's a heading, shown open and in bold with both chapters inside it.
+- `pageLabels` numbers the pages i and ii, then 1 and 2 from the third page. `pageMode: "outlines"` asks the viewer to open the file with the outline showing.
+
+## What to change
+
+- **Where a page link lands:** add a `fit` to the target, such as `fit: { type: "width" }` (`Fit::Width` in Rust) to fill the window with the page's width. `destination` takes one too.
+- **The page numbers:** a label also takes a `prefix` and a `first` number, so `{ start: 2, style: "decimal", prefix: "A-" }` numbers the chapters A-1 and A-2.
+- **The panel on open:** `pageMode` also takes `"thumbnails"`, `"attachments"` or `"none"`.
+- **A title and an author:** add `metadata({ title, author })`, and `displayDocTitle: true` in the viewer preferences so viewers show the title instead of the file name. See [Links, outlines and metadata](../../pages/guides/links-outlines-and-metadata.md).
+
+Next: [generate, then edit](../../pages/recipes/generate-then-edit.md), which opens a PDF you made and changes its metadata.