microblog.pub/docs/user_guide.md

User's guide

[TOC]

ActivityPub

Using microblog.pub efficiently requires knowing a bit about how ActivityPub works.

Skimming over the Overview section of the ActivityPub specification 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), 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.

Privacy replace

You can define domain to be rewrited to more "privacy friendly" alternatives, like Invidious or Nitter.

To do so, just add as these extra config items, this is a sample config that rewrite URLs for Twitter, Youtube, Reddit and Medium:

privacy_replace = [
    {domain = "youtube.com", 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.

You can override colors by editing data/_theme.scss:

$primary-color: #e14eea;                                                                            
$secondary-color: #32cd32;

See app/scss/main.scss to see what variables can be overidden.

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. 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.

Example:

Hello

```python
print("I will be highlighted")
```

Interactions

microblog.pub supports the most common interactions supported by the Fediverse.

Shares

Sharing 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.

TODO receiving

Likes

Liking an object will notify the author. Unkike sharing, liked object are not displayed on the homepage.

Most receiving servers will increment the number of likes.

TODO receiving

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.

TODO receiving

Webmentions

Sending webmention to ping mentioned website is done automatically once a note is authored, see TODO.

TODO side-effect of receiving a webmention.

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.