fedi2html/README.md

# fedi2html

![Clipping from a screenshot of a webpage generated by fedi2html. It is showing a legibly-formatted post, containing its username, text, date, and three attachment images. The post is by Tirifto (@tirifto@jam.xwx.moe) with a custom emoji that resembles a “K” in his username. It was posted apparently at 14:12 on April 19th 2024, and says: “Antaŭ nelonge mi bakis spickukon! Domaĝe la supro iomete bruliĝis kaj mi devis senŝeligi ĝin. Sed almenaŭ tio donis bonan pretekston, kial mi nepre kovru la supron per kirlita kremo.” The message contains a custom emoji of a laughing blobcat. The hashtags are visible below as links: #lang\_eo, #bakado, #fotoj, #kuirado, #manĝaĵoj, #spickuko, kaj #vivo. The attachments are all images: “spickuko.jpg”, “spickukeroj.jpg”, and “peco.jpg”. They each have small alt-text descriptions that are truncated. There is a reply to this post, which is displayed as a box inside the responded post.](img/screenshot_attachments.png)
![Clipping from a screenshot of a webpage generated by fedi2html. A chain of three posts, each replying to the last, are visible. Each post is within a small box, containing the poster’s avatar, user-name, and text. Each response is found within a smaller box within the parent post, showing a clear hierarchy in the thread. Reid posts, mentioning jadedctrl, “but would you ask spicy questions?” jadedctrl responds, “I like using a lot of spice myself, but because of the high sodium content I couldn’t recommend a diet like that to other people on good conscious”. jadedctrl also responds with a custom emoji of a laughing blobcat. Reid responds to that response, “a life without spice is like GTA without crime: too damn boring”.](img/screenshot_comment.png)

[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 from a fediverse server.  
In the first case, it will render the post and, by default, all responses.  
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
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
+								# fedi2html
-												Add multi-attachment screenshot

											
										
										
											2024-04-25 21:37:58 -05:00
+								![Clipping from a screenshot of a webpage generated by fedi2html. It is showing a legibly-formatted post, containing its username, text, date, and three attachment images. The post is by Tirifto (@tirifto@jam.xwx.moe) with a custom emoji that resembles a “K” in his username. It was posted apparently at 14:12 on April 19th 2024, and says: “Antaŭ nelonge mi bakis spickukon! Domaĝe la supro iomete bruliĝis kaj mi devis senŝeligi ĝin. Sed almenaŭ tio donis bonan pretekston, kial mi nepre kovru la supron per kirlita kremo.” The message contains a custom emoji of a laughing blobcat. The hashtags are visible below as links: #lang\_eo, #bakado, #fotoj, #kuirado, #manĝaĵoj, #spickuko, kaj #vivo. The attachments are all images: “spickuko.jpg”, “spickukeroj.jpg”, and “peco.jpg”. They each have small alt-text descriptions that are truncated. There is a reply to this post, which is displayed as a box inside the responded post.](img/screenshot_attachments.png)
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
+								![Clipping from a screenshot of a webpage generated by fedi2html. A chain of three posts, each replying to the last, are visible. Each post is within a small box, containing the poster’s avatar, user-name, and text. Each response is found within a smaller box within the parent post, showing a clear hierarchy in the thread. Reid posts, mentioning jadedctrl, “but would you ask spicy questions?” jadedctrl responds, “I like using a lot of spice myself, but because of the high sodium content I couldn’t recommend a diet like that to other people on good conscious”. jadedctrl also responds with a custom emoji of a laughing blobcat. Reid responds to that response, “a life without spice is like GTA without crime: too damn boring”.](img/screenshot_comment.png)
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								[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.
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
 								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
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								fedi2html can take post URLs or user URLs from a fediverse server.
 								In the first case, it will render the post and, by default, all responses.
 								If a user URL is given, it will by default render the user’s posts, responses, and repeats; and all responses to these.
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
 								```
 								$ 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
 								```
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								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).
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								### Arguments
 								There are six arguments you should be aware of:
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
 								| 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. |
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								| `-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.        |
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								### 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. |
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
 								## Installation
-												Document templates’ use in README.md

											
										
										
											2024-04-25 22:03:04 -05:00
+								Installing fedi2html itself is simpler than simple — just copy it into your PATH!
-												Add README.md

											
										
										
											2024-04-25 18:41:25 -05:00
 								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