README.org

yankpad.el

Blog post about Yankpad

Let’s say that you have text snippets that you want to paste, but that yasnippet or skeleton is a bit too much when you do not need a shortcut/abbrev for your snippet. You like org-mode, so why not write your snippets there? Introducing the yankpad:

* Category 1

** Snippet title

    Here's a text snippet I want to insert.

** Snippet with keybinding                               :last:tag:is:key:o:

    And here's another snippet. This snippet has tags, and the last of these
    tags should be a key. This will bind the snippet to the key (in this case
    "o") when first calling yankpad-map.

** expandword: Snippet with keyword expansion

    This snippet has a keyword; "expandword" in this case. If this category is
    active, and you type the keyword into a buffer and use the "yankpad-expand"
    command, the keyword will be replaced with this snippet.

* Category 2

** Explaining categories

    This snippet belongs to another category. Categories are useful if you need
    several yankpads, for instance if you're a teacher (like me) working with
    different courses.

** yasnippet magic

    If you have yasnippet installed (not a requirement), the content in each snippet
    is actually executed by yasnippet! This means that you could run elisp
    inside your snippets: `(+ 3 4)` and have handy tab stop fields.

    | Student | Grade |
    |---------+-------|
    | $1      | $2    |

    That's pretty handy!
    $0

** "Litterate programming" snippet                     :src:

    Tagging a snippet with src says that only the content of source blocks
    should be expanded. All other text (like this paragraph) is ignored.

    #+BEGIN_SRC emacs-lisp
    (message "This is part of the snippet")
    #+END_SRC

    If you have several source blocks, their content will be concatenated.

    #+BEGIN_SRC emacs-lisp
    (message "This is also part of the snippet!!!")
    #+END_SRC

** The source block below will be executed if tag is func :func:
    #+BEGIN_SRC emacs-lisp
    ;; Instead of a src-block, the snippet may be named
    ;; the same as an emacs-lisp function. This will then
    ;; be executed without arguments (see next example).
    (elfeed)
    #+END_SRC

** elfeed                                            :func:e:

* Kitchen sink category
:PROPERTIES:
:INCLUDE:  Category 1|Category 2
:END:

** Include other categories

Snippets from Category 1 and Category 2 will be appended to this category.
This is done by setting the INCLUDE property of the category. Categories
are separated by a pipe.

* org-mode

** Major-mode categories

    If you have a category with the same name as a major-mode, that category will be
    activated when switching major-mode. This only affects the local buffer and does
    not modify the global category.

* my-projectile-project

** Projectile based categories

    If you have projectile installed (not a requirement) you can give a category the
    same name as one of your projectile projects. That category will be activated
    when using projectile-find-file on a file in the project.

Setup

1. Install yankpad from Melpa, or download yankpad.el and add it to your load-path and require it.
2. The default location for the yankpad file is yankpad.org in your org-directory. This can be changed by modifying the yankpad-file variable.
3. Optionally bind yankpad-map, yankpad-insert, and/or yankpad-expand to a key.
4. Optionally install yasnippet and/or projectile and/or company-mode, if you want the additional yankpad features that those package provide.
5. That’s it!

If you want different heading levels for the categories (default 1) or snippets (default 2), change the value of yankpad-category-heading-level and/or yankpad-snippet-heading-level.

By default keywords are defined by a word at the start of a snippet title, followed by a colon (:). You can change : into another string by changing the yankpad-expand-separator variable.

Here’s an example setup using the excellent use-package:

(use-package yankpad
  :ensure t
  :defer 10
  :init
  (setq yankpad-file "~/yankpad.org")
  :config
  (bind-key "<f7>" 'yankpad-map)
  (bind-key "<f12>" 'yankpad-expand)
  ;; If you want to complete snippets using company-mode
  (add-to-list 'company-backends #'company-yankpad)
  ;; If you want to expand snippets with hippie-expand
  (add-to-list 'hippie-expand-try-functions-list #'yankpad-expand))

Usage

1. Add snippet entries to your yankpad-file. Level 1 headings are categories and level 2 headings are snippets (by default). A quick way to open your yankpad-file is to use M-x yankpad-edit. You can also add snippets to the current yankpad-category by using M-x yankpad-capture.
2. Insert a snippet with M-x yankpad-insert. If the snippet has a keyword (it starts with a word followed by a colon), you can write that keyword into the buffer and use M-x yankpad-expand instead. It may be useful to bind these commands to some key on your keyboard. You can also use company-yankpad to expand a snippet using company-mode (thanks sid-kurias for contributing). If you want to insert the last snippet again, you can use M-x yankpad-repeat (bind that to a key if you’re using it frequently).
3. If you want to change category, use M-x yankpad-set-category. If you have a category with the same name as a major-mode (for instance org-mode), that category will be locally set when switching major-mode. In the same manner you can name a category to one of your Projectile project names (if Projectile is installed). If both cases are true, the Projectile category becomes active, but the snippets from the major mode are appended as well. If you later change category with M-x yankpad-set-category, the major-mode and project snippets will be appended to the chosen category.
4. If you want to append snippets from another of your categories (basically like having two or more categories active at the same time), use M-x yankpad-append-category. If you want one of your categories to always include snippets from another category; set the INCLUDE property of the category heading (several categories can be included this way, by separating them with |, see example at the top of this readme).
5. To quickly open your yankpad-file for editing, run M-x yankpad-edit.
6. Yankpad caches your snippets, making it a bit snappier to insert snippets from the yankpad. If you’ve edited your yankpad-file you might want to use M-x yankpad-reload to clear the snippet cache and reload your snippets in the current category.

Since a * at the beginning of a line would specify a new heading, lines can not begin with *. However, you can write \* at the beginning of a line, which will be replaced by a * when expanding the snippet. If you use this in order to yank snippets into an org-mode buffer, the new headings will be automatically indented – depending on the current level – by default. This can be changed by setting the variable yankpad-respect-current-org-level to nil.

Sometimes it may be useful to set the category automatically for a specific file. In this case you can add yankpad-category as a file variable, for instance by adding this line at the top of your file:

-*- yankpad-category: "Category name"; -*-

You can also set the yankpad-category to nil in this way, if you do not want any default category triggered for that file.

Special tags

Snippets in your Yankpad can have tags, and some of these have special meanings:

Changelog