jdenen / Mastodon.el

• 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 :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]].