Metadata

This page explains how to add metadata to PDF documents with rix/pdf.

The examples use the public Rix facade:

cpp

#include <rix.hpp>

and access PDF through:

cpp

rix.pdf

PDF metadata helps describe a generated document. It can include the title, author, subject, creator, and keywords.

Basic metadata example

Create a file:

bash

mkdir -p ~/rix-pdf-metadata
cd ~/rix-pdf-metadata
touch metadata.cpp

Add:

cpp

#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  doc.set_title("Rix PDF Metadata Example")
      .set_author("Rix")
      .set_subject("PDF metadata")
      .set_keywords("rix,pdf,vix,cpp");

  auto &page = doc.add_page();

  auto y = page.heading(
      page.x_left(),
      page.y_top(),
      "Metadata",
      1);

  y -= 10.0F;

  page.paragraph(
      page.x_left(),
      y,
      page.content_width(),
      "This PDF includes title, author, subject, creator, and keyword metadata.");

  auto saved = rix.pdf.save(doc, "metadata.pdf");

  if (saved.failed())
  {
    rix.debug.eprint(
        "pdf error:",
        rix.pdf.error.to_string(saved.error()),
        saved.error().message());

    return 1;
  }

  rix.debug.print("created:", "metadata.pdf");
  return 0;
}

Run it:

bash

vix run metadata.cpp

If Rix is not available yet for single-file usage:

bash

vix install -g rix/rix
vix run metadata.cpp

This creates:

txt

metadata.pdf

What metadata is

Metadata is information about the PDF document.

It is not the visible page content.

Visible content is added with pages:

cpp

auto &page = doc.add_page();

page.text(
    page.x_left(),
    page.y_top(),
    "Visible text");

Metadata is added to the document itself:

cpp

doc.set_title("Document title");
doc.set_author("Rix");

PDF viewers may display this information in document properties.

Available metadata fields

rix/pdf supports these metadata fields:

txt

title
author
subject
creator
keywords

Use them to describe generated reports, invoices, exports, receipts, documents, and application output.

Set the title

Use:

cpp

doc.set_title("Rix PDF Metadata Example");

The title describes the document.

Example:

cpp

auto doc = rix.pdf.document();

doc.set_title("Monthly Report");

Set the author

Use:

cpp

doc.set_author("Rix");

The author can be a person, application, organization, or service.

Example:

cpp

doc.set_author("Vix.cpp Application");

Set the subject

Use:

cpp

doc.set_subject("PDF metadata");

The subject explains what the document is about.

Example:

cpp

doc.set_subject("Generated report");

Set the creator

Use:

cpp

doc.set_creator("my-app");

The creator identifies the software or tool that created the PDF.

By default, the creator is:

txt

rix/pdf

If the creator is set to an empty value, it is normalized back to the default creator.

Set keywords

Use:

cpp

doc.set_keywords("rix,pdf,vix,cpp");

Keywords should be short and useful.

Example:

cpp

doc.set_keywords("report,invoice,export");

Chain metadata setters

The document metadata setters are chainable.

cpp

doc.set_title("Rix PDF Metadata Example")
    .set_author("Rix")
    .set_subject("PDF metadata")
    .set_keywords("rix,pdf,vix,cpp");

This is the recommended style when setting several metadata fields together.

Metadata with visible content

Metadata does not create visible content.

If you want the title to appear on the page, also write it as a heading or text:

cpp

auto doc = rix.pdf.document();

doc.set_title("Monthly Report")
    .set_author("Rix");

auto &page = doc.add_page();

page.heading(
    page.x_left(),
    page.y_top(),
    "Monthly Report",
    1);

The metadata title is for the PDF info dictionary.

The heading is visible on the page.

Read metadata

Access metadata with:

cpp

const auto &metadata = doc.metadata();

Example:

cpp

const auto &metadata = doc.metadata();

rix.debug.print("title:", metadata.title());
rix.debug.print("author:", metadata.author());
rix.debug.print("subject:", metadata.subject());
rix.debug.print("creator:", metadata.creator());
rix.debug.print("keywords:", metadata.keywords());

Update metadata directly

You can update metadata through the metadata object:

cpp

doc.metadata().set_title("Updated title");
doc.metadata().set_author("Updated author");

The document helpers are usually cleaner:

cpp

doc.set_title("Updated title")
    .set_author("Updated author");

Clear metadata

Use the metadata object to clear user-provided metadata:

cpp

doc.metadata().clear();

This clears:

txt

title
author
subject
keywords

The creator is reset to:

txt

rix/pdf

Check whether metadata is empty

Use:

cpp

doc.metadata().empty()

Example:

cpp

if (doc.metadata().empty())
{
  rix.debug.print("metadata is empty");
}

The default creator does not make metadata non-empty.

Metadata in a report

cpp

#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  doc.set_title("Project Report")
      .set_author("Rix")
      .set_subject("Generated project report")
      .set_keywords("rix,report,pdf");

  auto &page = doc.add_page();

  auto y = page.heading(
      page.x_left(),
      page.y_top(),
      "Project Report",
      1);

  y -= 10.0F;

  page.paragraph(
      page.x_left(),
      y,
      page.content_width(),
      "This document uses metadata for document properties "
      "and visible headings for page content.");

  auto saved = rix.pdf.save(doc, "project-report.pdf");

  if (saved.failed())
  {
    rix.debug.eprint(
        "pdf error:",
        rix.pdf.error.to_string(saved.error()),
        saved.error().message());

    return 1;
  }

  rix.debug.print("created:", "project-report.pdf");
  return 0;
}

Run:

bash

vix run metadata.cpp

Metadata with `make_text`

The high-level make_text helper accepts an optional title:

cpp

auto saved = rix.pdf.make_text(
    "hello.pdf",
    "Hello from rix.pdf",
    "Rix PDF");

The title is used as document metadata and as the visible heading.

Use make_text when you only need a simple text PDF.

Use document() when you need more control over metadata and content.

Metadata with tables

cpp

#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  doc.set_title("Table Report")
      .set_author("Rix")
      .set_subject("Generated table")
      .set_keywords("table,pdf,rix");

  auto &page = doc.add_page();

  auto y = page.heading(
      page.x_left(),
      page.y_top(),
      "Table Report",
      1);

  y -= 20.0F;

  rixlib::pdf::Table table;

  table.set_column_widths({
      160.0F,
      160.0F,
      160.0F});

  table.add_header({
      "Name",
      "Language",
      "Project"});

  table.add_row({
      "Ada",
      "C++",
      "Rix"});

  table.add_row({
      "Gaspard",
      "C++",
      "Vix.cpp"});

  page.table(
      page.x_left(),
      y,
      table);

  auto saved = rix.pdf.save(doc, "table-report.pdf");

  if (saved.failed())
  {
    rix.debug.eprint(
        "pdf error:",
        rix.pdf.error.to_string(saved.error()),
        saved.error().message());

    return 1;
  }

  rix.debug.print("created:", "table-report.pdf");
  return 0;
}

Metadata with generated exports

For generated exports, metadata can identify the source:

cpp

doc.set_title("CSV Export")
    .set_author("my-app")
    .set_subject("Generated CSV report as PDF")
    .set_creator("my-app")
    .set_keywords("csv,export,pdf");

This is useful when PDF files are produced automatically by a backend service.

Metadata and file names

The metadata title and output file name are separate.

cpp

doc.set_title("Monthly Report");

auto saved = rix.pdf.save(doc, "report-2026-06.pdf");

The title describes the document.

The file name describes the saved file path.

They can be the same, but they do not have to be.

Write metadata to bytes

Metadata is included when writing PDF bytes:

cpp

auto bytes = rix.pdf.write(doc);

if (bytes.failed())
{
  rix.debug.eprint(
      "pdf error:",
      rix.pdf.error.to_string(bytes.error()),
      bytes.error().message());

  return 1;
}

Use write when another part of your application will handle the bytes.

Use save when you want to write directly to a PDF file.

Save the PDF

Use:

cpp

auto saved = rix.pdf.save(doc, "metadata.pdf");

Always check errors:

cpp

if (saved.failed())
{
  rix.debug.eprint(
      "pdf error:",
      rix.pdf.error.to_string(saved.error()),
      saved.error().message());

  return 1;
}

Use in a Vix project

Create a Vix application:

bash

vix new pdf-metadata --app
cd pdf-metadata

Add Rix:

bash

vix add rix/rix
vix install

In vix.app, make sure Rix is listed under deps:

txt

deps = [
  "rix/rix",
]

A small vix.app can look like this:

txt

name = "pdf-metadata"
type = "executable"
standard = "c++20"
output_dir = "bin"

sources = [
  "src/main.cpp",
]

include_dirs = [
  "include",
  "src",
]

deps = [
  "rix/rix",
]

packages = [
  "vix",
]

links = [
  "vix::vix",
]

Then use metadata in src/main.cpp:

cpp

#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  doc.set_title("Metadata example")
      .set_author("Rix")
      .set_subject("PDF metadata")
      .set_keywords("rix,pdf");

  auto &page = doc.add_page();

  page.heading(
      page.x_left(),
      page.y_top(),
      "Metadata example",
      1);

  auto saved = rix.pdf.save(doc, "metadata.pdf");

  if (saved.failed())
  {
    rix.debug.eprint(
        "pdf error:",
        rix.pdf.error.to_string(saved.error()),
        saved.error().message());

    return 1;
  }

  rix.debug.print("created:", "metadata.pdf");
  return 0;
}

Build and run:

bash

vix build
vix run

Single-file usage

For small scripts, examples, and experiments:

bash

vix run metadata.cpp

If Rix is installed globally for single-file usage:

bash

vix install -g rix/rix
vix run metadata.cpp

For project usage, prefer:

bash

vix add rix/rix
vix install

and keep the dependency in vix.app:

txt

deps = [
  "rix/rix",
]

Use only PDF with the facade

If you want the rix.* facade style but only want PDF mounted, define the feature macro before including rix.hpp:

cpp

#define RIX_ENABLE_PDF
#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  doc.set_title("Metadata example")
      .set_author("Rix");

  auto &page = doc.add_page();

  page.text(
      page.x_left(),
      page.y_top(),
      "Hello from rix.pdf");

  return rix.pdf.save(doc, "metadata.pdf").ok() ? 0 : 1;
}

When at least one RIX_ENABLE_* macro is defined, only selected modules are mounted.

Use the independent package

For independent usage, install:

bash

vix add rix/pdf
vix install

In vix.app:

txt

deps = [
  "rix/pdf",
]

Then include:

cpp

#include <rix/pdf.hpp>

Use this style when a project only needs PDF and does not need the full unified Rix facade.

For most application documentation, prefer:

cpp

#include <rix.hpp>

Common mistakes

Expecting metadata to appear on the page

Metadata is not visible page content.

This sets document metadata:

cpp

doc.set_title("Monthly Report");

To show the title on the page, also add a heading:

cpp

page.heading(
    page.x_left(),
    page.y_top(),
    "Monthly Report",
    1);

Forgetting to add a page

Metadata alone can be written, but most documents should have visible content:

cpp

auto &page = doc.add_page();

Not checking save errors

Wrong:

cpp

rix.pdf.save(doc, "metadata.pdf");

Better:

cpp

auto saved = rix.pdf.save(doc, "metadata.pdf");

if (saved.failed())
{
  rix.debug.eprint(
      "pdf error:",
      rix.pdf.error.to_string(saved.error()),
      saved.error().message());

  return 1;
}

Confusing title and file name

This is the PDF metadata title:

cpp

doc.set_title("Monthly Report");

This is the output path:

cpp

rix.pdf.save(doc, "report.pdf");

They are related, but not the same thing.

Setting empty creator

If the creator is empty, it is reset to the default creator:

txt

rix/pdf

Use a real value if your application should identify itself:

cpp

doc.set_creator("my-app");

Confusing `deps` and `packages`

For a Vix project, do not put Rix packages in packages.

Wrong:

txt

packages = [
  "rix/rix",
]

Correct:

txt

deps = [
  "rix/rix",
]

deps is for Vix Registry packages.

packages is for CMake package discovery.

What you should remember

Create a document:

cpp

auto doc = rix.pdf.document();

Set metadata:

cpp

doc.set_title("Title")
    .set_author("Rix")
    .set_subject("PDF metadata")
    .set_keywords("rix,pdf,vix,cpp");

Set the creator:

cpp

doc.set_creator("my-app");

Add visible content separately:

cpp

auto &page = doc.add_page();

page.heading(
    page.x_left(),
    page.y_top(),
    "Title",
    1);

Save:

cpp

auto saved = rix.pdf.save(doc, "metadata.pdf");

Check errors:

cpp

if (saved.failed())
{
  rix.debug.eprint(
      "pdf error:",
      rix.pdf.error.to_string(saved.error()),
      saved.error().message());
}

For a Vix project, install Rix:

bash

vix add rix/rix
vix install

and use:

txt

deps = [
  "rix/rix",
]

Next step

Learn how to handle PDF errors.

Next: Errors

Metadata ​

Basic metadata example ​

What metadata is ​

Available metadata fields ​

Set the title ​

Set the author ​

Set the subject ​

Set the creator ​

Set keywords ​

Chain metadata setters ​

Metadata with visible content ​

Read metadata ​

Update metadata directly ​

Clear metadata ​

Check whether metadata is empty ​

Metadata in a report ​

Metadata with make_text ​

Metadata with tables ​

Metadata with generated exports ​

Metadata and file names ​

Write metadata to bytes ​

Save the PDF ​

Use in a Vix project ​

Single-file usage ​

Use only PDF with the facade ​

Use the independent package ​

Common mistakes ​

Expecting metadata to appear on the page ​

Forgetting to add a page ​

Not checking save errors ​

Confusing title and file name ​

Setting empty creator ​

Confusing deps and packages ​

What you should remember ​

Next step ​

Metadata

Basic metadata example

What metadata is

Available metadata fields

Set the title

Set the author

Set the subject

Set the creator

Set keywords

Chain metadata setters

Metadata with visible content

Read metadata

Update metadata directly

Clear metadata

Check whether metadata is empty

Metadata in a report

Metadata with `make_text`

Metadata with tables

Metadata with generated exports

Metadata and file names

Write metadata to bytes

Save the PDF

Use in a Vix project

Single-file usage

Use only PDF with the facade

Use the independent package

Common mistakes

Expecting metadata to appear on the page

Forgetting to add a page

Not checking save errors

Confusing title and file name

Setting empty creator

Confusing `deps` and `packages`

What you should remember

Next step