aboutsummaryrefslogblamecommitdiff
path: root/README.org
blob: baa627e4b64acfcf0c9003ebb4d639ad416a7da3 (plain) (tree)
1
2
3
4
5
6
7
8
9
             
 
                                                                                    
                                                                                                        
                                                                                                                               
 
                                                                    
 
                                                                                                                                       








                                                                   
                       
 
                      
                       
              
         
         
 











                                                           
 



                                                                                                                                   
            
                                                                                                                          
                              
 


                                                                         
                                                      
         






                        
 
        
                 
                                                                                                                            
 
                                                                                                             






                                                                                                                   


                                                                                                                                                


              
                                                                                                                                                                                                                                                    
                
 




























                                                                             
 
           




                                    
 



                                                                     
                                                                        
                                        
                                                                       
                                                                                     
 
                                                                     
                                            
 


                                                                                                                                                                                           
 
                






                                      
 
          
                                                                                                                                     
 
                                                                                                         





                                                   

                                                                                                             

         

                                                                                                            


                                                                                                                                                              
* 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=/=<tab>=   | 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]].