search

hodgesmr / mastodon_digest

A Python script that aggregates recent popular posts from your Mastodon timeline
BSD 3-Clause "New" or "Revised" License
439 stars 58 forks source link

readme

Mastodon Digest

⚠️ Update, 2023-05-21: Mastodon Digest is currently in maintenance-only mode. I do not have the capacity to continue fielding feature requests or PRs that fundamentally alter the way the tool works. If you have an idea for a new feature, forks are encouraged. I will continue to push updates for bug or security fixes. If you're looking for options that are more actively maintained, I suggest: Fediview or this fork. I'm heartened by how much positive attention this got among many Mastodon communities. For me this was always a toy. I'm glad I could push some open source code that gave people room to experiment.

This is a Python project that generates a digest of popular Mastodon posts from your home timeline. The digest is generated locally. The digests present two lists: posts from users you follow, and boosts from your followers. Each list is constructed by respecting your server-side content filters and identifying content that you haven't yet interacted with. Digests are automatically opened locally in your web browser. You can adjust the digest algorithm to suit your liking (see Command arguments). The digest will not contain posts from users who include #nobot or #noindex in their bio.

Mastodon Digest

Run

You can run in Docker or in a local python environment. But first, set up your environment:

Before you can run the tool locally, you need to copy .env.example to .env (which is ignored by git) and fill in the relevant environment variables:

cp .env.example .env

Both the Docker container and the python script will construct the environment from the .env file. This is usually sufficient and you can stop here. However, you may optionally construct your environment manually. This is may be useful for deployed environments.

Docker

First, build the image:

make build

Then you can generate and open a digest:

make run

You can also pass command arguments:

make run FLAGS="-n 8 -s ExtendedSimpleWeighted -t lax"

Local

Mastodon Digest has been tested to work on Python 3.9 and above.

With Make

If your system Python meets that, you can:

make local

You can also pass command arguments:

make local FLAGS="-n 8 -s ExtendedSimpleWeighted -t lax"

Manually

Althernatively if you have a different Python 3.9 environment, you can:

pip install -r requirements.txt

Then generate a Mastodon Digest with:

python run.py

Through either method, the digest is written to render/index.html by default. You can then view it with the browser of your choice.

Command arguments

A number of command arguments are available to adjust the algorithm. You can see the command arguments by passing the -h flag:

python run.py -h
usage: mastodon_digest [-h] [-f TIMELINE] [-n {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24}]
                       [-s {ExtendedSimple,ExtendedSimpleWeighted,Simple,SimpleWeighted}] [-t {lax,normal,strict}]
                       [-o OUTPUT_DIR] [--theme {light,default}]

options:
  -h, --help            show this help message and exit
  -f TIMELINE           The timeline to summarize: Expects 'home', 'local' or 'federated', or 'list:id', 'hashtag:tag' (default:
                        home)
  -n {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24}
                        The number of hours to include in the Mastodon Digest (default: 12)
  -s {ExtendedSimple,ExtendedSimpleWeighted,Simple,SimpleWeighted}
                        Which post scoring criteria to use. Simple scorers take a geometric mean of boosts and favs. Extended
                        scorers include reply counts in the geometric mean. Weighted scorers multiply the score by an inverse
                        square root of the author's followers, to reduce the influence of large accounts. (default:
                        SimpleWeighted)
  -t {lax,normal,strict}
                        Which post threshold criteria to use. lax = 90th percentile, normal = 95th percentile, strict = 98th
                        percentile (default: normal)
  -o OUTPUT_DIR         Output directory for the rendered digest (default: ./render/)
  --theme {light,default}
                        Named template theme with which to render the digest (default: default)

If you are running with Docker and make, you can pass flags as:

make run FLAGS="-n 8 -s ExtendedSimpleWeighted -t lax"

Algorithm Options

I'm still experimenting with these, so it's possible that I change the defaults in the future.

Theme Options

Specify a render template theme with the --theme <theme-name> argument.

Two basic templates for the digest are provided, default and light. You can create new templates by adding a directory to templates/themes/my-theme/. You must create index.html.jinja as the root template.

Template fragments placed inside themes/common/ can be re-used by any template, which is helpful to try and keep things DRY-er (for example, include scripts.html.jinja for the current version of the Mastodon iframe embed JavaScript.)

The available view variables are:

Each post and boost is a ScoredPost object:

When developing themes, you can run the digest in development mode, which uses theme files from the local filesystem rather than rebuilding the docker image every time you make a change:

make dev FLAGS="--theme my-theme"

A Matt Hodges project

This project is maintained by @MattHodges.

Please use it for good, not evil.