Skip to content

Commit

Permalink
make it look a little better, improve the description
Browse files Browse the repository at this point in the history
  • Loading branch information
mauforonda committed Dec 22, 2022
1 parent 82aeddf commit 19e1cc6
Show file tree
Hide file tree
Showing 8 changed files with 258 additions and 185 deletions.
132 changes: 18 additions & 114 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,90 +1,30 @@
A fork of [hodgesmr/mastodon_digest](https://github.com/hodgesmr/mastodon_digest) that

[**see live** 🎉](https://mauforonda.github.io/mastodon_digest/)

# Mastodon Digest

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 Options](#command-options)).
- runs on github actions
- renders mastodon posts without iframes
- in a clean and responsive style

![Mastodon Digest](howitlooks.png)

## Run

You can run in [Docker](#docker) or in a [local python environment](#local). But first, set up your environment:

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

```sh
cp .env.example .env
```

- `MASTODON_TOKEN` : This is your access token. You can generate one on your home instance under Preferences > Development. Your token only needs Read permissions.
- `MASTODON_BASE_URL` : This is the protocol-aware URL of your Mastodon home instance. For example, if you are `@[email protected]`, then you would set `https://mastodon.social`.
- `MASTODON_USERNAME`: This is your Mastodon account username on your home instance. For example, if you are `@[email protected]`, then you would set `Gargron`.

### Docker

First, build the image:

```sh
make build
```

Then you can generate and open a digest:

```sh
make run
```

You can also pass [command arguments](#command-arguments):

```sh
make run FLAGS="-n 8 -s Simple -t lax"
```

### Local

First, make sure you've set your environment variables:

```sh
set -a
source .env
set +a
```

From within your Python3 environment, simply:

```sh
pip install -r requirements.txt
```

You can immediately generate a Mastodon Digest with:

```sh
python run.py
```

The digest is written to `render/index.html` by default. You can then view it with the browser of your choice.

[**see live** 🎉](https://mauforonda.github.io/mastodon_digest/)

## Command arguments
---

A number of command arguments are available to adjust the algorithm. You can see the command arguments by passing the `-h` flag:
> **Mastodon Digest** scans posts you haven't yet seen in your timeline, finds the most popular ones and shows them to you in a pretty page.
```sh
python run.py -h
```
## To run your own

1. Fork this repository
2. Create repository secrets (`Settings``Secrets/Actions``New repository secrets`) for:
- `MASTODON_BASE_URL`: the url of your instance, like `https://mastodon.social`
- `MASTODON_USERNAME`: your user name, like `Gargron`
- `MASTODON_TOKEN`: a token you request in your instance settings under `Preferences``Development`
3. Adjust the [github workflow](.github/workflows/update.yml) however you want
- edit `cron` to define how often you want the digest to run
- edit the command `python run.py -n 12 -s SimpleWeighted -t lax` with your own preferences for:
```
usage: mastodon_digest [-h]
[-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]
options:
-h, --help show this help message and exit
-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)
The number of hours to consider (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
Expand All @@ -94,41 +34,5 @@ options:
-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/)
```

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

```sh
make run FLAGS="-n 8 -s Simple -t lax"
```

#### Algorithm Options
* `-n` : Number of hours to look back when building your digest. This can be an integer from 1 to 24. Defaults to **12**. I've found that 12 works will in the morning and 8 works well in the evening.
* `-s` : Scoring method to use. **SimpleWeighted** is the default.
- `Simple` : Each post is scored with a modified [geometric mean](https://en.wikipedia.org/wiki/Geometric_mean) of its number of boosts and its number of favorites.
- `SimpleWeighted` : The same as `Simple`, but every score is multiplied by the inverse of the square root of the author's follower count. Therefore, authors with very large audiences will need to meet higher boost and favorite numbers. **This is the default scorer**.
- `ExtendedSimple` : Each post is scored with a modified [geometric mean](https://en.wikipedia.org/wiki/Geometric_mean) of its number of boosts, its number of favorites, and its number of replies.
- `ExtendedSimpleWeighted` : The same as `ExtendedSimple`, but every score is multiplied by the inverse of the square root of the author's follower count. Therefore, authors with very large audiences will need to meet higher boost and favorite numbers.
* `-t` : Threshold for scores to include. **normal** is the default
- `lax` : Posts must achieve a score within the 90th percentile.
- `normal` : Posts must achieve a score within the 95th percentile. **This is the default threshold**.
- `strict` : Posts must achive a score within the 98th percentile.

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

## What's missing?

Probably many things!

You likely noticed that this repository has no tests. That's because I'm still treating this as a toy and not work. But tests might be good!

I'm still thinking about the best structure / process / whatever to incorporate new interesting algorithms. Maybe I'll devote time to that, maybe not.

I've tested this on my Intel and M1 macOS machines. I believe it'll work on other architectures and operating systems, but I haven't tried. The availability of a GUI web browser is important.

## A Matt Hodges project

This project is maintained by [@MattHodges](https://mastodon.social/@MattHodges).

_Please use it for good, not evil._
4. Enable github actions under `Settings``Actions/General`, run the action from the `Actions` tab and when it succeeds publish your digest by going to `Settings``Pages` and selecting to deploy from the `root` of the `gh-pages` branch.
3 changes: 2 additions & 1 deletion formatters.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ def format_displayname(display_name, emojis):
username = post.data['account']['username']
content = post.data['content']
media = "\n".join([format_media(media) for media in post.data.media_attachments])
created_at = post.data['created_at'].strftime('%B %d, %Y at %H:%M')
# created_at = post.data['created_at'].strftime('%B %d, %Y at %H:%M')
created_at = post.data['created_at'].isoformat()
home_link = f'<a href="{post.get_home_url(mastodon_base_url)}" target="_blank">home</a>'
original_link = f'<a href="{post.data.url}" target="_blank">original</a>'
replies_count = post.data['replies_count']
Expand Down
Binary file modified howitlooks.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 19e1cc6

Please sign in to comment.