Faircamp 2.0 Docs
On this page ☰

Site settings

The site is the single, global entity that allows specifying settings for the whole of your faircamp site, including setting defaults for everything in it.

These settings go into in the site manifest. It is a plaintext file called site.eno at the root of your site directory. The site manifest can contain the settings documented on this page, as well as any number of defaults for the artists, catalogs, multitracks and tracks on your site (which are documented on their respective pages).

An example site.eno file:

base_url: https://music.example.com/
language: en
title: My music

multitrack.more_label: About
multitrack.download_formats:
- flac
- mp3
- opus

*.embedding: disabled
*.m3u: enabled
*.theme.mode: light
*.theme:
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 the site.

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

artist_attribution: disabled

By default, artist names are displayed next to all releases and tracks on your site: On artist, catalog, multitrack and track pages, in search results, and conditionally in the track list and docked player only when artists on a release differ between tracks. This is the enabled setting.

By setting artist_attribution to disabled you can change this, leaving out artists everywhere.

Typical usecases for this include:

  • Single artist sites where everything is by the same artist anyway
  • Podcasts for which the concept of "artists" does not apply, although episodes might still be tagged with the podcast name as "artist"
  • Conceptual projects that diverge from mainstream cultural practices

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

This allows specifying arbitrary files for inclusion in the build (more precisely, in the site's build directory root). Some of the most common usecases for this are for instance:

  • Providing script files for analytics
  • Providing stylesheet files that customize the style beyond faircamp's theming system
  • Providing complementary assets like font files, images, etc.

For instance, to include a few files:

assets:
- analytics.js
- custom.css
- my_font.woff2

Any files you provide will be included in the build with exactly the filename you specify. If your filename(s) collide with any directory or file names that faircamp generates, faircamp will point this out to you and abort the build - in this case you need to assign other, non-conflicting name(s).

Note that specifying (for instance) a .css file does not mean the styles will be automatically applied on the page, neither does specifying a .js file lead to the script being executed on the page automatically. If you want to directly use the assets in this way on your faircamp page (which might not be your usecase, hence this is not done automatically), you additionally need to use the metadata setting to include the respective directives for it in the <head>…</head> section of your site.

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

To allow embeds, M3U playlists and feeds to be generated (whether they are enabled is configured on its own) you have to set base_url:

base_url: https://example.com

This url should be the website url under which you want your faircamp site to go online.

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

cache_optimization: delayed

Advanced control over caching strategy.

Allowed options: delayed, immediate, wipe, manual

Faircamp maintains an asset cache that holds the results of all computation-heavy build artifacts (transcoded audio files, images, and compressed archives). By default this cache uses the delayed optimization strategy: Any asset that is not directly used in a build gets marked as stale and past a certain period (e.g. 24 hours) gets purged from the cache during a follow-up build (if it is not meanwhile reactivated because it's needed again). This strikes a nice balance for achieving instant build speeds during editing (after assets have been generated initially) without inadvertently growing a storage resource leak in a directory you don't ever look at normally.

If you're short on disk space you can switch to immediate optimization, which purges stale assets right after each build (which might result in small configuration mistakes wiping cached assets that took long to generate as a drawback).

If you're even shorter on disk space you can use wipe optimization, which just completely wipes the cache right after each build (so everything needs to be regenerated on each build).

If you want full control you can use manual optimization, which does not automatically purge anything from the cache but instead reports stale assets after each build and lets you use faircamp --optimize-cache and/or faircamp --wipe-cache accordingly whenever you're done with your changes and e.g. don't expect to generate any new builds for a while.

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

clean_urls

By default, all generated internal page links on a Faircamp site point to html files, for instance my-album/index.html. This allows your built site to be viewed locally/offline from disk without requiring faircamp or a web server, and it also allows you to instantly long-term-archive your site at any point in time.

When you take your site online, you might want to generate the site with clean urls instead, that is, with internal page links that do not point to the html files, but only to the directories, for instance my-album/. This is disadvantageous for archival and offline viewing, but will present online visitors with shorter, prettier page addresses.

To enable this, simply specify the clean_urls setting.

Note that there is also a --no-clean-urls flag that can be specified in the CLI in order to disable this setting on a per-build basis, useful e.g. if you automatically create and archive builds from a periodically running script.

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

disable_faircamp_signature

By default faircamp adds a subtle faircamp signature (faircamp logo, title and version) to the footer. If you want to disable this (no judgement!) you can use this option.

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

disable_favicon

Out of the box faircamp includes its default favicon on your site. If you want to disable the favicon or use your own, use this option. For your own favicon additionally use assets to include it in your build and metadata to reference it in your site's <head>…</head> section.

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

language: fr

Available languages

Faircamp currently ships with these languages:

  • Catalan ca
  • Chinese (Simplified, Mandarin, PRC Official Putonghua dialect) zh-hans-cn
  • Chinese (Traditional, Mandarin, Taiwan dialect) zh-hant-tw
  • Danish da
  • Dutch nl
  • English en (default)
  • Finnish fi
  • French fr
  • German de
  • Italian it
  • Japanese ja
  • Lithuanian lt
  • Norwegian Bokmål nb
  • Polish pl
  • Portuguese (European) pt-pt
  • Russian ru
  • Spanish es
  • Serbian (Cyrillic) sr-cyrl
  • Serbian (Latin) sr-latn
  • Swedish sv
  • Turkish tr
  • Ukrainian uk
  • Welsh cy

You can easily contribute additional or improved language translations by going to the translation website and following the instructions. No account and no special knowledge is needed, all that is required is a little bit of your time and your will to help out.

If there are no translations for your language yet, you can still set the language code, this is used to auto-determine the text direction (LTR/RTL) and declare the language for your content on the site and in feed metadata - the interface texts will still be in english then of course.

language: ar

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

links:
- Website https://example.com
- Donations https://donations.example.com
- Imprint #imprint
- https://social.example.com/profile/

This allows you to specify site-wide links which are not tied to any particular page, and therefore displayed on all of them. Practically speaking, site links are currently rendered in the footer of each page.

This setting is primarily intended for linking to websites directly related to your faircamp site, to donation pages or profiles on social media platforms, to legal information, to an imprint page, and so on.

You can supply any number of links, and links can be full urls (e.g. https://example.com) or references to anchors within the page (e.g. #about), although the latter case only makes sense for anchors present on each and every page of your site, so carefully deliberate this use beforehand.

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).

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

This allows you to specify arbitrary tags for inclusion in the <head>…</head> section of every page on your faircamp site. Some of the most common usecases for this are for instance:

  • Including an external analytics script file
  • Specifying style customizations or linking to a stylesheet containing them
  • Adding your own site-wide <meta …> tags

Now before copying/pasting from the snippets below, take note that assets included through assets must not be included simply by referring to their filename alone - instead, take their filename (e.g. custom.css) and wrap it in double curly braces, like so: {{custom.css}}.

This way, faircamp will identify them as explicit references to your assets and replace them with the correct, relative path on every page (custom.css on the homepage, ../custom.css on artist and release pages, ../../custom.css on track pages, and so on). A side-benefit from this is that faircamp will ensure the reference's integrity for you - if the filename in your reference does not match the file on disk, you will know before the site is even built.

For instance, to link to an analytics script file included through assets:

assets: analytics.js

-- metadata
<script src="{{analytics.js}}"></script>
-- metadata

To link to a custom css file that internally references a png file, with both of them included through assets:

assets:
- custom.css
- marker.png

-- metadata
<link href="{{custom.css}}" rel="stylesheet">
-- metadata

Note that when (for example) custom.css internally references marker.png, such internal references must not use the double curly braces otherwise used in metadata, as the .css and .png file always keep the same relative location to each other - and faircamp does not touch what's inside your site assets anyhow.

To directly specify style tweaks that additionally use an svg included through assets:

assets: marker.svg

-- metadata
<style>
    a { text-decoration-thickness: .2em; }
    ul {
        list-style: georgian inside url("{{marker.svg}}");
        padding-left: 0;
    }
</style>
-- metadata

Fediverse:creator meta

To include fediverse:creator metadata:

-- metadata
<meta name="fediverse:creator" content="@JohnMastodon@example.com"/>
-- metadata

Domain verification using rel-me links

If you want to use (e.g.) Mastodon's verification feature, which is based on rel="me", this is how it's done:

-- metadata
<link href="https://example.com" rel="me"/>
-- metadata

Tread carefully with this feature

Lastly, please keep in mind that modifications you make through this feature have the capability to break readability, accessibility, functionality, etc. for the visitors on your page - you are without guardrails here - so be considerate what changes you make. Additionally, if you make any such modifications on your page and at some point observe bugs on your faircamp site, it's strongly recommended to confirm that your modifications are not somehow responsible for them before reporting them, and to mention them alongside your bugreports as well, just to be sure.

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

The over-all title of your site, which appears in the header, footer, inside the RSS Feed, etc.

title: My music

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

When other people or sites hotlink to your site's resources, or you discover that people are blatantly sharing direct download links to your releases, you can change the url_seed – a freeform text fragment that is used in the generation of unique download urls when your site is built:

url_seed: Put any text here

Whatever text you specify here controls the "deterministic randomization" of faircamp's download urls. It's important to note though that the text itself never shows up in the urls.

Your download urls stay valid as long as this text does not change. Any time you update the text, all download urls are regenerated, and thereby all old ones invalidated. Practically speaking it makes sense to use some kind of a date as the text on the right, for instance url_seed: 1 April 2022 could tell you that your current download urls have been valid since that day. You could also use "2022-04", "Spring 2022" or such, given that one usually will not manually invalidate the urls on a daily basis.

If you need an even stronger mechanism, you can also use the rotate keyword:

url_seed: rotate

This will automatically re-new all download urls each time you generate the site. Note however that without additional manual tweaks to your deployment routine, this will have very adverse effects on your deployment time, prompting a re-upload of all your audio files each time you deploy, so use this with caution, only when it's really needed, and ideally adapting your deployment strategy to work around unnecessary re-uploads.

Note that all of this is a general countermeasure against hotlinking to your assets and against people linking directly to your download pages (rather than your release pages for instance). However, all of this cannot stop people from passing around your download codes (if you use download codes to protect your downloads). If you witness malicious actions of that kind, you can instead configure and distribute new download codes to your legitimate buyers/subscribers, which will prevent anyone who obtained or still obtains the old codes from using them, effectively blocking their access to your downloads.

Previous Multitrack settings