* Motivation

美化并预览 Org Mode 的链接。支持一些文件的缩略图，预览，等特性。

Usually Org links only have text, it's not very intuitive to recognize what type
of link it is. Add some color and icon, even image preview will help user read links.

* Intro

An Emacs extension which beautify Org Mode links with previewing.

* Screenshots

Annotate link with icon to indicate link type. And use color to indicate link file exist or not?

#+ATTR_ORG: :width 600
#+ATTR_LATEX: :width 6.0in
#+ATTR_HTML: :width 600px
[[file:screenshot.png]]

Supports video file link preview with thumbnail.

#+ATTR_ORG: :width 600
#+ATTR_LATEX: :width 6.0in
#+ATTR_HTML: :width 600px
[[file:video-thumbnail.png]]

* Features [20/24]

- [X] Only display org-link-beautify preview images (and icons) when headline
  expanded. This will reduce Emacs memory and improve performance!!!
- [X] support colorize links if file: target file does not exist
- [X] support display icons for link types (currently already supported many link types)
- [X] supported many different link types (If you found not supported link type, PR welcome!)
- [X] display image for previewing image file
- [X] display image for previewing PDF file and preview of specific PDF page number. Like this:

  #+begin_src org
  [[file:/path/to/filename.pdf]]
  #+end_src
  #+begin_src org
  [[pdfview:/path/to/filename.pdf::15]]
  #+end_src

  Currently support PDF link types:
  + =pdfview:=
  + =docview:=
  + =eaf:pdfviewer::=
  + =file:=
- [X] support image link preview
- [X] display thumbnail for video file link
  + [X] support Linux video thumbnail with "=ffmpegthumbnailer="
  + [X] support macOS video thumbnail with "=qlmanage="
  + [X] support all platforms with "=ffmpeg="
- [X] preview audio file link with wave form image
  + [X] support Linux audio thumbnail with "=audiowaveform="
  + [X] support macOS audio thumbnail with "=qlmanage="
- [X] preview ebooks, supports: epub, mobi, azw3, pdf etc.
- [X] preview CDisplay Archived Comic Book Formats (.cbr, .cbz, cb7, .cba etc) cover
- [X] add keymap on link text-property, available keybindings:
  + =[Enter]= :: =org-open-at-point=, so you can press =[Enter]= to open link.
    You can add more keybindings with following similar config:
    #+begin_src emacs-lisp :eval no
    (define-key org-link-beautify-keymap (kbd "RET") 'org-open-at-point)
    #+end_src
  + =[M-w]= :: copy file in link at point
  + =[M-q]= :: display QR code for link URL at point
- =[c]= :: =org-link-beautify-copy-file-to-clipboard=, copy the file at point link to system clipboard for pasting.
- [X] preview text files like .org, .markdown (.md), .txt, and source code files etc (customized with ~org-link-beautify-text-preview-list~).
- [X] preview archive files like .zip, .rar, .tar.gz, .tar.bz2, .7z etc.
- [ ] preview URL with screenshot on web page (Still considering whether should add this feature.)
- [ ] preview FictionBook2 (.fb2, .fb2.zip) covert image
- [ ] preview subtitle file with limited lines
- [X] display link filename over thumbnail to display more link information through Emacs overlay

* Install

** Requirements

- nerd-icons :: 

- video thumbnail feature needs package "=ffmpegthumbnailer="

  For Arch Linux:

  #+begin_src shell :dir /sudo:: :results none
  sudo pacman -S --noconfirm ffmpegthumbnailer
  #+end_src

  For macOS:

  #+begin_src shell
  brew install ffmpegthumbnailer
  #+end_src

- audio wave form image preview need package "=audiowaveform="

  Check out https://github.com/bbc/audiowaveform for installation guide.

- PDF file preview with command "=pdftocairo=" or "=pdf2svg="

  For Arch Linux:

  #+begin_src shell :dir /sudo:: :results none
  sudo pacman -S --noconfirm poppler # command pdftocairo
  sudo pacman -S --noconfirm pdf2svg # command pdf2svg
  #+end_src

  For macOS:

  #+begin_src shell
  brew install poppler pdf2svg
  #+end_src

- EPUB file cover image preview need command "=gnome-epub-thumbnailer="

  For Arch Linux:

  #+begin_src shell :dir /sudo:: :results none
  sudo pacman -S --noconfirm gnome-epub-thumbnailer
  #+end_src

  For macOS:

  https://github.com/marianosimone/epub-thumbnailer

- EPUB file cover image preview with "epub-thumbnailer.py" script requires PIL/Pillow.

  #+begin_src shell
  python  -m pip install Pillow
  python3 -m pip install Pillow
  #+end_src

** MELPA

* Usage

#+begin_src emacs-lisp
(org-link-beautify-mode 1) ; (ref:toggle org-link-beautify-mode)
#+end_src

* Performance

If you want better better performance. You can do bellowing options:

- Enable option ~org-link-beautify-async-preview~

  #+begin_src emacs-lisp
  (setq org-link-beautify-async-preview t)
  #+end_src

- You can toggle this option carefully to improve Org ~org-activate-links~ performance:

  #+begin_src emacs-lisp
  (setq org-element-use-cache t)
  #+end_src

* Link examples

*NOTE*: Because =all-the-icons= fonts has some issue on my system, so bellowing some
icons might not correctly displayed. And some links are not beautified because I
have not found suitable icons for them. And if file: link type source file is
not available, it will be colored. If you have any idea, PR welcome.

#+begin_src org
- file link [[file:babel-R.org][kkk]]
  + remote file
  + non-existing file
  + video thumbnail for video file link  [[file:~/Downloads/Neural Network Architectures-oJNHXPs0XDk.mkv]]
- raw link [[file:babel-clojure.org]]
- file+sys link [[file+sys:README.org]]
- file link smart recognize file types [[file:~/Downloads/8-个税政治成本最高 对社会公平毫无帮助\[李稻葵\].pdf]]
- directory link [[file:~/Downloads/][Downloads]]
- URL link (use different icons based on url with smart all-the-icons) [[https://www.google.com]]
- elisp link [[elisp:(print "hello, org-link-beautify!")]]
- shell link [[shell:echo "hi"]]
- eww link [[eww:https://www.baidu.com]]
- A mu4e link [[mu4e:msgid:87mu62hfq1.fsf@nicolasgoaziou.fr][Re: [Suggestion] add an API function for getting link description]]
- Git link [[git:/home/stardiviner/Code/Emacs/org-mode/lisp/org.el::master@{2017-06-24}::1]]
- orgit link
- orgit-rev link
- orgit-log link
- pdfview link [[pdfview:~/Downloads/社会网络 深度图查询.pdf]]
- grep link [[grep:org-link-beautify]]
- occur link [[occur:org-link-beautify]]
- man link [[man:grep]]
- info link [[info:emacs]]
- help link [[help:man]]
- rss link [[rss:https://www.gmail.com]]
- elfeed link [[elfeed:Today's news]]
- telnet link
- wikipedia link [[wikipedia:Linux]]
- mailto link [[mailto:numbchild@gmail.com]]
- doi link [[doi:what?]]
- EAF link [[eaf:pdf-viewer::/home/stardiviner/Org/Wiki/Computer Technology/Programming/Programming Languages/Database/SQL/PostgresQL/Data/Books/PostgreSQL即学即用中文第2版.pdf::46][PostgreSQL即学即用中文第2版.pdf]]
#+end_src

* FAQ

*NOTE*: This Emacs package icons use "[[https://github.com/domtronn/all-the-icons.el][all-the-icons]]". If you got icon problem. You
need to make sure all-the-icons and fonts installed correctly.

** Q: Some link types are not beautified by org-link-beautify?

This is because =org-link-beautify= finished loading before that package register link type. This
depend on your Emacs config init file the order or loading packages.

Solution: make sure =org-link-beautify= is loaded at the end of all packages. You can config like this:

#+begin_src emacs-lisp
(add-hook 'after-init-hook #'org-link-beautify-mode)
#+end_src

* Contributions

- Thanks to John Kitchin and Nicolas Goaziou help in Org Mode mailing list.
- And [[https://emacs-china.org/t/icon-org-mode/13147][yuchen-lea's screenshot]] gives me design idea
- pdf file link preview inspired from [[https://github.com/shg/org-inline-pdf.el][org-inline-pdf.el]]