diff --git a/README.md b/README.md index 3afa9d04f..1027957d1 100644 --- a/README.md +++ b/README.md @@ -175,20 +175,21 @@ To contribute, see [Contributing to Soapbox](docs/contributing.md). # Customization -Soapbox supports customization of the user interface, to allow per instance branding and other features. Current customization features include: - -* Instance name -* Site logo -* Favicon -* About page -* Terms of Service page -* Privacy Policy page -* Copyright Policy (DMCA) page -* Promo panel list items, e.g. blog site link -* Soapbox extensions, e.g. Patron module -* Default settings, e.g. default theme - -Customization details can be found in the [Customization doc](docs/customization.md) +Soapbox supports customization of the user interface, to allow per-instance branding and other features. +Some examples include: + +- Instance name +- Site logo +- Favicon +- About page +- Terms of Service page +- Privacy Policy page +- Copyright Policy (DMCA) page +- Promo panel list items, e.g. blog site link +- Soapbox extensions, e.g. Patron module +- Default settings, e.g. default theme + +More details can be found in [Customizing Soapbox](docs/customization.md). # License & Credits diff --git a/docs/customization.md b/docs/customization.md index 9c0a31301..2b5b38276 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -1,110 +1,26 @@ # Customizing Soapbox -If you haven't already, [install Soapbox](../installing). But before you install soapbox, you should consider how Soapbox is installed, by default. +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. -Soapbox, by default, is installed to replace the default Pleroma front end. By extension, the Pleroma Masto front end continues to be available at the `/web` sub-URL, which you can reference, if you'd like, in the `promoPanel` section of `soapbox.json` +## Backend settings -There are two main places Soapbox gets its configuration: +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. -- `/opt/pleroma/config/prod.secret.exs` +- 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. -- `/opt/pleroma/instance/static/instance/soapbox.json` +These settings are exposed through the API under GET `/api/v1/instance`. -Logos, branding, etc. take place in the `soapbox.json` file. -For example: +## Soapbox settings -```json -{ - "logo": "/instance/images/soapbox-logo.svg", - "brandColor": "#0482d8", - "promoPanel": { - "items": [{ - "icon": "area-chart", - "text": "Our Site stats", - "url": "https://fediverse.network/example.com" - }, { - "icon": "comment-o", - "text": "Our Site blog", - "url": "https://blog.example.com" - }] - }, - "extensions": { - "patron": false - }, - "defaultSettings": { - "autoPlayGif": false, - "themeMode": "light" - }, - "copyright": "♡2020. Copying is an act of love. Please copy and share.", - "customCss": [ - "/instance/static/your_file_here.css" - ], - "navlinks": { - "homeFooter": [ - { "title": "About", "url": "/about" }, - { "title": "Terms of Service", "url": "/about/tos" }, - { "title": "Privacy Policy", "url": "/about/privacy" }, - { "title": "DMCA", "url": "/about/dmca" }, - { "title": "Source Code", "url": "/about#opensource" } - ] - } -} -``` +Most settings are specific to your Soapbox installation and not the entire website. +That includes the logo, default theme, and more. -Customizable features include: +- 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`. -* Instance name -* Site logo -* Promo panel list items, e.g. blog site link -* Favicon -* About pages -* Default user settings -* Cascadomg Style Sheets (CSS) - -## Instance Name -Instance name is edited during the Pleroma installation step or via AdminFE. - -## Instance Description -Instance description is edited during the Pleroma installation step or via AdminFE. - -## Captcha on Registration Page -Use of the Captcha feature on the registration page is configured during the Pleroma installation step or via AdminFE. - -## Site Logo, Brand Color, and Promo Panel List Items -The site logo, brand color, and promo panel list items are customized by copying `soapbox.example.json` in the `static/instance` folder to `soapbox.json` and editing that file. It is recommended that you test your edited soapbox.json file in a JSON validator, such as [JSONLint](https://jsonlint.com/), before using it. - -The icon names for the promo panel list items can be source from [Line Awesome](https://icons8.com/line-awesome). Note that you should hover over or click a selected icon to see what the icon's real name is, e.g. `world` - -The site logo, in SVG format, is rendered to be able to allow the site theme colors to appear in the less than 100% opaque sections of the logo. -The logo colors are rendered in a color that provides contrast for the site theme. - -The `navlinks` section of the `soapbox.json` file references the links that are displayed at the bottom of the Registration/Login, About, Terms of Service, Privacy Policy and Copyright Policy (DMCA) pages. - -The `brandColor` in `soapbox.json` refers to the main color upon which the look of soapbox-fe is defined. - -After editing your HTML files and folder names, save the file and refresh your browser. - -## Favicon -The favicon is customized by dropping a favicon.png file into the `/static` folder and refreshing your browser. - -## About Pages -Soapbox supports any number of custom HTML pages under `yoursite.com/about/:slug`. - -The finder will search `/opt/pleroma/instance/static/instance/about/:slug.html` to find your page. -Use the name `index.html` for the root page. - -Example templates are available for editing in the `static/instance/about.example` folder, such as: -* index.html -* tos.html -* privacy.html -* dmca.html - -Simply rename `about.example` to `about`, or create your own. - -The `soapbox.json` file navlinks section's default URL values are pointing to the above file location, when the `about.example` folder is renamed to `about` -These four template files have placeholders in them, e.g. "Your_Instance", that should be edited to match your Soapbox instance configuration, and will be meaningless to your users until you edit them. - -## Alternate Soapbox URL Root Location -If you want to install Soapbox at an alternate URL, allowing you to potentially run more than 2 front ends on a Pleroma server, you can consider deploying the Nginx config created by @a1batross, available [here](https://git.mentality.rip/a1batross/soapbox-nginx-config/src/branch/master/soapbox.nginx) - -Tech support is limited for this level of customization +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`.