README.org

   1 * Motivation
   2
   3 美化并预览 Org Mode 的链接。支持一些文件的缩略图，预览，等特性。
   4
   5 Usually Org links only have text, it's not very intuitive to recognize what type
   6 of link it is. Add some color and icon, even image preview will help user read links.
   7
   8 * Intro
   9
  10 An Emacs extension which beautify Org Mode links with previewing.
  11
  12 * Screenshots
  13
  14 Annotate link with icon to indicate link type. And use color to indicate link file exist or not?
  15
  16 #+ATTR_ORG: :width 600
  17 #+ATTR_LATEX: :width 6.0in
  18 #+ATTR_HTML: :width 600px
  19 [[file:screenshot.png]]
  20
  21 Supports video file link preview with thumbnail.
  22
  23 #+ATTR_ORG: :width 600
  24 #+ATTR_LATEX: :width 6.0in
  25 #+ATTR_HTML: :width 600px
  26 [[file:video-thumbnail.png]]
  27
  28 * Features [20/24]
  29
  30 - [X] Only display org-link-beautify preview images (and icons) when headline
  31   expanded. This will reduce Emacs memory and improve performance!!!
  32 - [X] support colorize links if file: target file does not exist
  33 - [X] support display icons for link types (currently already supported many link types)
  34 - [X] supported many different link types (If you found not supported link type, PR welcome!)
  35 - [X] display image for previewing image file
  36 - [X] display image for previewing PDF file and preview of specific PDF page number. Like this:
  37
  38   #+begin_src org
  39   [[file:/path/to/filename.pdf]]
  40   #+end_src
  41   #+begin_src org
  42   [[pdfview:/path/to/filename.pdf::15]]
  43   #+end_src
  44
  45   Currently support PDF link types:
  46   + =pdfview:=
  47   + =docview:=
  48   + =eaf:pdfviewer::=
  49   + =file:=
  50 - [X] support image link preview
  51 - [X] display thumbnail for video file link
  52   + [X] support Linux video thumbnail with "=ffmpegthumbnailer="
  53   + [X] support macOS video thumbnail with "=qlmanage="
  54   + [X] support all platforms with "=ffmpeg="
  55 - [X] preview audio file link with wave form image
  56   + [X] support Linux audio thumbnail with "=audiowaveform="
  57   + [X] support macOS audio thumbnail with "=qlmanage="
  58 - [X] preview ebooks, supports: epub, mobi, azw3, pdf etc.
  59 - [X] preview CDisplay Archived Comic Book Formats (.cbr, .cbz, cb7, .cba etc) cover
  60 - [X] add keymap on link text-property, available keybindings:
  61   + =[Enter]= :: =org-open-at-point=, so you can press =[Enter]= to open link.
  62     You can add more keybindings with following similar config:
  63     #+begin_src emacs-lisp :eval no
  64     (define-key org-link-beautify-keymap (kbd "RET") 'org-open-at-point)
  65     #+end_src
  66   + =[M-w]= :: copy file in link at point
  67   + =[M-q]= :: display QR code for link URL at point
  68 - =[c]= :: =org-link-beautify-copy-file-to-clipboard=, copy the file at point link to system clipboard for pasting.
  69 - [X] preview text files like .org, .markdown (.md), .txt, and source code files etc (customized with ~org-link-beautify-text-preview-list~).
  70 - [X] preview archive files like .zip, .rar, .tar.gz, .tar.bz2, .7z etc.
  71 - [ ] preview URL with screenshot on web page (Still considering whether should add this feature.)
  72 - [ ] preview FictionBook2 (.fb2, .fb2.zip) covert image
  73 - [ ] preview subtitle file with limited lines
  74 - [X] display link filename over thumbnail to display more link information through Emacs overlay
  75
  76 * Install
  77
  78 ** Requirements
  79
  80 - nerd-icons ::
  81
  82 - video thumbnail feature needs package "=ffmpegthumbnailer="
  83
  84   For Arch Linux:
  85
  86   #+begin_src shell :dir /sudo:: :results none
  87   sudo pacman -S --noconfirm ffmpegthumbnailer
  88   #+end_src
  89
  90   For macOS:
  91
  92   #+begin_src shell
  93   brew install ffmpegthumbnailer
  94   #+end_src
  95
  96 - audio wave form image preview need package "=audiowaveform="
  97
  98   Check out https://github.com/bbc/audiowaveform for installation guide.
  99
 100 - PDF file preview with command "=pdftocairo=" or "=pdf2svg="
 101
 102   For Arch Linux:
 103
 104   #+begin_src shell :dir /sudo:: :results none
 105   sudo pacman -S --noconfirm poppler # command pdftocairo
 106   sudo pacman -S --noconfirm pdf2svg # command pdf2svg
 107   #+end_src
 108
 109   For macOS:
 110
 111   #+begin_src shell
 112   brew install poppler pdf2svg
 113   #+end_src
 114
 115 - EPUB file cover image preview need command "=gnome-epub-thumbnailer="
 116
 117   For Arch Linux:
 118
 119   #+begin_src shell :dir /sudo:: :results none
 120   sudo pacman -S --noconfirm gnome-epub-thumbnailer
 121   #+end_src
 122
 123   For macOS:
 124
 125   https://github.com/marianosimone/epub-thumbnailer
 126
 127 - EPUB file cover image preview with "epub-thumbnailer.py" script requires PIL/Pillow.
 128
 129   #+begin_src shell
 130   python  -m pip install Pillow
 131   python3 -m pip install Pillow
 132   #+end_src
 133
 134 ** MELPA
 135
 136 * Usage
 137
 138 #+begin_src emacs-lisp
 139 (org-link-beautify-mode 1) ; (ref:toggle org-link-beautify-mode)
 140 #+end_src
 141
 142 * Performance
 143
 144 If you want better better performance. You can do bellowing options:
 145
 146 - Enable option ~org-link-beautify-async-preview~
 147
 148   #+begin_src emacs-lisp
 149   (setq org-link-beautify-async-preview t)
 150   #+end_src
 151
 152 - You can toggle this option carefully to improve Org ~org-activate-links~ performance:
 153
 154   #+begin_src emacs-lisp
 155   (setq org-element-use-cache t)
 156   #+end_src
 157
 158 * Link examples
 159
 160 *NOTE*: Because =all-the-icons= fonts has some issue on my system, so bellowing some
 161 icons might not correctly displayed. And some links are not beautified because I
 162 have not found suitable icons for them. And if file: link type source file is
 163 not available, it will be colored. If you have any idea, PR welcome.
 164
 165 #+begin_src org
 166 - file link [[file:babel-R.org][kkk]]
 167   + remote file
 168   + non-existing file
 169   + video thumbnail for video file link  [[file:~/Downloads/Neural Network Architectures-oJNHXPs0XDk.mkv]]
 170 - raw link [[file:babel-clojure.org]]
 171 - file+sys link [[file+sys:README.org]]
 172 - file link smart recognize file types [[file:~/Downloads/8-个税政治成本最高 对社会公平毫无帮助\[李稻葵\].pdf]]
 173 - directory link [[file:~/Downloads/][Downloads]]
 174 - URL link (use different icons based on url with smart all-the-icons) [[https://www.google.com]]
 175 - elisp link [[elisp:(print "hello, org-link-beautify!")]]
 176 - shell link [[shell:echo "hi"]]
 177 - eww link [[eww:https://www.baidu.com]]
 178 - A mu4e link [[mu4e:msgid:87mu62hfq1.fsf@nicolasgoaziou.fr][Re: [Suggestion] add an API function for getting link description]]
 179 - Git link [[git:/home/stardiviner/Code/Emacs/org-mode/lisp/org.el::master@{2017-06-24}::1]]
 180 - orgit link
 181 - orgit-rev link
 182 - orgit-log link
 183 - pdfview link [[pdfview:~/Downloads/社会网络 深度图查询.pdf]]
 184 - grep link [[grep:org-link-beautify]]
 185 - occur link [[occur:org-link-beautify]]
 186 - man link [[man:grep]]
 187 - info link [[info:emacs]]
 188 - help link [[help:man]]
 189 - rss link [[rss:https://www.gmail.com]]
 190 - elfeed link [[elfeed:Today's news]]
 191 - telnet link
 192 - wikipedia link [[wikipedia:Linux]]
 193 - mailto link [[mailto:numbchild@gmail.com]]
 194 - doi link [[doi:what?]]
 195 - 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]]
 196 #+end_src
 197
 198 * FAQ
 199
 200 *NOTE*: This Emacs package icons use "[[https://github.com/domtronn/all-the-icons.el][all-the-icons]]". If you got icon problem. You
 201 need to make sure all-the-icons and fonts installed correctly.
 202
 203 ** Q: Some link types are not beautified by org-link-beautify?
 204
 205 This is because =org-link-beautify= finished loading before that package register link type. This
 206 depend on your Emacs config init file the order or loading packages.
 207
 208 Solution: make sure =org-link-beautify= is loaded at the end of all packages. You can config like this:
 209
 210 #+begin_src emacs-lisp
 211 (add-hook 'after-init-hook #'org-link-beautify-mode)
 212 #+end_src
 213
 214 * Contributions
 215
 216 - Thanks to John Kitchin and Nicolas Goaziou help in Org Mode mailing list.
 217 - And [[https://emacs-china.org/t/icon-org-mode/13147][yuchen-lea's screenshot]] gives me design idea
 218 - pdf file link preview inspired from [[https://github.com/shg/org-inline-pdf.el][org-inline-pdf.el]]
 219