metais help manifest
Every field of metais.yaml, inputs and outputs included.
Examples:
A complete metais.yaml: a package with two inputs, one of which may be supplied
as CSV, rendered to Markdown and to an HTML page that escapes its values.
metais: "1.0"
name: org.example.release-notes
version: "1.2.0"
title: Release notes
description: Release notes for one product release, in Markdown and HTML.
guide: |-
Supply the release first, then its changes.
Read inputs/changes.md for what a good change says.
authors:
- name: Example Docs Team
email: docs@example.org
url: https://example.org/docs
license: Apache-2.0
homepage: https://example.org/release-notes
inputs:
- name: release
title: The release
schema: inputs/release.schema.json
- name: changes
title: The changes in the release
description: One change per row, newest first.
schema: inputs/changes.schema.json
meaning: inputs/changes.md
forms: [json, yaml, csv]
csv:
delimiter: ";"
outputs:
- id: notes
template: notes.md.liquid
- id: page
template: page.html.liquid
path: "{{ inputs.release.version }}/index.html"
escape: html
The same package's outputs could instead write one page per change with
for_each, and a zip holding a template, an asset and a mirror:
outputs:
- id: change_pages
template: change.md.liquid
for_each: inputs.changes
when: item.public
path: "changes/{{ item.id }}.md"
- id: bundle
path: "release-{{ inputs.release.version }}.zip"
container:
format: zip
entries:
- template: notes.md.liquid
path: README.md
first: true
- asset: logo.png
path: images/logo.png
stored: true
- mirror: site
path: site
escape: html
The manifest's top level:
metais
Required. The METAIS specification version the package targets, as a
quoted string: unquoted, 1.0 is the number 1. A tool processes the package
under exactly that version's rules.
Example: metais: "1.0"
name
Required. The package's name: segments of lower-case ASCII letters and
digits, single hyphens between them, joined by dots. A segment is at most
63 characters and the name at most 128, and the first segment is not a
Windows device name (con, prn, aux, nul, com0 to com9, lpt0 to lpt9). A
package published beyond its author should begin with a domain its
publisher controls, reversed.
Example: name: org.example.release-notes
version
Required. The package's own version, a Semantic Versioning 2.0.0 version
of at most 128 characters, without a leading v and quoted. Pre-release and
build metadata are allowed.
Example: version: "1.2.0-rc.1"
title
Required. What the package is, as a person names it: one line of 1 to 200
characters.
Example: title: Release notes
description
Required. What the package produces, in a sentence or a short paragraph of
1 to 1000 characters, displayed verbatim.
Example: description: Release notes for one product release.
guide
Required. The guide for suppliers, in CommonMark, of 1 to 16384
characters: what the package is for, how its inputs relate, the order to
gather them in, and where to read further. It may not end with a line
break, so write a block as guide: |- rather than guide: |.
Example: guide: Supply the release first, then its changes.
authors
Optional. The package's authors, 1 to 64 people or organizations, each an
object with the fields under authors[].
Example: authors: [{name: Example Docs Team}]
license
Optional. The terms of the package's own content, an SPDX license
expression of 1 to 512 characters with AND, OR and WITH in upper case.
Identifiers are not checked against the SPDX License List.
Example: license: Apache-2.0 OR MIT
homepage
Optional. The package's home page, an absolute https or http URI of at
most 2048 characters, with a host, no user information and no fragment. No
command ever fetches it.
Example: homepage: https://example.org/release-notes
inputs
Required. The inputs the package takes, in the order a supplier meets
them, each an object with the fields under inputs[]. It may be empty.
Example: inputs: []
input_constraints
Optional. The package path, under inputs/ and ending .json, .yaml or .yml,
of a schema evaluated against the object holding every input, for rules
that relate one input to another.
Example: input_constraints: inputs/constraints.schema.json
outputs
Required. The output declarations, at least one, in the order they are
planned, each with the fields under outputs[].
Example: outputs: [{id: notes, template: notes.md.liquid}]
Each author, authors[]:
authors[].name
Required. The person or organization: one line of 1 to 200 characters.
Example: name: Ada Lovelace
authors[].email
Optional. An email address of 3 to 254 characters, with exactly one @ and
no space. It is not validated further, and no command sends mail.
Example: email: ada@example.org
authors[].url
Optional. The author's web page, an absolute https or http URI with a host
and no user information, as homepage.
Example: url: https://example.org/ada
Each input, inputs[] (spec chapter 5):
inputs[].name
Required. The input's name, unique among the inputs: a lower-case letter,
then up to 63 lower-case letters, digits and underscores, and none of
Liquid's reserved words blank, empty, false, first, last, nil, null, size
and true. A template reads the input as inputs.<name>, a data directory's
file for it is named after it, and it is the first token of a --set
pointer.
Example: name: changes
inputs[].title
Required. What the input is, in brief: one line of 1 to 200 characters.
Example: title: The changes in the release
inputs[].description
Optional. What the input means, as plain text, line breaks allowed.
Example: description: One change per row, newest first.
inputs[].schema
Required. The package path, under inputs/, of the input's JSON Schema
file, ending .json, .yaml or .yml.
Example: schema: inputs/changes.schema.json
inputs[].meaning
Optional. The package path, under inputs/, of a CommonMark document ending
.md that says what the data is for and what good data looks like. No tool
interprets it.
Example: meaning: inputs/changes.md
inputs[].forms
Optional. The file forms the input may be supplied in, each at most once,
of json, yaml, csv, text and markdown. Default: json and yaml.
Example: forms: [json, yaml, csv]
inputs[].csv
Optional, and allowed only when forms holds csv. How a CSV file of the
input is read: an object whose one member is delimiter.
Example: csv: {delimiter: ";"}
inputs[].csv.delimiter
Required in csv. The character that separates fields: a comma, a
semicolon, a vertical bar or a tab.
Example: delimiter: "\t"
inputs[].collection
Optional. true for a collection: an array of items, supplied as a
directory of item files. Default false.
Example: collection: true
inputs[].required
Optional. false for an input a supplier may leave out. Default true.
Example: required: false
Each output declaration, outputs[] (spec chapters 9 and 10):
A declaration takes exactly one form, named by the one source key it carries:
template, asset, mirror or container. Each field below names the forms that take
it, and a form refuses any other field.
outputs[].id
Every form. Required at the top level and optional on a container entry.
The declaration's identifier: a lower-case letter, then up to 63
lower-case letters, digits and underscores, unique among the top-level
declarations, and an entry's among its container's entries.
Example: id: change_pages
outputs[].template
The template form's source key: the template's path relative to
templates/, rendered to one file per evaluation.
Example: template: notes.md.liquid
outputs[].asset
The asset form's source key: a file or a directory relative to assets/, .
being the whole of assets/. Every file is copied byte for byte, never
rendered.
Example: asset: images
outputs[].mirror
The mirror form's source key: a directory relative to templates/, . being
the whole of templates/, whose every template is rendered to its relative
path with a final .liquid removed. A template whose name, or a directory's
between it and the mirror's, begins with _ is a partial and is not
mirrored, and nor is a template a template field names.
Example: mirror: site
outputs[].container
The container form's source key: the zip's shape, an object with the
fields under outputs[].container.
Example: container: {entries: [{template: notes.md.liquid}]}
outputs[].path
Every form. Required on a container and with for_each, and optional
otherwise. The destination relative to the root of the tree, a Liquid
template that is never escaped; for an asset directory or a mirror it
names a directory, . being the root. Without it, a template output is
written to its template's path with a final .liquid removed, an asset to
its path under assets/, and a mirror beneath its directory. Quote a path
that begins with {.
Example: path: "changes/{{ item.id }}.md"
outputs[].when
Every form. Optional. A Liquid condition, what may follow if in {% if %}:
the declaration writes files only where it holds, and without when it
always holds. With for_each it is judged once per element.
Example: when: inputs.release.public
outputs[].for_each
Template and container forms. Optional, and needs path. A Liquid value
expression, what may appear inside {{ }}: its array gives one evaluation
per element, in order, with the element bound to item and its position to
fan_out, and nil gives none. A declaration beneath a container with
for_each has none of its own.
Example: for_each: inputs.changes
outputs[].escape
Template and mirror forms. Optional. How the values a template writes are
escaped: none, the default, or html, which writes & < > " and ' as
entities.
Example: escape: html
outputs[].newline
Template and mirror forms. Optional. The rendered file's line endings:
as-written, the default, or crlf, which makes every LF not preceded by CR
a CR LF before the file is validated.
Example: newline: crlf
outputs[].validate
Template form. Optional. The package path, outside .compiled/, of a JSON
Schema the file's final bytes are validated against, parsed by its kind,
which must be json or yaml. A file that fails refuses the render, and
nothing is written.
Example: validate: schemas/feed.schema.json
outputs[].kind
Template form. Optional. The output kind of every file it renders,
overriding the one its path's extension gives: html, xml, markdown, json,
yaml, csv, css, hash, slash, sql or text. The kind chooses the comment
syntax provenance writes; it is not escaping.
Example: kind: yaml
outputs[].executable
Template and asset forms, never a container entry. Optional. true writes
the file with mode 0755 instead of 0644, less the umask. Default false.
Example: executable: true
A zip container's shape, outputs[].container (spec chapter 10):
outputs[].container.format
Optional. The container's format: zip is the only one.
Example: format: zip
outputs[].container.profile
Optional. The packaging rules of a format the container follows: ooxml,
which needs an entry [Content_Types].xml; odf, which writes the mimetype
entry first and needs META-INF/manifest.xml; or epub, which writes the
mimetype entry first and needs META-INF/container.xml. Without one, the
container is written exactly as declared.
Example: profile: epub
outputs[].container.mimetype
Required with the odf profile, and allowed only with it. The media type,
type/subtype, written as the mimetype entry.
Example: mimetype: application/vnd.oasis.opendocument.text
outputs[].container.entries
Required. The container's entries, at least one, each a declaration with
the fields under outputs[].container.entries[].
Example: entries: [{template: notes.md.liquid, path: README.md}]
Each container entry, outputs[].container.entries[]:
An entry is a declaration of one of the four forms and takes the fields
outputs[] gives its form, except that id is optional, executable is refused,
since a zip records no file mode, and path names the entry inside the container.
Entries are written into the container only; a part that must also be a file of
its own is declared again at the top level. Two fields are an entry's alone:
outputs[].container.entries[].first
Optional. true places the entry's files before every other entry the
profile does not place, in declaration order. Default false.
Example: first: true
outputs[].container.entries[].stored
Optional. true stores the entry's files rather than compressing them.
Default false.
Example: stored: true
metais check [<dir>] checks a package's manifest against these rules, with every
other step, and reports every finding at once; a package that cannot be read at
all gets only the findings of that refusal. metais init writes a package to
start from. metais help templates covers the template language a template, path,
when and for_each are written in. The specification's chapter 3 (the manifest),
chapter 5 (inputs), chapter 9 (outputs) and chapter 10 (containers and
transforms) state each rule, and schemas/1.0/manifest.schema.json holds the
manifest's schema.