Catalog settings

A catalog presents any number of releases from any number of artists on your site. In general a catalog is used as an overarching collection and homepage of a faircamp site, presenting the entirety of what's available, especially for labels and audio producers with many projects.

Faircamp does not (yet) allow you to pick the contents of a catalog – this is on the roadmap for the near future. For the moment, a catalog always presents all (public) releases of your site.

A catalog lives in its own directory and can not be located at the root of the site directory. Create a catalog.eno plaintext file inside a directory and it becomes a catalog.

An example catalog.eno file:

title: My music

m3u: enabled
more_label: About

image: studio_3.png
image_description: Me in my studio

links:
- https://example.com/my-music-elsewhere/
- Blog https://example.com/my-blog/

-- synopsis
Just some of my music
-- synopsis

-- more
Some of my music released between 1999-2005.

For further information check out my [website](https://...)
-- more

theme.mode: light
theme.light:
accent_brightening = 85
accent_chroma = 50
accent_hue = 23
base_chroma = 34
base_hue = 180

The remainder of this page alphabetically lists all available settings for catalogs.

copy_link

Default-able Use the prefixed form catalog.copy_link outside of catalog manifests

To disable the "Copy link" button (by default it's enabled) you can use the copy_link option, with either enabled or disabled as value. This is also inherited by all releases, but can be changed on a granular basis for single releases or groups of releases in their manifests.

copy_link: disabled

external_page

Local-only This catalog setting can not inherit default values from other manifests

external_page: https://example.com

With this option set, the catalog is linked to an external page wherever it appears on the faircamp site (which technically is only in the browse/search navigation right now). The catalog page itself is not generated in that case, or rather: It becomes a redirect to the external page.

feeds

Default-able Use the prefixed form catalog.feeds outside of catalog manifests

Heads up: You need to set site.base_url so that faircamp can generate feeds.

By default faircamp provides two feeds that your visitors can subscribe to: An Atom feed and a plain RSS feed (RSS 2.0 without media or podcast extensions), both of which are simple "blog-like" (purely text and image based) feeds that provide updates linking to your new releases so that people can listen to new material on your site only (this is the textual feeds setting).

If you are publishing (a) podcast(s) on your faircamp site, set the feeds option to either podcast (to provide only a single, Podcast RSS based feed), to media (to provide only Media RSS and Podcast RSS feeds) or to all(to provide all textual and media feed types), for instance:

feeds: podcast

Note that the Podcast RSS feed for a catalog will include all tracks of all multitrack and track releases mixed together in a single feed. You can also enable feeds at the multitrack release level – that is the recommended setup for hosting podcasts (where each multitrack release is a podcast).

If you want to disable all feeds you can use this option:

feeds: disabled

If you need a very specific feed configuration, you can also use the discrete atom, media_rss, plain_rss and podcast_rss options in a list. For instance to provide only an atom feed:

feeds:
- atom

Or, to provide only plain RSS and Podcast RSS feeds:

feeds:
- plain_rss
- podcast_rss

homepage

Local-only This catalog setting can not inherit default values from other manifests

homepage

Makes this catalog page the homepage of your site. There is only one homepage, so this setting can only be used in one place at a time.

image

Local-only This catalog setting can not inherit default values from other manifests

The image is displayed on the catalog page, e.g. a logo for your label or a portrait, band photo or such.

image: studio_3.png

Specify the path of the image, relative to the directory the manifest is in (so if the image "example.jpg" is in the same folder, just write "example.jpg", if it's in the parent folder write "../example.jpg", and so on).

Safe area

The catalog's image is shown in different ways depending on the screen size and browser viewport of a visitor's device. If you include e.g. a logo in your image, parts of it might be invisible due to the automated cropping done by faircamp. This section describes how to include content within the image in such a way that it never gets cropped away:

The least wide the image is shown is at an aspect ratio of 2.25:1 (corresponding e.g. to a resolution of 225x100, 675x300, etc.), that's on very wide and very narrow screens. The widest it is shown (when the browser is just below 960px wide) is at an aspect ratio of 5:1 (corresponding to a resolution of 500x100, 1500x300, etc.). If you create your image with an aspect ratio of 5:1, so e.g. at 1500x300, and place the text that should be not cropped within a rectangle of 2.25:1, so within a 675px wide rectangle at the center of the example 1500x300 image, the text should always be fully visible, uncropped, and only the parts to the left and right will get cropped off.

|<-------  5:1 (e.g. 1500×300)  ------->|
┌─────────────┬───────────┬─────────────┐
│             │           │             │
│   CROPPED   │ LOGO SAFE │   CROPPED   │
│             │           │             │
└─────────────┴───────────┴─────────────┘
              |<--------->|
           2.25:1 (e.g. 675×300)

image_description

Local-only This catalog setting can not inherit default values from other manifests

-- image_description
Me in my studio
-- image_description

If you use a catalog image, make sure to include an image_description so that visually impaired people can also make sense of it (this description is used as the alt text for the image).

You can either provide a multiline or inline value according to your preference and required length for the description. A multiline example:

-- image_description
A photograph separated into two planes:
In the foreground, an old lady, smiling into the camera.
In the background, an unrecognizable mechanical contraption.
-- image_description

An inline example:

image_description: A photograph of a cat, tiptoeing over modular synthesizer panels

links

Local-only This catalog setting can not inherit default values from other manifests

links:
- My music elsewhere https://example.com/my/music/elsewhere/
- Social media https://social.example.com/@account-a
- Imprint #imprint
- https://example.com/something/else/

You can supply any number of links, these are prominently displayed in the header/landing area of your catalog page. Links can be full urls (e.g. "https://example.com") or references to anchors within the page (e.g. "#about").

For each link you can supply either just the bare link (e.g. - https://example.com, or (more commonly) add a label for the link, which can be put before or after the link itself (- Example Label https://example.com or - https://example.com Example Label).

m3u

Default-able Use the prefixed form catalog.m3u outside of catalog manifests

This controls the generation of an M3U playlist for a catalog - it is disabled by default.

To enable the M3U playlist for a catalog:

m3u: enabled

To disable the M3U playlist for a catalog:

m3u: disabled

more

Local-only This catalog setting can not inherit default values from other manifests

-- more
Our label explores a niche between 90ies Italo Disco and scottish
folk music from the early 50ies.

Among the represented artists are: ...
-- more

This field lets you provide long-form content of any kind to augment the catalog homepage with: A biography/discography, mission statement, about text, links to related pages, etc. When provided, this content appears right after the releases on the catalog homepage.

The more field supports Markdown.

more_label

Default-able Use the prefixed form catalog.more_label outside of catalog manifests

more_label: About

If you provide long-form content for your catalog (which can be anything you want, content-wise) through the more field, by default there will be a link with the label "More" on your homepage, leading to the section containing that content. If you want to customize that label so it specifically refers to the type of content you are providing there, the more_label field allows you to do that. Some typical examples of custom labels one might use in the context of the catalog homepage: "About", "Biography", "Artist Statement", "Read on", "Artist roster" etc.

permalink

Local-only This catalog setting can not inherit default values from other manifests

permalink: example-catalog

The permalink is a short, unique text fragment (for instance: example-catalog) that forms a part of the permanent address of a catalog page. For an online faircamp site, the permalink is appended to the site.base_url to construct the full address of the page.

For instance: https://example.com (the site.base_url) + example-catalog (the permalink) = https://example.com/example-catalog – this is the link that you can share with your visitors to point them to the catalog page.

Permalinks may only contain the following characters:

• a-z (lowercase letters only)
• 0-9
• - (dash)

If you don't specify your own permalink, faircamp auto-generates one from the title (for instance the title Example Catalog becomes the permalink example-catalog then). Note that in this case when the title changes, the permalink does too. This can lead to other people's bookmarks or links to your site becoming invalidated. Therefore it's generally recommended to specify your own permalinks – at least for the most important things on your site.

If you set/enable either external_page or homepage for your catalog, the permalink is still relevant: The page address (part of which is the permalink) then becomes a redirect to either the external page or the homepage. Furthermore, the permalink is always part of the address of your RSS feeds, M3U playlists, etc. – even if your catalog page is set as the homepage.

platform_integration

Default-able Use the prefixed form catalog.platform_integration outside of catalog manifests

Facebook's Open Graph metadata (and other adjacent protocols) are used by platforms to crawl and harvest content from (linked) websites in order to present them using a uniform "card" design pattern inside social feeds and timelines.

By default, faircamp only renders metadata that is used to generate link previews whenever someone links to things on your faircamp site. This can be disabled with:

platform_integration: disabled

Open Graph properties that get rendered (when link previews are enabled) are the mandatory og:title, og:image (including alt, height and width), og:type (always as website) and og:url properties, as well as og:locale and og:site_name. Where present, the synopsis field is rendered as the og:description property additionally.

In the near future faircamp will also gain support for rendering content embeds, that is, metadata and embed code that allows platforms to directly integrate a media player for your audio material in user timelines. You can already configure this with the setting below, but until it's implemented this will act identically to the link_previews setting.

platform_integration: content_embeds

The factory setting (in case you need to reset your own inherited default) can be set with:

platform_integration: link_previews

podcast.categories

Default-able Use the prefixed form catalog.podcast.categories outside of catalog manifests

podcast.categories:
- History
- Arts > Design

Use this to set your catalog podcast feed's categories. You can either set a top level category only, or separate top-level and subcategory with a greater-than sign (>), for example Arts > Design for the top-level category Arts and subcategory Design.

podcast.explicit

Default-able Use the prefixed form catalog.podcast.explicit outside of catalog manifests

podcast.explicit: yes

Set this to yes if the catalog podcast feed contains explicit language or adult content.

published

Local-only This catalog setting can not inherit default values from other manifests

published: 2024-12-19T16:39:57-08:00

A date/time specifying when this catalog was first published on the faircamp site. This will be primarily used in your Atom/RSS feeds as metadata for feed consumers.

Also see the related updated setting – Date/time when this catalog was last updated on the faircamp site.

synopsis

Local-only This catalog setting can not inherit default values from other manifests

-- synopsis
My self hosted faircamp site, presenting some of my music.
Thanks for stopping by!
-- synopsis

A short (256 characters max), plaintext introduction text for your catalog, this is the first thing visitors will see - make it count!

theme.dark

Default-able Use the prefixed form catalog.theme.dark outside of catalog manifests

theme.dark:
accent_brightening = 85
accent_chroma = 50
accent_hue = 23
base_chroma = 34
base_hue = 180
background_alpha = 23
background_image = simple_texture.jpg

Adjusts the colors and/or background image of the dark theme. Note that theme.mode needs to be either adaptive or dark for this to have any effect, otherwise the dark theme is never displayed.

Tip: With the --theming-widget CLI option you can interactively explore the theme.dark and theme.light theme settings. Build your site with this option enabled and every page will contain the theming widget (don't forget to turn it off before deployment).

Dynamic range

theme.dark:
dynamic_range = 24

At the highest dynamic_range (100%) the dark theme is darkest and the least colorful (depending on chroma settings, see below). The lower the dynamic_range (0% being the default) the more it will have a differentiated dark grey feeling and become more colorfully tinted with rising base_chroma levels.

Tip: By interatively exploring different values with the --theming-widget option you can get a good feeling of what this does and how you want to set it.

Base and accent colors

theme.dark:
base_chroma = 34
base_hue = 180
accent_brightening = 85
accent_chroma = 50
accent_hue = 23

The theme is initially monochromatic (without color).

With base_chroma (0-100 (%)) you control the colorfulness of the theme, while the base_hue (0-360 (degrees)) setting sets the shade of the color.

Some elements on the page are accentuated (prominent buttons and the "timeline" of the audio player). The colorfulness of the accentuation is customized with the accent_chroma (0-100 (%)) setting, while the accent_hue (0-360 (degrees)) setting adjusts its shade. The accent_brightening (0-100 (%)) setting allows you to brighten or darken this color accent (it's at 50% by default), which allows for stronger and deeper colors still.

Background image

theme.dark:
background_alpha = 23
background_image = simple_texture.jpg

The previously described theme.dark settings can be handled carefree - no matter the settings, your site will stay readable (at worst it may look funny). When you set a background image however, choose carefully what image you use and how opaque you make it. Sharp details and strong contrasts within the image and against the text of the site will render the site hard to read or even unreadable. That said, background_image lets you reference the image to use, and with background_alpha (0-100 (%)) you can optionally control its opaqueness.

theme.font

Default-able Use the prefixed form catalog.theme.font outside of catalog manifests

By default, faircamp bundles and uses the Barlow font on a generated site, but alternatively you can also configure your site to only use your visitors' system font(s):

Using the standard sans serif font from the system of the visitor:

theme.font: system-sans

Using the standard serif font from the system of the visitor:

theme.font: system-serif

Using the standard monospace font from the system of the visitor:

theme.font: system-mono

To reset to faircamp's bundled default font:

theme.font: bundled-default

Usage of custom fonts entails complexities and responsibilities that faircamp can not generically automate away, therefore this requires manual integration through the site.assets and site.metadata options - this also gives a great amount of flexibility, including the possibility to use multiple fonts and tweak their integration down to the last detail where needed.

theme.light

Default-able Use the prefixed form catalog.theme.light outside of catalog manifests

theme.light:
accent_brightening = 85
accent_chroma = 50
accent_hue = 23
base_chroma = 34
base_hue = 180
background_alpha = 23
background_image = simple_texture.jpg

Adjusts the colors and/or background image of the light theme. Note that theme.mode needs to be either adaptive or light for this to have any effect, otherwise the light theme is never displayed.

Tip: With the --theming-widget CLI option you can interactively explore the theme.dark and theme.light theme settings. Build your site with this option enabled and every page will contain the theming widget (don't forget to turn it off before deployment).

Dynamic range

theme.light:
dynamic_range = 24

At the highest dynamic_range (100%) the light theme is the most bright and the least colorful (depending on chroma settings, see below). The lower the dynamic_range (0% being the default) the more it will have a differentiated light grey feeling and become more colorfully tinted with rising base_chroma levels.

Tip: By interatively exploring different values with the --theming-widget option you can get a good feeling of what this does and how you want to set it.

Base and accent colors

theme.light:
base_chroma = 34
base_hue = 180
accent_brightening = 85
accent_chroma = 50
accent_hue = 23

The theme is initially monochromatic (without color).

With base_chroma (0-100 (%)) you control the colorfulness of the theme, while the base_hue (0-360 (degrees)) setting sets the shade of the color.

Some elements on the page are accentuated (prominent buttons and the "timeline" of the audio player). The colorfulness of the accentuation is customized with the accent_chroma (0-100 (%)) setting, while the accent_hue (0-360 (degrees)) setting adjusts its shade. The accent_brightening (0-100 (%)) setting allows you to brighten or darken this color accent (it's at 50% by default), which allows for stronger and deeper colors still.

Background image

theme.light:
background_alpha = 23
background_image = simple_texture.jpg

The previously described theme.light settings can be handled carefree - no matter the settings, your site will stay readable (at worst it may look funny). When you set a background image however, choose carefully what image you use and how opaque you make it. Sharp details and strong contrasts within the image and against the text of the site will render the site hard to read or even unreadable. That said, background_image lets you reference the image to use, and with background_alpha (0-100 (%)) you can optionally control its opaqueness.

theme.mode

Default-able Use the prefixed form catalog.theme.mode outside of catalog manifests

theme.mode: light

This controls the overall theme appearance – dark, light or adaptive.

The default setting is adaptive, which means that a dark or light theme will be displayed automatically, based on browser/system preferences of each site visitor.

With dark and light you can instead opt for a fixed dark or light appearance for all visitors.

theme.round_corners

Default-able Use the prefixed form catalog.theme.round_corners outside of catalog manifests

To give a softer feel to your page, set the round_corners option to enabled, this will add a round corner to your cover images:

theme.round_corners: enabled

By setting it to disabled you can restore the default behavior:

theme.round_corners: enabled

theme.waveforms

Default-able Use the prefixed form catalog.theme.waveforms outside of catalog manifests

By default, the width of each track's waveform on a multitrack release page will render at a different length, reflecting the duration of the track in relation to the longest track on the release - for instance if the longest track on a release is about two minutes long, that one will span the full width, but another track that is only about one minute long will span only half of that width. If you publish releases whose tracks have wildly varying lengths, shorter tracks might get very narrow in the interface. If this is a concern to you, or you just generally want all tracks to be full-width as an aesthetic choice, you can enable this alternative behavior with this setting:

theme.waveforms: absolute

You can also disable waveforms altogether, resulting in a more compact layout:

theme.waveforms: disabled

With relative you can restore the default waveform behavior:

theme.waveforms: relative

title

Local-only This catalog setting can not inherit default values from other manifests

The title for the catalog.

title: My music

updated

Local-only This catalog setting can not inherit default values from other manifests

updated: 2024-12-19T16:39:57-08:00

A date/time specifying when this catalog was last updated on the faircamp site. This will be primarily used in your Atom/RSS feeds as metadata for feed consumers.

Also see the related published setting – Date/time when this catalog was first published on the faircamp site.

visibility

Default-able Use the prefixed form catalog.visibility outside of catalog manifests

visibility: featured

Controls the visibility level of this catalog (default: featured).

Available options:

• featured (default) – The catalog is openly accessible and included in the browse/search navigation
• public – The catalog is openly accessible, but excluded from the browse/search navigation
• unlisted – The catalog is not linked to anywhere, visitors need to know and directly enter the URL to get to its page.
• offline – The catalog is entirely omitted when generating the site and does not appear anywhere on it