Dave Jarvis' Repositories

git clone https://repo.autonoma.ca/repo/keenwrite.git
keenwrite / docs / 05-metadata.md
# Metadata

Metadata is information about a document such as title, author keywords,
copyright date, ISBN, and more. Most systems require coupling metadata directly
to the source document. {{app.title}} fetches reads metadata from the variable
definitions file instead. This allows reusing the same metadata across
documents.

Metadata can be inserted into the output document either through the document
properties in the user interface or via the command line.

## Document properties

Metadata can be mapped in the user preferences, shown in [@fig:gui-metadata].
When the document is exported, the document metadata variables are added to the
`<head>` tag as `<meta>` tags.

![Metadata screenshot](images/screenshots/09.png)

:: Document metadata preferences {#fig:gui-metadata}

The **Key** column lists metadata names and the **Value** column lists the
metadata content for each corresponding **Key**. The content may include
references to variable definitions. When the document is typeset, the values
for the variables will be substituted upon export. When exporting to XHTML
format, the header will include the keys and values as `<meta>` tags. For
example:

``` html
<head>
  <title>Document Title</title>
  <meta content="science, nature" name="keywords"/>
  <meta content="Penn Surnom" name="author"/>
  <meta content="4311" name="count"/>
</head>
```

## Command-line

Recall the document metadata from earlier:

``` yaml
document:
  title: Document Title
  author: Author Name
```

These data can be provided via command-line arguments as follows:

``` bash
keenwrite.bin \
  -i "01-introduction.md" \
  -v "metadata.yaml" \
  --metadata="title={{document.title}}" \
  --metadata="author={{document.author}}"
```

The resulting XHTML document will resemble:

``` html
<head>
  <title>Document Title</title>
  <meta content="Author Name" name="author"/>
  <meta content="1234" name="count"/>
</head>
```

We'll take a deeper look at command-line usages in
[@cha:command-line-interface].

## Special fields

Certain metadata keys have special handling and formatting rules when documents
are exported to different formats. When exporting the document, note the
following special metadata:

* **count** -- Document word count, always included.
* **author** -- Included as PDF metadata.
* **keywords** -- Included as PDF metadata.
* **document.title** -- Populates the `<title>` tag, not a `<meta>` tag.

Except for **count**, all of these metadata variables can be customized.

Some themes, such as *Handrit*, have additional metadata that may be included
in the final document automatically. *Handrit*, in particular, has a way to
pass in a pseudonym (or by-line) for publishing manuscripts under a pseudonym.