104 lines
7.6 KiB
Markdown
104 lines
7.6 KiB
Markdown
# fedi2html
|
||
|
||
|
||
|
||
|
||
[fedi2html](https://hak.xwx.moe/jadedctrl/fedi2html) is a shell script that renders posts from Fediverse/Mastodon/Pleroma/etc to text — for instance, HTML. It could be used for archiving posts, embedding comments into a webpage, etc; the latter is my use-case.
|
||
|
||
Inspired by the work of [Óscar Otero](https://github.com/oom-components/mastodon-comments), who was inspired by [Thiago Cerqueira](https://thiagojedi.github.io/blog/activitypub-comments/), who was inspired by [Julian Fietkau](https://fietkau.blog/2023/another_blog_resurrection_fediverse_new_comment_system), who was in turn inspired by [Cassidy James](https://cassidyjames.com/blog/fediverse-blog-comments-mastodon/), who also was inspired by [Jan Wildeboer](https://jan.wildeboer.net/2023/02/Jekyll-Mastodon-Comments/) who was inspired by [Yidhra Farm](https://yidhra.farm/tech/jekyll/2022/01/03/mastodon-comments-for-jekyll.html), who was inspired by [Joel Chrono](https://joelchrono12.xyz/blog/how-to-add-mastodon-comments-to-jekyll-blog/) who was inspired by [Carl Schwan](https://carlschwan.eu/2020/12/29/adding-comments-to-your-static-blog-with-mastodon/).
|
||
|
||
|
||
## Usage
|
||
fedi2html can take post URLs or user URLs. In the first case, it will render the post and, by default, all respones. If a user URL is given, it will by default render the user’s posts, responses, and repeats; and all responses to these.
|
||
|
||
```
|
||
$ echo '<html><head><link rel="stylesheet" href="style.css" type="text/css"/></head>' > out.html
|
||
$ fedi2html https://jam.xwx.moe/users/Tirifto >> out.html
|
||
$ fedi2html https://jam.xwx.moe/notice/AfJdu8YChrGdHXmOpM >> out.html
|
||
```
|
||
|
||
Of course, the output is by-default unstylized HTML, including no CSS; for best results, I’d recommend using the [style.css](style.css) file found in this directory, as is done above (by prepending its inclusion in a <link> tag).
|
||
|
||
### Arguments
|
||
There are six arguments you should be aware of:
|
||
|
||
| Flag | Description |
|
||
|----------|-----------------------------------------------|
|
||
| `-c` | Only print responses to the post(s). |
|
||
| `-I` | Display posts in reverse-chronological order. |
|
||
| `-l NUM` | Display at maximum NUM posts. |
|
||
| `-R` | Do not recursively fetch & display responses. |
|
||
|----------|-----------------------------------------------|
|
||
| `-b` | Exclude reblogs/repeats in user feeds. |
|
||
| `-B` | Exclude top-level replies in user feeds. |
|
||
| `-t TAG` | Only print posts of TAG in user feeds. |
|
||
|
||
|
||
### Templates
|
||
fedi2html doesn’t technically *have* to render posts as HTML, because you can specify the template it uses for printing posts, attachments, etc. For this, we use environment variables containing shell-style variables (dollar-sign followed by variable name).
|
||
|
||
There are four templates used: `$POST_TEMPLATE`, `$ATTACH_TEMPLATE`, `$ATTACH_IMAGE_TEMPLATE`, and `$IMAGE_TEMPLATE`. You can take a look at fedi2html’s first few lines to see the default values.
|
||
|
||
#### POST_TEMPLATE
|
||
`$POST_TEMPLATE` is for the overall post structure. It contains the post contents, all responses, and attachment data. The variables that can be specified inside of it are:
|
||
|
||
| Variable | Description |
|
||
|---------------------|------------------------------------------------|
|
||
| `$ACCOUNT_ID` | The poster’s user@host ID. |
|
||
| `$ACCOUNT_URL` | URL to the poster’s profile. |
|
||
| `$ACCOUNT_NAME` | Poster’s display name. |
|
||
| `$ACCOUNT_AVATAR` | URL to the poster’s avatar image. |
|
||
| `$POST_URL` | URL of the post. |
|
||
| `$POST_DATE` | Date the post was made. |
|
||
| `$POST_CONTENT` | HTML/text content of the post. |
|
||
| `$POST_ATTACHMENTS` | Attachments, as rendered from other templates. |
|
||
| `$POST_RESPONSES` | Reply posts, which will use this template. |
|
||
|
||
Keep in mind that posts are “recursive” — that`$POST_RESPONSES` will be substituted with other results of the `$POST_TEMPLATE`.
|
||
|
||
#### ATTACH_TEMPLATE
|
||
`$ATTACH_TEMPLATE` and `$ATTACH_IMAGE_TEMPLATE` determine how attachments will be rendered within a post. This template will be substituted into the `$POST_TEMPLATE`’s `$POST_ATTACHMENTS` variable. Variables available to these templates are:
|
||
|
||
| Variable | Description |
|
||
|-------------------|-----------------------------------------|
|
||
| `$ATTACH_URL` | URL to the attachment file. |
|
||
| `$ATTACH_NAME` | Name of the attached file. |
|
||
| `$ATTACH_TYPE` | Mime-type of the attachment file. |
|
||
| `$ATTACH_DESC` | Description/alt-text of the attachment. |
|
||
| `$ATTACH_PREVIEW` | “Preview” URL of the attachment. |
|
||
|
||
|
||
#### EMOJI_TEMPLATE
|
||
`$EMOJI_TEMPLATE` is used for rendering custom emojis; it appears in-line in post-contents, users’ display-names, etc. The variables that can be specified inside of it are:
|
||
|
||
| Variable | Description |
|
||
|--------------------|--------------------------------|
|
||
| `$EMOJI_SHORTCODE` | The corresponding shortcode. |
|
||
| `$EMOJI_URL` | URL to the emoji’s image file. |
|
||
|
||
|
||
## Installation
|
||
Installing fedi2html itself is simpler than simple — just copy it into your PATH!
|
||
|
||
Assuming that you use ~/.local/bin/:
|
||
```
|
||
$ PATH="$PATH:~/.local/bin/"
|
||
$ chmod +x fedi2html
|
||
$ cp fedi2html ~/.local/bin/
|
||
```
|
||
|
||
|
||
### Dependencies
|
||
However, fedi2html has some dependencies:
|
||
|
||
* [curl](https://curl.se/) — For fetching/downloading posts.
|
||
* [jq](https://jqlang.github.io/jq/) — For parsing the resultant JSON.
|
||
|
||
They are both fairly standard, and are generally accessible as packages `curl` and `jq`, respectively. In the rare cases they aren’t, both are written in C and are easily-compilable.
|
||
|
||
|
||
## Misc
|
||
Written by Jaidyn Ann <jadedctrl@posteo.at>
|
||
License is [GNU GPLv3](COPYING)
|
||
Source is at https://hak.xwx.moe/jadedctrl/fedi2html
|