bigbuffet/bigbuffet-rw
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite customization guide

Browse source
This commit is contained in:
Alex Gleason 2022-07-18 12:12:50 -05:00
parent 2e0a8e864e
commit 2f27d879cc
No known key found for this signature in database
GPG key ID: 7211D1F99744FBB7
2 changed files with 29 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
README.md
View file

@ -175,20 +175,21 @@ To contribute, see [Contributing to Soapbox](docs/contributing.md).
# Customization # Customization
Soapbox supports customization of the user interface, to allow per instance branding and other features. Current customization features include: Soapbox supports customization of the user interface, to allow per-instance branding and other features.
Some examples include:
* Instance name - Instance name
* Site logo - Site logo
* Favicon - Favicon
* About page - About page
* Terms of Service page - Terms of Service page
* Privacy Policy page - Privacy Policy page
* Copyright Policy (DMCA) page - Copyright Policy (DMCA) page
* Promo panel list items, e.g. blog site link - Promo panel list items, e.g. blog site link
* Soapbox extensions, e.g. Patron module - Soapbox extensions, e.g. Patron module
* Default settings, e.g. default theme - Default settings, e.g. default theme
Customization details can be found in the [Customization doc](docs/customization.md) More details can be found in [Customizing Soapbox](docs/customization.md).
# License & Credits # License & Credits

116
docs/customization.md
View file

@ -1,110 +1,26 @@
# Customizing Soapbox # 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. ## Soapbox settings
For example:
```json Most settings are specific to your Soapbox installation and not the entire website.
{ That includes the logo, default theme, and more.
"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" }
]
}
}
```
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 If using Pleroma, these settings are exposed through the API under GET `/api/pleroma/frontend_configurations`.
* Site logo Otherwise, the settings need to be uploaded manually and made available at GET `/instance/soapbox.json`.
* 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