Media Types

Media types are used to group media items that are of the same kind. For example you could have a media type for books, sermons, music, videos, etc. Media types control how the details page of a media item is rendered. This affects how the media item is presented, for example wether a cover image or a video player is shown on top of the page. Types can also be used to filter media items on the search page. The icon of a media type hints the user what kind of media item to expect.

Here is an example of a media type:

src/content/media-types/video.json

{
  "label": "x.type.video",
  "icon": "mdi--video-outline",
  "detailsPage": {
    "layout": "video"
  }
}

Reference

A media type is a JSON file that describes a media type. The media type identifier is its filename without the .json suffix.

label

type: string
example: "x.type.video"
required: true

The name of the media type it is either a fixed string or a translation key to support multiple locales.

icon

type: string
example: "mdi--video-outline"
required: true

The icon that indicates this type. For example this could be a “play”-icon for a video. It has to be in the format mdi--[icon-name]. With [icon-name] being the name of the icon from the Material Design Icon site.

detailsPage

type: object
required: false

The details page configuration. If no object is supplied, the default layout is shown. This object can have the following properties:

layout

type: "default" | "video" | "audio" | "custom"
example: "video"
required: true

The layout of the details page. Depending on the layout you choose, there are additional config options on the detailsPage object. Here is a description of each available layout:

layout: “default”

The default layout shows the media item cover image, title and authors next to a visible button that links to the primary content URL (first item in the media item content array). For URLs that can be opened by the browser, the button text is “Open” for all other URLs it is “Download”. For example if the URL links to a PDF file, the button opens the file inside the browser. An example of a default layout configuration is:

{
  // ...
  "detailsPage": {
    "layout": "default",
    "openActionLabel": "x.action.read"
  }
}

With the default layout you can configure the following options:

openActionLabel

type: string
example: "x.action.read"
required: false

The label of the button that opens the primary content URL. This needs to be a translation key. The default translates to “Open” in English.

coverStyle

type: "default" | "book"
example: "book"
required: false
default: "default"

This sets the style of the cover image. The book style makes the cover image look like a book cover with sharp corners and a book fold. The default style shows the cover image as is.

layout: “video”

The video layout shows a details page with an embedded video player. The video player uses the primary content URL (first item in the media item content array). All other content URLs are shown as additional content below the video player. An example of a video layout configuration is:

{
  // ...
  "detailsPage": {
    "layout": "video"
  }
}

Currently there are no additional configuration options for the video layout. The video layout supports YouTube URLs, Vimeo URLs and links to mp4 files.

layout: “audio”

The audio layout shows a details page with an embedded audio player. The audio player uses the primary content URL (first item in the media item content array). All other content URLs are shown as additional content below the audio player. An example of an audio layout configuration is:

{
  // ...
  "detailsPage": {
    "layout": "audio"
  }
}

Currently there are no additional configuration options for the audio layout. The audio layout supports links to mp3 files.

layout: “custom” Experimental

The custom layout shows a details page with your own layout. Custom details pages are still an experimental feature, we might introduce changes to the API without updating the major version number. Track changes to this feature on the LightNet release notes.

You can define your own layout with an Astro component. An example of a custom layout configuration is:

{
  // ...
  "detailsPage": {
    "layout": "custom",
    "customComponent": "CustomDetailsPage.astro"
  }
}

customComponent

type: string
example: "CustomDetailsPage.astro"
required: true

Custom details pages require you to reference an Astro component to be rendered. The component must be stored in the /src/details-pages folder. The component receives a mediaId property that is the media item’s identifier. You need to wrap your components inside a <DetailsPage> layout. This example fetches the media item with the given mediaId and renders the title of the media item:

src/details-pages/CustomDetailsPage.astro

---
import { getEntry } from "astro:content";
import { DetailsPage } from "lightnet/experimental-details-page";

interface Props {
  mediaId: string;
}
const { mediaId } = Astro.props;

const mediaItem = await getEntry("media", mediaId);
if (!mediaItem) {
  throw new Error(`Cannot find media item for id: ${mediaId}`);
}
---
<DetailsPage mediaId={mediaId}>
  <h1>{mediaItem.title}</h1>
</DetailsPage>

The details page components used by LightNet are experimentally available for building custom details pages. You can import them from lightnet/experimental-details-page.