Media directive

Media directives

media directives and media.yml

The media and media-inline directives are used with the media.yml file to to designate which type of media will be rendered in each build-type (EPUB, Reader, Mobi, etc). With other b-ber directives, attributes are added inline to the directive in the Markdown files. The media and media-inline directives are distinct as they function as placeholders for other directives added in the media.yml file. A media directive only requires a unique ID attribute when adding it to a Markdown file.

<!-- chapter-one.md -->

# Chapter One

::: media:my-unique-id

The directive's ID is then added to the _project/media.yml file, along with a property for each of the build-types (epub, mobi, reader, web, pdf, xml), and a type property for each of those builds. The type property lets b-ber know which type of directive should be inserted in the place of the media directive.

# _project/media.yml

my-unique-id:
  epub:
    type: figure

When running bber build epub, the media directive in the Markdown above will be replaced by a figure directive.

As with other media directives--Figures, Video, Vimeo, Audio--the media directive will create a new XHTML pages for each of the elements encountered in the Markdown and add these new pages to the <type>.yml files automatically during build. The media-inline will render the media directly in the HTML without creating a link to the figures section of the publication. Please note that the -inline suffix should only be used in the directive found in the markdown, not the media.yml file.

Basic usage (Markdown)

::: media:my-unique-id-1

::: media-inline:my-unique-id-2

Basic usage (media.yml)

1. Each media and media-inline directive's ID must be listed at the top level;
2. IDs must be unique;
3. An entry for each build-type must be specified under each ID;
4. Not all media in a project must be listed in the media.yml. A user can opt to only include certain media using this file, and use conventional directives in the Markdown for other media sources.

media.yml

The example below specifies which type of directive should be rendered for each build-type (EPUB, Reader, Mobi, etc). Please note the type attribute, which is only used in the media.yml file. All other attributes listed under each build-type are match those for the directive that is declared in the type attribute. For example, if adding the type: vimeo, all the Vimeo attributes can be used.

In the following example, the Reader would have an embedded Vimeo player, the EPUB a video file, and the Mobi, XML, and PDF, an image.

Markdown

::: media-inline:my-unique-id-1

media.yml

my-unique-id-1: 
  reader:
    type: vimeo
    source: 123456
    caption: The caption for the Reader build. 
  epub:
    type: video
    source: my-video-file
    caption: The caption for the EPUB build. This video can also be watched on [Vimeo](https://vimeo.com).
  mobi:
    type: figure
    source: my-image-file.jpg
    caption: The caption for the Mobi build.
  xml:
    type: figure
    source: my-image-file.jpg
    caption: The caption for the XML build.
  pdf:
    type: figure
    source: my-image-file.jpg
    caption: The caption for the PDF build.

In the following example, the Reader would have an embedded Vimeo player with Vimeo attributes, the EPUB an audio file, and the Mobi, XML, and PDF, an image.

Markdown

::: media-inline:my-unique-id-2

media.yml

my-unique-id-2: 
  reader:
    type: vimeo
    source: 123456
    caption: The caption for the Reader build.
    autoplay: yes
    controls: no
    loop: yes
    muted: yes
  epub:
    type: audio
    source: my-audio-file
    caption: The caption for the EPUB build.
  mobi:
    type: figure
    source: my-image-file.jpg
    caption: The caption for the Mobi build.
  xml:
    type: figure
    source: my-image-file.jpg
    caption: The caption for the XML build.
  pdf:
    type: figure
    source: my-image-file.jpg
    caption: The caption for the PDF build.

Advanced YAML Configuration

It can become verbose when listing all the build-types under each ID in the media.yml file. YAML's anchors and aliases can be used to include default settings. These are then overridden for specific IDs in the case that a user wishes to always render a consistent fallback for certain build-types.

In the following example, an unsupported anchor is added with a fallback image for the EPUB, Mobi, PDF, and XML builds.

# Create a base "unsupported" anchor
unsupported: &unsupported
  type: figure
  source: unsupported-figure.jpg
  caption: This project includes a video that can be watched online on [Vimeo](https://vimeo.com).
  
# Create a "defaults" anchor with aliases to "unsupported"
defaults: &defaults
  epub: *unsupported
  mobi: *unsupported
  xml: *unsupported
  pdf: *unsupported

# Apply the defaults and extend them with values for the reader and epub builds.
my-unique-id-1: 
  <<: *defaults
  reader: 
    type: vimeo
    source: 123456