Skip to main content

Customizing Soapbox

Soapbox uses your own site's name and branding throughout the interface. This allows every Soapbox site to be different, and catered to a particular audience. Unlike Mastodon, which uses the "Mastodon" branding on all instances, Soapbox does not refer to itself in the user interface.

Backend settings​

The site's name and description are configured in the backend itself. These are settings global to your website, and will also affect mobile apps and other frontends accessing your website.

  • On Mastodon, you can change it through the admin interface.
  • On Pleroma, it can be edited through AdminFE, or by editing config/prod.secret.exs on the server.

These settings are exposed through the API under GET /api/v1/instance.

Soapbox settings​

Most settings are specific to your Soapbox installation and not the entire website. That includes the logo, default theme, and more.

  • On Pleroma, admins can edit these settings directly from Soapbox. Just click "Soapbox config" in the sidebar, or navigate directly to /soapbox/config.
  • On Mastodon, admins need to upload a JSON file with the settings, and make it available at https://yoursite.tld/instance/soapbox.json.

If using Pleroma, these settings are exposed through the API under GET /api/pleroma/frontend_configurations. Otherwise, the settings need to be uploaded manually and made available at GET /instance/soapbox.json.

About pages​

It is possible to create arbitrary HTML pages under /about/:page on your website.

In your Soapbox installation directory (probably on your server), find the instance folder. For Pleroma, this will be located under /opt/pleroma/instance/static/instance. This directory contains files that are loaded on-demand by the browser, including about pages.

Just create a file like instance/about/hello.html on your server and it will become available under /about/hello on your instance. If you create a file called index.html, it will be treated as the root (available under /about), and you can create subfolders too.

For convenience, Soapbox ships with sample files under instance/about.example. Simply rename that directory to about and start editing!