yankee.el

Yankee extends copy-as-format to provide a function for yanking source blocks in Emacs with helpful annotations to help readers gain more context:

• yankee-yank

These are especially useful when composing issues and pull/merge requests on GitHub / GitLab / Bitbucket, but have broader utility as well. See the full list of supported formats (and how to add your own) at ~copy-as-format~.

If the yanked region is in a project, its path relative to the project root will be used to annotate the code block with a comment that including the selected line numbers.

If not in a project, an abbreviated absolute path will be included instead.

Additionally, if the buffer being yanked from is backed by a file under version control, a commit ref will be included.

GitHub-flavored Markdown

```emacs-lisp
;; yankee.el L158-L163 (ea278931)

(defun yankee/current-commit-ref ()
  "The current commit's SHA, if under version control.
Currently only supports Git."
  (if (equal 'Git (vc-backend (buffer-file-name)))
      (substring (shell-command-to-string "git rev-parse HEAD") 0 8)
    nil))
```
<sup>
  <a href="https://github.com/jmromer/yankee.el/blob/ea278931/yankee.el#L158-L163">
    yankee.el#L158-L163 (ea278931)
  </a>
</sup>

which produces this output:

GitHub-flavored Markdown (foldable)

(The summary line is customizable at runtime)

<details>
<summary>yankee/current-commit-ref</summary>

```emacs-lisp
;; yankee.el L158-L163 (ea278931)

(defun yankee/current-commit-ref ()
  "The current commit's SHA, if under version control.
Currently only supports Git."
  (if (equal 'Git (vc-backend (buffer-file-name)))
      (substring (shell-command-to-string "git rev-parse HEAD") 0 8)
    nil))
```
<sup>
  <a href=https://github.com/jmromer/yankee.el/blob/ea278931/yankee.el#L158-L163">
    yankee.el#L158-L163 (ea278931)
  </a>
</sup>
</details>

which produces this output:

Org mode

NB: The `BEGIN_SRC` tag is intentionally broken here for display purposes.

#+BEGIN SRC emacs-lisp
;; yankee.el L158-L163 (517300b3)

(defun yankee/current-commit-ref ()
  "The current commit's SHA, if under version control.
Currently only supports Git."
  (if (equal 'Git (vc-backend (buffer-file-name)))
      (substring (shell-command-to-string "git rev-parse HEAD") 0 8)
    nil))
#+END SRC
[[https://github.com/jmromer/yankee.el/blob/517300b3/yankee.el#L158-L163][yankee.el#L158-L163 (517300b3)]]

which produces this output:

;; yankee.el L158-L163 (517300b3)

(defun yankee/current-commit-ref ()
  "The current commit's SHA, if under version control.
Currently only supports Git."
  (if (equal 'Git (vc-backend (buffer-file-name)))
      (substring (shell-command-to-string "git rev-parse HEAD") 0 8)
    nil))

yankee.el#L158-L163 (517300b3)

Jira

{code:python}
# testproj/articles/models.py L4-L9 (ee46f59fb1)

class Article(models.Model):
    title = models.CharField(help_text="title model help_text", max_length=255, blank=False, unique=True)
    body = models.TextField(help_text="article model help_text", max_length=5000, blank=False)
    slug = models.SlugField(help_text="slug model help_text", unique=True, blank=True)
    date_created = models.DateTimeField(auto_now_add=True)
    date_modified = models.DateTimeField(auto_now=True)
{code}

[testproj/articles/models.py#L4-L9 (ee46f59fb1)|https://github.com/axnsan12/drf-yasg/blob/ee46f59fb1/testproj/articles/models.py#L4-L9]

which renders as follows:

Demo

(Click to view animated)

Installation

To install, load yankee.el and require yankee (the following assumes the project’s parent directory has been added to the load-path):

;; ~/spacemacs.d/init.el
(require 'yankee)

Suggested keybindings for evil-mode

Spacemacs and Evil-mode users may find the following key bindings intuitive:

;; ~/spacemacs.d/init.el
(define-key evil-visual-state-map (kbd "g y") #'yankee/yank)