---
name: "Pandoc::Metadata"
section: "3pm"
platform: "linux"
package: "libpandoc-elements-perl"
version: "0.38-7"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pandoc::Metadata"
---

# Pandoc::Metadata(3pm)

pandoc document metadata

## NAME

Pandoc::Metadata - pandoc document metadata

## DESCRIPTION

Document metadata such as author, title, and date can be embedded in different documents formats. Metadata can be provided in Pandoc markdown format with metadata blocks \<http://pandoc.org/MANUAL.html#metadata-blocks\> at the top of a markdown file or in YAML format like this:

```
  ---
  title: a title
  author:
    - first author
    - second author
  published: true
  ...
```

Pandoc supports document metadata build of strings ("MetaString"), boolean values ("MetaBool"), lists ("MetaList"), key-value maps ("MetaMap"), lists of inline elements ("MetaInlines") and lists of block elements ("MetaBlocks"). Simple strings and boolean values can also be specified via pandoc command line option `"-M"` or `"--metadata"`:

```
  pandoc -M key=string
  pandoc -M key=false
  pandoc -M key=true
  pandoc -M key
```

Perl module Pandoc::Elements exports functions to construct metadata elements in the internal document model and the general helper function `"metadata"`.

## COMMON METHODS

All Metadata Elements support common element methods (`"name"`, `"to_json"`, `"string"`, ...) and return true for method `"is_meta"`.

### value( \[ $key \| $pointer \] \[ %options \] )

Called without an argument this method returns an unblessed deep copy of the metadata element. Plain keys at the root level (unless they start with `"/"`) and JSON Pointer expressions (RFC 6901 \<http://tools.ietf.org/html/rfc6901\>) can be used to select subfields.  Note that JSON Pointer escapes slash as `"~1"` and character `"~"` as `"~0"`. URI Fragment syntax is not supported.

```
  $doc->value;                   # full metadata
  $doc->value("");               # full metadata, explicitly
  $doc->value('/author');        # author field
  $doc->value('author');         # author field, plain key
  $doc->value('/author/name');   # name subfield of author field
  $doc->value('/author/0');      # first author field
  $doc->value('/author/0/name'); # name subfield of first author field
  $doc->value('/~1~0');          # metadata field '/~'
  $doc->value('/');              # field with empty string as key
```

Returns `"undef"` if the selected field does not exist.

As a debugging aid you can set option `"strict"` to a true value. In this case the method will `"croak"` if an invalid pointer, invalid array index, non-existing key or non-existing array index is encountered.

Instances of MetaInlines and MetaBlocks are stringified by unless option `"element"` is set to `"keep"`.

Setting option `"boolean"` to `"JSON::PP"` will return `"JSON::PP:true"` or `"JSON::PP::false"` for MetaBool instances.

## METADATA ELEMENTS

### MetaString

A plain text string metadata value.

```
    MetaString $string
    metadata "$string"
```

### MetaBool

A Boolean metadata value. The special values `"false"` and `"FALSE"` are recognized as false in addition to normal false values (`0`, `"undef"`, `""`, ...).

```
    MetaBool $value
    metadata JSON::true()
    metadata JSON::false()
```

### MetaList

A list of other metadata elements.

```
    MetaList [ @values ]
    metadata [ @values ]
```

### MetaMap

A map of keys to other metadata elements.

```
    MetaMap { %map }
    metadata { %map }
```

### MetaInlines

Container for a list of inlines in metadata.

```
    MetaInlines [ @inlines ]
```

### MetaBlocks

Container for a list of blocks in metadata.

```
    MetaBlocks [ @blocks ]
```

The `"string"` method concatenates all stringified content blocks separated by empty lines.