SPEC.md

Perun SPEC

This document defines metadata used by built-in tasks.

• Set by fields are set by the mentioned tasks.
• Required by fields are mandatory. Global metadata can alternatively be set for the tasks using task options.
• Used by fields are optional.

Global metadata

• :site-title
  • Required by: atom-feed
  • Required by: rss
• :author
  • Required by: atom-feed if posts don't have author metadata
• :author-email
• :base-url
  • Must be in canonical form, that is end in /
  • Required by: atom-feed
  • Required by: rss
• :doc-root
  • Defaults to "public"
  • Permalinks will be determined relative to this directory
• :language
• :description
  • Used by: atom-feed
  • Used by: rss

Post metadata

All posts have a path which is used as a key to identify the post.

• :title
  • Required by: atom-feed
  • Used by: rss either this or description is required
• :content The post content
  • Populated from file content
  • Only set in the :entry value of the map passed to renderer functions
• :original-path The path for the input file from which this entry is descended
  • Set by input parsing tasks (like markdown) on output files
  • Passed through by rendering tasks
• :description
  • Used by: rss either this or title is required
• :slug
  • Set implicitly based on a file's path
  • Required by: permalink default fn
• :permalink relative url for the post
  • Set implicitly based on a file's path
  • Required by: atom-feed
  • Required by: canonical-url
• :uuid The post's permanent ID.
  • Required by atom-feed
• :canonical-url full url for the post
  • Set implicitly based on a file's path, if a :base-url is present in global metadata
  • Used by: atom-feed
  • Used by: rss
• :author
  • Required by: atom-feed, unless global value is set
• :author-email
  • Used by: atom-feed
  • Used by: rss
• :draft
  • Used by: draft
• :date-build date when the site was generated
  • Set by: build-date
  • Used by: sitemap
• :date-created
  • Required by: atom-feed
• :date-published
  • Used by: collection to sort the posts
  • Used by: atom-feed
  • Used by: rss
• :date-modified
  • Used by: atom-feed
  • Used by: sitemap
• :original
  • Set by: markdown
• :ttr
  • Set by: ttr
• :include-atom
  • Set by: markdown, true by default
  • Used by: atom-feed
• :include-rss
  • Set by: markdown, true by default
  • Used by: rss
• :tags
  • Used by: tags, atom-feed
• :tag
  • Set by: tags, on the pages generated for each tag listed
• :page
  • The number of this page
  • Set by: paginate
  • Set by: atom-feed
• :first-page
  • The filename of the first page in this group of pages
  • Set by: paginate
  • Set by: atom-feed
• :last-page
  • The filename of the last page in this group of pages
  • Set by: paginate
  • Set by: atom-feed
• :prev-page
  • The filename of the previous page in this group of pages, if it exists
  • Set by: paginate
  • Set by: atom-feed
• :next-page
  • The filename of the next page in this group of pages, if it exists
  • Set by: paginate
  • Set by: atom-feed
• :io.perun/trace
  • Conjed onto by every task that modifies metadata
  • Serves as a record of tasks to touch a file