mastodon.el

mastodon.el copied to clipboard

#+OPTIONS: toc:nil

• mastodon.el updated

This is an updated version of the great but seemingly dormant mastodon client for emacs.

[The original readme is below.]

It adds the following features:

| Profiles: | | | | display profile metadata fields | | | display pinned toots first | | | display relationship (follows you/followed by you) | | | display toots/follows/followers counts | | | links/tags/mentions in profile bios are active links | | | show a lock icon for locked accounts | | =R=, =C-c a=, =C-c r= | view/accept/reject follow requests | | =V= | view your favorited toots | | =i= | toggle pinning of toots | | =S-C-P= | jump to your profile | | =U= | update your profile bio note | | =O= | jump to own profile | | Notifications: | | | | follow requests now also appear in notifications | | =a=, =r= | accept/reject follow request | | | notifications for when a user posts (=mastodon-tl--enable-notify-user-posts=) | | Timelines: | | | =C= | copy url of toot at point | | =d= | delete your toot at point, and reload current timeline | | =D= | delete and redraft toot at point, preserving reply/CW/visibility | | =W=, =M=, =B= | (un)follow, (un)mute, (un)block author of toot at point | | =k=, =K= | toggle bookmark of toot at point, view bookmarked toots | | | display polls and vote on them | | | images are links to the full image, can be zoomed/rotated/saved (see image keymap) | | | images scale properly | | | toot visibility (direct, followers only) icon appears in toot bylines | | | display toot's number of favorites, boosts and replies | | | customize option to cache images | | Toots: | | | | mention booster in replies by default | | | replies preserve visibility status/CW of original toot | | | autocompletion of user mentions, via =company-mode= (must be installed to work) | | =C-c C-a= | media uploads, asynchronous | | | media upload previews displayed in toot compose buffer | | =C-c C-n= | and sensitive media/nsfw flag | | =C-c C-e= | add emoji (if =emojify= installed) | | | download and use your instance's custom emoji | | | server's maximum toot length shown in toot compose buffer | | Search: | | | =S= | search (posts, users, tags) (NB: only posts you have interacted with are searched) | | | |

It also makes some small cosmetic changes to make timelines easier to read, and makes some functions asynchronous, based on https://github.com/ieure/mastodon.el.

The minimum Emacs version is now 27.1. But if you are running an older version it shouldn't be very hard to get it working.

** live-updating timelines: =mastodon-async-mode=

(code taken from https://github.com/alexjgriffith/mastodon-future.el.)

Works for federated, local, and home timelines and for notifications. It's a little touchy, one thing to avoid is trying to load a timeline more than once at a time. It can go off the rails a bit, but it's still pretty cool.

To enable, it, add =(require 'mastodon-async)= to your =init.el=. Then you can view a timeline with one of the commands that begin with =mastodon-async--stream-=.

** NB: dependencies

This version depends on the library =request= (for uploading attachments). You can install it from MELPA, or https://github.com/tkf/emacs-request. It also depends on =seq=.

Optional dependencies are =company= for autocompletion of mentions when composing a toot, and =emojify= for inserting and viewing emojis.

** NB: bugs

This repo also incorporates fixes for two bugs that were never merged into the upstream repo:

• https://github.com/jdenen/mastodon.el/issues/227 (and https://github.com/jdenen/mastodon.el/issues/234)
• https://github.com/jdenen/mastodon.el/issues/228

** 2FA

It looks like 2-factor auth was never completed in the original repo. It's not a priority for me, auth ain't my thing. If you want to hack on it, its on the develop branch in the original repo.

** contributing

Contributions are welcome. Registration is disabled by default on the gitea instance, but if you are interested, get in touch with me on mastodon: [[https://todon.nl/@mousebot][@[email protected]]]. Or just leave an issue on github.

For now, to get started with hacking, pull off the develop branch of the blast repo.

• Original README

** Installation

Clone this repository and add the lisp directory to your load path. Then, require it and go.

#+BEGIN_SRC emacs-lisp (add-to-list 'load-path "/path/to/mastodon.el/lisp") (require 'mastodon) #+END_SRC

Or, with =use-package=:

#+BEGIN_SRC emacs-lisp (use-package mastodon :ensure t) #+END_SRC

*** MELPA

Add =MELPA= to your archives:

#+BEGIN_SRC emacs-lisp (require 'package) (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/") t) #+END_SRC

Update and install:

=M-x package-refresh-contents RET=

=M-x package-install RET mastodon RET=

*** Emoji

=mastodon-mode= will enable [[https://github.com/iqbalansari/emacs-emojify][Emojify]] if it is loaded in your Emacs environment, so there's no need to write your own hook anymore. =emojify-mode= is not required.

*** Discover

=mastodon-mode= can provide a context menu for its keybindings if [[https://github.com/mickeynp/discover.el][Discover]] is installed. It is not required.

if you have Discover, add the following to your Emacs init configuration:

#+BEGIN_SRC emacs-lisp (require 'mastodon-discover) (with-eval-after-load 'mastodon (mastodon-discover)) #+END_SRC

Or, with =use-package=:

#+BEGIN_SRC emacs-lisp (use-package mastodon :ensure t :config (mastodon-discover)) #+END_SRC

** Usage *** 2 Factor Auth 2FA is not supported yet. It is in the [[https://github.com/jdenen/mastodon.el/milestone/2][plans]] for the =1.0.0= release.

If you have 2FA enabled and try to use mastodon.el, your Emacs client will hang until you C-g your way out. *** Instance

Set =mastodon-instance-url= in your =.emacs= or =customize=. Defaults to the [[https://mastodon.social][flagship]].

#+BEGIN_SRC emacs-lisp (setq mastodon-instance-url "https://my.instance.url") #+END_SRC

There is an option to have your user credentials (email address and password) saved to disk so you don't have to re-enter them on every restart. The default is not to do this because if not properly configured it would save these unencrypted which is not a good default to have. Customize the variable =mastodon-auth-source-file= if you want to enable this feature.

*** Timelines

=M-x mastodon=

Opens a =mastodon-home= buffer in the major mode so you can see toots. You will be prompted for email and password. The app registration process will take place if your =mastodon-token-file= does not contain =:client_id= and =:client_secret=.

**** Keybindings

|-----------------+---------------------------------------------------------| | Key | Action | |-----------------+---------------------------------------------------------| | | /Help/ | | =?= | Open context menu if =discover= is available | | | /Timeline actions/ | | =n= | Go to next item (toot, notification) | | =p= | Go to previous item (toot, notification) | | =M-n=/== | Go to the next interesting thing that has an action | | =M-p=/=<S-tab>= | Go to the previous interesting thing that has an action | | =u= | Update timeline | | =#= | Prompt for tag and open its timeline | | =A= | Open author profile of toot under =point= | | =F= | Open federated timeline | | =H= | Open home timeline | | =L= | Open local timeline | | =N= | Open notifications timeline | | =P= | Open profile of user attached to toot under =point= | | =T= | Open thread buffer for toot under =point= | | | /Toot actions/ | | =c= | Toggle content warning content | | =b= | Boost toot under =point= | | =f= | Favourite toot under =point= | | =r= | Reply to toot under =point= | | =n= | Compose a new toot | | | /Switching to other buffers/ | | | /Quitting/ | | =q= | Quit mastodon buffer, leave window open | | =Q= | Quit mastodon buffer and kill window | |-----------------+---------------------------------------------------------|

**** Legend

|--------+-------------------------| | Marker | Meaning | |--------+-------------------------| | =(B)= | I boosted this toot. | | =(F)= | I favourited this toot. | |--------+-------------------------|

*** Toot toot

=M-x mastodon-toot=

Pops a new buffer/window with a =mastodon-toot= minor mode. Enter the contents of your toot here. =C-c C-c= sends the toot. =C-c C-k= cancels. Both actions kill the buffer and window.

If you have not previously authenticated, you will be prompted for your account email and password. NOTE: Email and password are NOT stored by mastodon.el.

Authentication stores your access token in the =mastodon-auth--token= variable. It is not stored on your filesystem, so you will have to re-authenticate when you close/reopen Emacs.

**** Customization The default toot visibility can be changed by setting or customizing the =mastodon-toot--default-visibility= variable. Valid values are ="public"=, ="unlisted"=, ="private"=, or =direct=.

Toot visibility can also be changed on a per-toot basis from the new toot buffer.

**** Keybindings

|-----------+------------------------| | Key | Action | |-----------+------------------------| | =C-c C-c= | Send toot | | =C-c C-k= | Cancel toot | | =C-c C-w= | Add content warning | | =C-c C-v= | Change toot visibility | |-----------+------------------------|

** Roadmap

[[https://github.com/jdenen/mastodon.el/milestone/1][Here]] are the features I plan to implement before putting mastodon.el on MELPA.

[[https://github.com/jdenen/mastodon.el/milestone/2][Here]] are the plans I have for the =1.0.0= release.

** Contributing

PRs, issues, and feature requests are very welcome!

*** Features

1. Create an [[https://github.com/jdenen/mastodon.el/issues][issue]] detailing the feature you'd like to add.
2. Fork the repository and create a branch off of =develop=.
3. Create a pull request referencing the issue created in step 1.

*** Fixes

1. In an [[https://github.com/jdenen/mastodon.el/issues][issue]], let me know that you're working to fix it.
2. Fork the repository and create a branch off of =develop=.
3. Create a pull request referencing the issue from step 1.

** Connect

If you want to get in touch with me, give me a [[https://mastodon.social/@johnson][toot]] or leave an [[https://github.com/jdenen/mastodon.el/issues][issue]].