* mastodon.el 

[[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

*** use-package

#+BEGIN_SRC emacs-lisp
  (use-package mastodon
    :load-path "/path/to/mastodon.el/lisp")
#+END_SRC

*** MELPA
I'll make mastdon.el available on MELPA when I feel like it's reached a
stable state.

*** Discover

=mastodon-mode= will provide a context menu for its keybindings if =discover=
is installed. It is not required.

** Usage

*** 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

*** App registration

=M-x mastodon-register=

Retrieves =client_id= and =client_secret= tokens. They're stored in the =mastdon-token-file=.
This value can be customized too, and defaults to
=${EMACS_HOME_DIRECTORY}/mastodon.plstore=.

*** Timelines

=M-x mastodon=

Opens a =*mastodon-home*= buffer in the major mode so you can see toots.

**** Keybindings

|-----+------------------------------------------------|
| Key | Action                                         |
|-----+------------------------------------------------|
| =?= | Open context menu (if =discover= is available) |
| =b= | Boost toot under =point=                       |
| =f= | Favourite toot under =point=                   |
| =F= | Open federated timeline                        |
| =H= | Open home timeline                             |
| =j= | Go to next toot                                |
| =k= | Go to previous toot                            |
| =L= | Open local timeline                            |
| =n= | Switch to =mastodon-toot= buffer               |
| =q= | Quit mastodon buffer. Leave window open.       |
| =Q= | Quit mastodon buffer and kill window.          |
| =r= | Reply to toot under =point=.                   |
| =t= | Open thread buffer for toot under =point=.     |
| =T= | Prompt for tag and open its timeline           |
|-----+------------------------------------------------|

**** 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--api-token-string= variable. It is not stored on your
filesystem, so
you will have to re-authenticate when you close/reopen Emacs.

** Enabling Emojis
By default no emojis will appear in any of the posts or user names. In order to enable emojis you can install the `emojify` package.

Add [[http://melpa.org/#/emojify][MELPA]] to your list of package archives
#+BEGIN_SRC elisp
(require 'package)
(add-to-list 'package-archives ("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
#+END_SRC

Update the contents of your package archive and download `emojify`

This only needs to be called once. i.e. you should not put it in your `.emacs` or `init.el` file.
#+BEGIN_SRC elisp
(package-refresh-contents)
(package-install 'emojify)
#+END_SRC

If you would rather install `emojify` interactively you can do so by doing the following.

Refresh the package index
#+BEGIN_QUOTE
M-x package-refresh-contents RET
#+END_QUOTE

And then install it by doing
#+BEGIN_QUOTE
M-x package-install RET emojify
#+END_QUOTE

Once installed you can define a hook for `mastodon-mode` that call  `emojify-mode`
#+BEGIN_SRC elisp
(require 'emojify)
(defun my-mastodon-hook-function ()
  (emojify-mode 't))
(add-hook 'mastodon-mode-hook 'my-mastodon-hook-function)
#+END_SRC


** 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. I'll give you a thumbs up and assign you the issue.
3. Fork the repository and create a branch.
4. 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. I'll assign you the issue.
3. Fork the repository and create a branch.
4. 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]].