Page size and layout

For PDFs, the most important decisions are not viewport settings but printed layout settings: paper size, margins, orientation, scaling, and which pages to keep.

Standard paper formats

Use pdf.format when you want a standard paper size such as A4, Letter, or Legal:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://keygen.sh/blog/i-quit' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://keygen.sh/blog/i-quit&pdf.format=A4

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://keygen.sh/blog/i-quit" \
  -d "pdf.format=A4" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://keygen.sh/blog/i-quit', {
  pdf: {
    format: "A4"
  },
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://keygen.sh/blog/i-quit",
    "pdf.format": "A4",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://keygen.sh/blog/i-quit",
  pdf.format: "A4",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://keygen.sh/blog/i-quit",
    "pdf.format" => "A4",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://keygen.sh/blog/i-quit")
    q.Set("pdf.format", "A4")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://keygen.sh/blog/i-quit', {
  pdf: {
    format: "A4"
  },
  meta: false
})

Use standard formats when the PDF needs to match common printing or document-sharing expectations.

Popular options include:

Format	Common use
`A4`	International business documents
`Letter`	US office and home printing
`Legal`	Contracts and legal documents
`Tabloid`	Larger layouts and wide content

See the format reference for the full list.

Custom dimensions

Use pdf.width and pdf.height when you need an exact custom page size rather than a standard paper format:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://microlink.io' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://microlink.io&pdf.width=8.5in&pdf.height=11in

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://microlink.io" \
  -d "pdf.width=8.5in" \
  -d "pdf.height=11in" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://microlink.io', {
  pdf: {
    width: "8.5in",
    height: "11in"
  },
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://microlink.io",
    "pdf.width": "8.5in",
    "pdf.height": "11in",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://microlink.io",
  pdf.width: "8.5in",
  pdf.height: "11in",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://microlink.io",
    "pdf.width" => "8.5in",
    "pdf.height" => "11in",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://microlink.io")
    q.Set("pdf.width", "8.5in")
    q.Set("pdf.height", "11in")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://microlink.io', {
  pdf: {
    width: "8.5in",
    height: "11in"
  },
  meta: false
})

Custom dimensions are useful for receipts, certificates, labels, or any non-standard document size.

The values accept CSS units such as px, in, cm, and mm.

Choose format vs custom size

If you need	Use
A standard printable document size	`pdf.format`
An exact custom paper size	`pdf.width` + `pdf.height`

Use one sizing strategy at a time so the document intent stays clear.

Margins

Use pdf.margin to control the whitespace around the printed content:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://basecamp.com/shapeup/0.3-chapter-01' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://basecamp.com/shapeup/0.3-chapter-01&pdf.margin=1cm

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://basecamp.com/shapeup/0.3-chapter-01" \
  -d "pdf.margin=1cm" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://basecamp.com/shapeup/0.3-chapter-01', {
  pdf: {
    margin: "1cm"
  },
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://basecamp.com/shapeup/0.3-chapter-01",
    "pdf.margin": "1cm",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://basecamp.com/shapeup/0.3-chapter-01",
  pdf.margin: "1cm",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://basecamp.com/shapeup/0.3-chapter-01",
    "pdf.margin" => "1cm",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://basecamp.com/shapeup/0.3-chapter-01")
    q.Set("pdf.margin", "1cm")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://basecamp.com/shapeup/0.3-chapter-01', {
  pdf: {
    margin: "1cm"
  },
  meta: false
})

Margins are one of the easiest ways to make a generated PDF feel more intentional and easier to print.

You can set:

One value for all sides: margin: '1cm'
Different values per side:

{
  pdf: {
    margin: {
      top: '12mm',
      bottom: '16mm',
      left: '10mm',
      right: '10mm'
    }
  }
}

Landscape orientation

Use pdf.landscape when the page is wide and a portrait document would compress it too much:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://www.algolia.com' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://www.algolia.com&pdf.landscape

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://www.algolia.com" \
  -d "pdf.landscape=true" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://www.algolia.com', {
  pdf: {
    landscape: true
  },
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://www.algolia.com",
    "pdf.landscape": "true",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://www.algolia.com",
  pdf.landscape: "true",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://www.algolia.com",
    "pdf.landscape" => "true",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://www.algolia.com")
    q.Set("pdf.landscape", "true")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://www.algolia.com', {
  pdf: {
    landscape: true
  },
  meta: false
})

Landscape is a good fit for wide dashboards, comparison tables, or marketing pages with horizontal sections.

Scale the rendered content

Use pdf.scale to zoom the rendered page content in or out before it is printed:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://varnish-cache.org/docs/trunk/phk/thatslow.html' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://varnish-cache.org/docs/trunk/phk/thatslow.html&pdf.scale=0.8

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://varnish-cache.org/docs/trunk/phk/thatslow.html" \
  -d "pdf.scale=0.8" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://varnish-cache.org/docs/trunk/phk/thatslow.html', {
  pdf: {
    scale: 0.8
  },
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://varnish-cache.org/docs/trunk/phk/thatslow.html",
    "pdf.scale": "0.8",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://varnish-cache.org/docs/trunk/phk/thatslow.html",
  pdf.scale: "0.8",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://varnish-cache.org/docs/trunk/phk/thatslow.html",
    "pdf.scale" => "0.8",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://varnish-cache.org/docs/trunk/phk/thatslow.html")
    q.Set("pdf.scale", "0.8")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://varnish-cache.org/docs/trunk/phk/thatslow.html', {
  pdf: {
    scale: 0.8
  },
  meta: false
})

Lower values fit more content on each page. Higher values make content larger, but also increase the chance of pagination overflow.

The supported range is 0.1 to 2.

Export only specific pages

Use pdf.pageRanges when the final document is longer than what you actually need:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://rauchg.com/2014/7-principles-of-rich-web-applications' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf.pageRanges=1-2

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://rauchg.com/2014/7-principles-of-rich-web-applications" \
  -d "pdf.pageRanges=1-2" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: {
    pageRanges: "1-2"
  },
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf.pageRanges": "1-2",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://rauchg.com/2014/7-principles-of-rich-web-applications",
  pdf.pageRanges: "1-2",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf.pageRanges" => "1-2",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://rauchg.com/2014/7-principles-of-rich-web-applications")
    q.Set("pdf.pageRanges", "1-2")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: {
    pageRanges: "1-2"
  },
  meta: false
})

Page ranges are useful for previews, partial exports, and document workflows that only need one section of a larger PDF.

You can specify a single page such as '1-1' or intervals such as '1-5, 8, 11-13'.

Choose the right layout control

If you need	Use
Standard office paper sizes	`pdf.format`
Exact paper dimensions	`pdf.width` + `pdf.height`
More or less whitespace around the content	`pdf.margin`
A wide document	`pdf.landscape`
More or less content per page	`pdf.scale`
Only part of a long PDF	`pdf.pageRanges`

Next step

Learn how to prepare the page before Microlink prints it — print vs screen CSS, waits, clicks, and injected styles — in page preparation.