#+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=, =a=, =r= | view/accept/reject follow requests | | =I=, =c=, =d= | view/create/delete filters | | =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 | | =G= | view follow suggestions | | | play gifs and videos (requires =mpv= to be installed) | | | 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! 1. Create an here on codeberg 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. * 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=/== | 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]].