Add README.md

This commit is contained in:
Jaidyn Ann 2024-04-25 18:41:25 -05:00
parent a342c5d0d6
commit 6b8000ab5b

63
README.md Normal file
View File

@ -0,0 +1,63 @@
# fedi2html
![Clipping from a screenshot of a webpage generated by fedi2html. It is showing a legibly-formatted post, containing the username, text, date, and an attachement plus thumnail. The post is by “jadedctrl”, posted apparently at 14:19 on April 15th 2024, and says: “Kaj nun miaj tagoplanoj presiĝos per punkpresilo! ^^”. The below hashtags are visible as links: #presilo, #planado, and #kalendaro. The attachment is an image called “kalendaro.jpg”, whose thumbnail is visible. Also visible is some of the images alt-text, reading “Foto de presita papero, sur kiu videblas du kolumnojn…”](img/screenshot_attachment.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 posters 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 couldnt 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 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 users 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 unstylized HTML, including no CSS; for best results, Id recommend using the [style.css](style.css) file found in this directory, as is done above (by prepending its inclusion in a <link> tag).
There are three general 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. |
… and three arguments relating specifically to user feeds:
| Flag | Description |
|----------|----------------------------|
| `-b` | Exclude reblogs/repeats. |
| `-B` | Exclude top-level replies. |
| `-t TAG` | Only print posts of TAG. |
## Installation
Installing fedi2html itself than simple — just copy 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 arent, 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