mirror of
https://git.sr.ht/~tsileo/microblog.pub
synced 2024-11-19 21:24:27 +00:00
226 lines
6.8 KiB
Markdown
226 lines
6.8 KiB
Markdown
# User's guide
|
|
|
|
[TOC]
|
|
|
|
## ActivityPub
|
|
|
|
Using microblog.pub efficiently requires knowing a bit about how [ActivityPub](https://activitypub.rocks/) works.
|
|
|
|
Skimming over the [Overview section of the ActivityPub specification](https://www.w3.org/TR/activitypub/#Overview) should be enough.
|
|
|
|
Also, you should know that the **Fediverse** is a common name used to describe all the interconnected/federated instances of servers supporting ActivityPub (like Mastodon, Pleroma, PeerTube, PixelFed...).
|
|
|
|
## Configuration
|
|
|
|
### Profile
|
|
|
|
You initial profile configuration is generated via the setup wizard.
|
|
|
|
You can manually edit the configuration file stored in `data/profile.toml` ([TOML](https://toml.io/en/)), note that the following config items cannot be updated (without breaking federation):
|
|
|
|
- `domain`
|
|
- `username`
|
|
|
|
As these two config items define your ActivityPub handle `@handle@domain`.
|
|
|
|
You can tweak your profile by tweaking these items:
|
|
|
|
- `name`
|
|
- `summary` (using Markdown)
|
|
- `icon_url`
|
|
|
|
Whenever one of these config items is updated, an `Update` activity will be sent to all know server to update your remote profile.
|
|
|
|
The server will need to be restarted for taking changes into account.
|
|
|
|
### Profile metadata
|
|
|
|
You can add metadata to your profile with the `metadata` config item.
|
|
|
|
Markdown is supported in the `value` field.
|
|
|
|
Be aware that most other softwares like Mastodon will limit the number of key/value to 4.
|
|
|
|
```toml
|
|
metadata = [
|
|
{key = "Documentation", value = "[https://docs.microblog.pub](https://docs.microblog.pub)"},
|
|
{key = "Source code", value = "[https://sr.ht/~tsileo/microblog.pub/](https://sr.ht/~tsileo/microblog.pub/)"},
|
|
]
|
|
```
|
|
|
|
### Manually approving followers
|
|
|
|
If you wish to manually approve followers, add this config item to `profile.toml`:
|
|
|
|
```toml
|
|
manually_approves_followers = true
|
|
```
|
|
|
|
The default value is `false`.
|
|
|
|
### Privacy replace
|
|
|
|
You can define domain to be rewrited to more "privacy friendly" alternatives, like [Invidious](https://invidious.io/)
|
|
or [Nitter](https://nitter.net/about).
|
|
|
|
To do so, just add as these extra config items, this is a sample config that rewrite URLs for Twitter, Youtube, Reddit and Medium:
|
|
|
|
```toml
|
|
privacy_replace = [
|
|
{domain = "youtube.com", replace_by = "yewtu.be"},
|
|
{domain = "youtu.be", replace_by = "yewtu.be"},
|
|
{domain = "twitter.com", replace_by = "nitter.fdn.fr"},
|
|
{domain = "medium.com", replace_by = "scribe.rip"},
|
|
{domain = "reddit.com", replace_by = "teddit.net"},
|
|
]
|
|
```
|
|
|
|
### Customization
|
|
|
|
#### Custom emoji
|
|
|
|
You can add custom emoji in the `data/custom_emoji` directory and they will be picked automatically.
|
|
|
|
#### Custom CSS
|
|
|
|
The CSS is written with [SCSS](https://sass-lang.com/documentation/syntax).
|
|
|
|
You can override colors by editing `data/_theme.scss`:
|
|
|
|
```scss
|
|
$primary-color: #e14eea;
|
|
$secondary-color: #32cd32;
|
|
```
|
|
|
|
See `app/scss/main.scss` to see what variables can be overidden.
|
|
|
|
#### Code highlighting theme
|
|
|
|
You can switch to one of the [styles supported by Pygments](https://pygments.org/styles/) by adding a line in `profile.toml`:
|
|
|
|
```toml
|
|
code_highlighting_theme = "solarized-dark"
|
|
```
|
|
|
|
### Blocking servers
|
|
|
|
In addition to blocking "single actors" via the admin interface, you can also prevent any communications with whole servers.
|
|
|
|
Add a `blocked_servers` config item into `profile.toml`.
|
|
|
|
The `reason` field is just there to help you document/remember why a server was blocked.
|
|
|
|
You should unfollow any account from a server before blocking it.
|
|
|
|
```toml
|
|
blocked_servers = [
|
|
{hostname = "bad.tld", reason = "Bot spam"},
|
|
]
|
|
```
|
|
|
|
## Public website
|
|
|
|
Public notes will be visible on the homepage.
|
|
|
|
Only the last 20 followers/follows you be showing on the public website.
|
|
|
|
And only the last 20 interactions (likes/shares/webmentions) will be displayed, to keep things simple/clean.
|
|
|
|
## Admin section
|
|
|
|
You can login to the admin section by clicking on the `Admin` link in the footer or by visiting `https://yourdomain.tld/admin`.
|
|
The password is the one set during the initial configuration.
|
|
|
|
### Lookup
|
|
|
|
The `Lookup` section allows you to interact with any remote remote objects/content on the Fediverse.
|
|
|
|
The lookup supports:
|
|
|
|
- profile page, like `https://testing.microblog.pub`
|
|
- content page, like `https://testing.microblog.pub/o/4bccd2e31fad43a7896b5a33f0b8ded9`
|
|
- username handle like `@testing@testing.microblog.pub`
|
|
- ActivityPub ID, like `https://testing.microblog.pub/o/4bccd2e31fad43a7896b5a33f0b8ded9`
|
|
|
|
## Authoring notes
|
|
|
|
Notes are authored in [Markdown](https://commonmark.org/). There is no imposed characters limit.
|
|
|
|
If you fill the content warning, the note will be automatically marked as sensitive.
|
|
|
|
You can add attachments/upload files.
|
|
When attaching pictures, EXIF metadata (like GPS location) will be removed automatically before being stored.
|
|
|
|
Consider marking attachments as sensitive using the checkbox if needed.
|
|
|
|
## Webmentions
|
|
|
|
Public notes that link to "Webmention-compatible" website will trigger an outgoing webmention.
|
|
Most websites that support Webmention will display your profile on the mentioned page.
|
|
|
|
### Fenced code blocks
|
|
|
|
You can include code blocks in notes, using the triple backtick syntax.
|
|
|
|
The code will be highlighted using [Pygments](https://pygments.org/).
|
|
|
|
Example:
|
|
|
|
~~~
|
|
Hello
|
|
|
|
```python
|
|
print("I will be highlighted")
|
|
```
|
|
|
|
~~~
|
|
|
|
## Interactions
|
|
|
|
microblog.pub supports the most common interactions supported by the Fediverse.
|
|
|
|
### Shares
|
|
|
|
Sharing (or announcing) an object will relay it to your followers and notify the author.
|
|
It will also be displayed on the homepage.
|
|
|
|
Most receiving servers will increment the number of shares.
|
|
|
|
Receiving a share will trigger a notification, increment the shares counter on the object and the actor avatar will be displayed on the object permalink.
|
|
|
|
### Likes
|
|
|
|
Liking an object will notify the author.
|
|
|
|
Unlike sharing, liked object are not displayed on the homepage.
|
|
|
|
Most receiving servers will increment the number of likes.
|
|
|
|
Receiving a like will trigger a notification, increment the likes counter on the object and the actor avatar will be displayed on the object permalink.
|
|
|
|
### Bookmarks
|
|
|
|
Bookmarks allow you to like objects without notifying the author.
|
|
|
|
It is basically a "private like", and allow you to easily access them later.
|
|
|
|
It will also prevent objects to be pruned.
|
|
|
|
### Webmentions
|
|
|
|
Sending webmention to ping mentioned websites is done automatically once a public note is authored.
|
|
|
|
Receiving a webmention will trigger a notification, increment the webmentions counter on the object and the source page will be displayed on the object permalink.
|
|
|
|
## Backup and restore
|
|
|
|
All the data generated by the server is located in the `data/` directory:
|
|
|
|
- Configuration files
|
|
- Server secrets
|
|
- SQLite3 database
|
|
- Theme modifications
|
|
- Custom emoji
|
|
- Uploaded media
|
|
|
|
Restoring is as easy as adding your backed up `data/` directory into a fresh deployment.
|