* mastodon.el [[https://melpa.org/#/mastodon][file:https://melpa.org/packages/mastodon-badge.svg]] [[https://travis-ci.org/jdenen/mastodon.el][https://travis-ci.org/jdenen/mastodon.el.svg?branch=master]] [[http://waffle.io/jdenen/mastodon.el][https://badge.waffle.io/jdenen/mastodon.el.png?label=in%20progress&title=In%20Progress]] Emacs client for [[https://github.com/tootsuite/mastodon][Mastodon]] [[http://spacemacs.org][https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]] ** 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 :load-path "/path/to/mastodon.el/lisp") #+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--init)) #+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 | |--------------------------+-----------------------------------------------------------------------------------| | | /In-buffer navigation/ | | == | Scroll up (i.e. move down to older items) | | == | Scroll down (i.e. move up to newer items) | | =<= | Move to beginning of buffer | | =>= | Move to end of buffer | | =j= | Go to next item (toot, notification) | | =k= | Go to previous item (toot, notification) | | == / =h= | Go to the next interesting thing that has an action | | == / =l= | Go to the previous interesting thing that has an action | | | /In-buffer actions/ | | =?= | Open context menu (if =discover= is available) | | =c= | Toggle the visibility of sensitive text (if there is text with a content warning) | | =b= | Boost toot under =point= | | =f= | Favourite toot under =point= | | =r= | Reply to toot under =point= | | == / == | Perform action for the thing under point (or under mouse for ==) if any | | =n= | Compose a new toot | | | /Switching to other buffers/ | | =A= | Open author profile of toot under =point= | | =N= | Open buffer with notifications | | =F= | Open federated timeline | | =H= | Open home timeline | | =L= | Open local timeline | | =N= | Open notifications timeline | | =t= | Open thread buffer for toot under =point= | | =T= | Prompt for tag and open its timeline | | =U= | Open profile of user attached to toot under =point= | | | /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 | |-----------+------------------------| >>>>>>> Make default visibility customizable; add documentation. ** 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]].