microblog/docs/user_guide.md

227 lines
6.8 KiB
Markdown
Raw Normal View History

2022-07-11 20:01:37 +00:00
# User's guide
2022-07-05 19:35:39 +00:00
[TOC]
2022-07-12 17:42:31 +00:00
## 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.
2022-08-24 05:52:46 +00:00
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
2022-08-09 21:03:52 +00:00
privacy_replace = [
{domain = "youtube.com", replace_by = "yewtu.be"},
2022-08-24 05:52:46 +00:00
{domain = "youtu.be", replace_by = "yewtu.be"},
2022-08-09 21:03:52 +00:00
{domain = "twitter.com", replace_by = "nitter.fdn.fr"},
{domain = "medium.com", replace_by = "scribe.rip"},
{domain = "reddit.com", replace_by = "teddit.net"},
]
```
2022-07-12 17:42:31 +00:00
### Customization
2022-07-16 06:39:12 +00:00
#### Custom emoji
You can add custom emoji in the `data/custom_emoji` directory and they will be picked automatically.
2022-07-12 17:42:31 +00:00
2022-07-30 07:43:36 +00:00
#### 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.
2022-08-23 17:40:45 +00:00
#### 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"
```
2022-08-24 05:52:46 +00:00
### 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"},
]
```
2022-07-12 17:42:31 +00:00
## 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
2022-07-14 18:05:36 +00:00
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.
2022-07-12 17:42:31 +00:00
### 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
2022-08-24 05:52:46 +00:00
Sharing (or announcing) an object will relay it to your followers and notify the author.
2022-07-12 17:42:31 +00:00
It will also be displayed on the homepage.
Most receiving servers will increment the number of shares.
2022-08-24 05:52:46 +00:00
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.
2022-07-12 17:42:31 +00:00
### Likes
Liking an object will notify the author.
2022-08-24 05:52:46 +00:00
Unlike sharing, liked object are not displayed on the homepage.
2022-07-12 17:42:31 +00:00
Most receiving servers will increment the number of likes.
2022-08-24 05:52:46 +00:00
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.
2022-07-12 17:42:31 +00:00
### 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.
2022-08-24 05:52:46 +00:00
It will also prevent objects to be pruned.
2022-07-12 17:42:31 +00:00
### Webmentions
2022-08-24 05:52:46 +00:00
Sending webmention to ping mentioned websites is done automatically once a public note is authored.
2022-07-12 17:42:31 +00:00
2022-08-24 05:52:46 +00:00
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.
2022-07-12 17:42:31 +00:00
2022-07-11 20:01:37 +00:00
## Backup and restore
All the data generated by the server is located in the `data/` directory:
2022-07-16 06:39:12 +00:00
- Configuration files
- Server secrets
- SQLite3 database
- Theme modifications
- Custom emoji
- Uploaded media
2022-07-11 20:01:37 +00:00
Restoring is as easy as adding your backed up `data/` directory into a fresh deployment.