#+TITLE: SHRFACE #+DATE: May 07, 2020 #+SINCE: {replace with next tagged release version} #+STARTUP: inlineimages nofold [[https://melpa.org/#/shrface][file:https://melpa.org/packages/shrface-badge.svg]]

• Table of Contents :TOC_1:noexport:

• [[#description][Description]]
• [[#installation][Installation]]
• [[#configuration][Configuration]]
• [[#newslogs][News/Logs]]

• Description This package extends =shr= / =eww= with org features and analysis capability. It can be used in [[https://github.com/dash-docs-el/dash-docs][dash-docs]], [[https://www.gnu.org/software/emacs/manual/html_mono/eww.html][eww]], [[https://github.com/wasamasa/nov.el][nov.el]], [[https://github.com/djcb/mu][mu/mu4e]], [[https://github.com/chenyanming/anki.el][anki.el]], etc. It is also able to export HTML buffer to Org buffer/file, or download/archive web pages.

#+attr_org: :width 600px [[file:img/eww.png]]

• Configurable org-like heading faces, headline bullets, item bullets,paragraph indentation, fill-column, item bullet, versatile hyper links(http/https/file/mailto/etc) face and so on.
• Browse the internet or local html file with [[https://www.gnu.org/software/emacs/manual/html_mono/eww.html][eww]] just like org mode.
• Read dash docsets with[[https://github.com/dash-docs-el/dash-docs][ dash-docs]] and the beauty of org faces.
• Read epub files with [[https://github.com/wasamasa/nov.el][nov.el]] , just like org mode.
• Read html email with [[https://github.com/djcb/mu][mu/mu4e]] , the same reading experience just like org mode without formatting html to org file.
• Switch/jump the headlines just like org-mode in [[https://www.gnu.org/software/emacs/manual/html_mono/eww.html][eww]] and [[https://github.com/wasamasa/nov.el][nov.el]] with =imenu=
• Toggle/cycle the headlines just like org-mode in [[https://www.gnu.org/software/emacs/manual/html_mono/eww.html][eww]] and [[https://github.com/wasamasa/nov.el][nov.el]] with [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html][outline minor mode]] , =org-cycle/org-shifttab=, or =shrface-outline-cycle= / =shrface-outline-cycle-buffer=.
• Enable indentation just like org-mode in [[https://www.gnu.org/software/emacs/manual/html_mono/eww.html][eww]] and [[https://github.com/wasamasa/nov.el][nov.el]] with =org-indent-mode=
• Analysis capability:
  • Headline analysis: List all headlines with clickable texts, or jump around with [[https://github.com/abo-abo/swiper][ivy]].
  • URL analysis: List all classified URL with clickable texts in a buffer, or jump around with [[https://github.com/abo-abo/swiper][ivy]].
• Export HTML buffer to org buffer/file using shr engine (no [[https://pandoc.org/][Pandoc]] is needed).

#+BEGIN_QUOTE The project target is to apply org features and analysis capability to =shr=, and all libraries that render HTML with =shr= (Simple HTML Renderer).

As [[https://www.emacswiki.org/emacs/HtmlRendering][EmacsWiki]] says:

=shr.el= is an HTML renderer in Emacs as of version 24.4 (based on libxml2, it was originally a part of Gnus). It’s the basis of the web browser =eww=. #+END_QUOTE

• Installation

It's available on [[https://melpa.org/][Melpa]] :

#+BEGIN_SRC emacs-lisp M-x package-install shrface #+END_SRC

• Configuration

** Quick Start *** use-package I recommend configure with ~use-package~, it is more elegant: #+BEGIN_SRC emacs-lisp

(use-package shrface :defer t :config (shrface-basic) (shrface-trial) (shrface-default-keybindings) ; setup default keybindings (setq shrface-href-versatile t))

(use-package eww :defer t :init (add-hook 'eww-after-render-hook #'shrface-mode) :config (require 'shrface))

(use-package nov :defer t :init (add-hook 'nov-mode-hook #'shrface-mode) :config (require 'shrface) (setq nov-shr-rendering-functions '((img . nov-render-img) (title . nov-render-title))) (setq nov-shr-rendering-functions (append nov-shr-rendering-functions shr-external-rendering-functions)))

(use-package anki :defer t :load-path "~/.emacs.d/lisp/anki/" :init (add-hook 'anki-mode-hook #'shrface-mode) (autoload 'anki "anki") (autoload 'anki-browser "anki") (autoload 'anki-list-decks "anki") :config (require 'shrface) (setq anki-shr-rendering-functions (append anki-shr-rendering-functions shr-external-rendering-functions)) (setq sql-sqlite-program "/usr/bin/sqlite3") (setq anki-collection-dir "/Users/chandamon/Library/Application Support/Anki2/User 1")) #+END_SRC

• Check this section to see the supported faces: #+html: Supported Faces

• Check the experimental faces notes here: #+html: Experimental faces

• There is another library =inherit-org= to inherit org faces to even more non-org buffers, and it is no dependency/relationships with =shrface=, check here https://github.com/chenyanming/inherit-org

*** Font setup The default font is ~variable-pitch~. #+BEGIN_SRC emacs-lisp (set-face-attribute 'variable-pitch nil :font (format "%s:pixelsize=%d" "iA Writer Quattro S" 15)) #+END_SRC

** Keybinding Settings You can to call =shrface-default-keybindings= to enable the recommended keybindings. #+begin_src emacs-lisp (defun shrface-default-keybindings () (interactive) "Sets up the default keybindings for `shrface-mode'." (define-key shrface-mode-map (kbd "TAB") 'shrface-outline-cycle) (define-key shrface-mode-map (kbd "") 'shrface-outline-cycle-buffer) (define-key shrface-mode-map (kbd "C-t") 'shrface-toggle-bullets) (define-key shrface-mode-map (kbd "C-j") 'shrface-next-headline) (define-key shrface-mode-map (kbd "C-k") 'shrface-previous-headline) (define-key shrface-mode-map (kbd "M-l") 'shrface-links-counsel) ; or 'shrface-links-helm or 'shrface-links-consult (define-key shrface-mode-map (kbd "M-h") 'shrface-headline-counsel)) ; or 'shrface-headline-helm or 'shrface-headline-consult #+end_src

Since the keybindings may conflict with other modes, such as =nov-mode-map=, =eww-mode-map=, =mu4e-mode-map=. If you want to enable shrface's keybindings on these modes, you have to bind the functions to those maps as well.

Here is the keybinding example: #+BEGIN_SRC emacs-lisp (with-eval-after-load 'nov (define-key nov-mode-map (kbd "") 'shrface-outline-cycle) (define-key nov-mode-map (kbd "S-") 'shrface-outline-cycle-buffer) (define-key nov-mode-map (kbd "C-t") 'shrface-toggle-bullets) (define-key nov-mode-map (kbd "C-j") 'shrface-next-headline) (define-key nov-mode-map (kbd "C-k") 'shrface-previous-headline) (define-key nov-mode-map (kbd "M-l") 'shrface-links-counsel) ; or 'shrface-links-helm or 'shrface-links-consult (define-key nov-mode-map (kbd "M-h") 'shrface-headline-counsel)) ; or 'shrface-headline-helm or 'shrface-headline-consult

(with-eval-after-load 'eww (define-key eww-mode-map (kbd "") 'shrface-outline-cycle) (define-key eww-mode-map (kbd "S-") 'shrface-outline-cycle-buffer) (define-key eww-mode-map (kbd "C-t") 'shrface-toggle-bullets) (define-key eww-mode-map (kbd "C-j") 'shrface-next-headline) (define-key eww-mode-map (kbd "C-k") 'shrface-previous-headline) (define-key eww-mode-map (kbd "M-l") 'shrface-links-counsel) ; or 'shrface-links-helm or 'shrface-links-consult (define-key eww-mode-map (kbd "M-h") 'shrface-headline-counsel)) ; or 'shrface-headline-helm or 'shrface-headline-consult

(with-eval-after-load 'mu4e (define-key mu4e-view-mode-map (kbd "") 'shrface-outline-cycle) (define-key mu4e-view-mode-map (kbd "S-") 'shrface-outline-cycle-buffer) (define-key mu4e-view-mode-map (kbd "C-t") 'shrface-toggle-bullets) (define-key mu4e-view-mode-map (kbd "C-j") 'shrface-next-headline) (define-key mu4e-view-mode-map (kbd "C-k") 'shrface-previous-headline) (define-key mu4e-view-mode-map (kbd "M-l") 'shrface-links-counsel) ; or 'shrface-links-helm or 'shrface-links-consult (define-key mu4e-view-mode-map (kbd "M-h") 'shrface-headline-counsel)) ; or 'shrface-headline-helm or 'shrface-headline-consult #+END_SRC

In additional to the keys provided by ~shrface-mode~, the following features should also work, you can test and find which fits your requirement: *** ~org-mode~

1. =org-cycle=,
2. =org-shifttab=
3. =org-content=
4. =org-overview= etc.

*** ~outline-minor-mode~ *** ~imenu-mode~

** Features Anatomy

*** shrface-mode ~shrface-mode~ is a minor mode that help you enable/disable the following additional features:

1. =imenu=
2. =outline-minior-mode=
3. =org-indent-mode=
4. Setup shr faces

Please be careful, every time you run ~shrface-mode~, faces will be enable/disable globally for all shr rendered buffers. Since I have not found a good way to enable/disable the faces per buffer yet.

If you want to enable shrface just when you need to, you should avoid to use ~add-hook~ like the recommended settings above, and just enable/disable =shrface-mode= via =M-x=.

*** shrface-occur List all headlines, and you can easily jump between them by mouse click.

*** shrface-links List all URLs and classify them. You can easily go to the occurrence (Left Click/Enter), copy the URL (Middle Click) or browse the URL (Right Click). Besides, if [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] is available, web icon for each link will be shown.

*** shrface-links-counsel List all URLs with =counsel=.

• The URLs are listed in order based the position on the buffer.
• The first candidate to select is the next url counting from the current cursor position. In this case, you can use =C-M-m (ivy-call)=, =C-M-n (ivy-next-line-and-call)=, and =C-M-p (ivy-previous-line-and-call)= to jump around all URLs without losing your position.
• =C-o= to fire the action menu on the selected candidate.
• =C-c C-o= to fire the =ivy-occur=

*** shrface-headline-counsel List all headlines with =counsel=.

• It is a better solution than =imenu= and =shrface-occur.=
• It can work without the headline bullets. You can disable the bullets via =(setq shrface-toggle-bullets t)= and still be able to jump around the headlines.
• The first candidate to select is the current context headline of the current cursor position. In this case, you can use =C-M-m (ivy-call)=, =C-M-n (ivy-next-line-and-call)=, and =C-M-p (ivy-previous-line-and-call)= to jump around all headlines without losing your position.
• =C-o= to fire the action menu on the selected candidate.
• =C-c C-o= to fire the =ivy-occur=

*** shrface-links-helm List all URLs with =helm=.

• =TAB= to preview the link
• =RET= to goto the link

*** shrface-headline-helm List all headlines with =helm=.

• =TAB= to preview the headline
• =RET= to goto the headline

*** shrface-links-consult List all links with =consult=.

*** shrface-headline-consult List all headlines with =consult=.

*** shrface-next-headline, shrface-previous-headline These two headline functions are designed to replace =outline-next-headline= and =outline-previous-headline=. They scan the headline number text properties and jump to the headlines which means it can work under no bullets circumstance if =(setq shrface-toggle-bullets t)=.

*** Headline bullets (h1 to h6) **** Customize the headline bullets You can configure your favorite bullets up to 6 levels of headings (cycled through if less than 6 bullets in setting).

You can set it with: #+BEGIN_SRC emacs-lisp (setq shrface-bullets-bullet-list ("◉" "○" "✸" "✿")) #+END_SRC

PS: The bullets setting can be derived from =org-bullets-bullet-list= or =org-superstar-headline-bullets-list=, if [[https://github.com/sabof/org-bullets][org-bullets]] or [[https://github.com/integral-dw/org-superstar-mode][org-superstar]] is available.

**** Toggle headline bullets locally/temporary

The quick way to toggle(disable/enable) headline bullets locally/temporary: #+BEGIN_SRC emacs-lisp M-x shrface-toggle-bullets #+END_SRC

Please notice: In =mu4e-view-mode=, using =shrface-toggle-bullets= will toggle bullets globally.

**** Disable headline bullets globally If you do not like headline bullets, disable them globally by:

#+BEGIN_SRC emacs-lisp (setq shrface-toggle-bullets t) #+END_SRC

Please notice, the following features are also disabled:

1. function =shrface-occur=
2. variable =shrface-mode=

However, the following features are still be able to use:

1. function =shrface-links=
2. function =shrface-links-counsel=
3. function =shrface-headline-counsel=
4. function =shrface-previous-headline=
5. function =shrface-next-headline=
6. function =shrface-links-helm=
7. function =shrface-headline-helm=
8. function =shrface-links-consult=
9. function =shrface-headline-consult=

*** Item bullet You can configure your favorite item bullet for shrface

You can set it with: #+BEGIN_SRC emacs-lisp (setq shrface-item-bullet "-") #+END_SRC

PS: Only one type of item bullet is supported, prettified by =shrface-item-bullet-face=

*** Paragraph indentation and fill column Both ~shrface-paragraph-indentation~ and ~shrface-paragraph-fill-column~ are obsolete.

Pleas use ~org-indent-mode~ to control the indentation, and ~shr-width~ to adjust the text width (fill-column).

*** Versatile URL You can enable versatile URL faces support simply by: #+BEGIN_SRC emacs-lisp (setq shrface-href-versatile t) #+END_SRC

The following types of URL can be customized.

• http
• https
• ftp
• file
• mailto
• other

*** Supported faces Here are the faces supported: #+BEGIN_SRC emacs-lisp

;;; Faces for `shrface-basic

(defcustom shrface-bullets-bullet-list (or (bound-and-true-p org-bullets-bullet-list) (bound-and-true-p org-superstar-headline-bullets-list) '("◉" "○" "✸" "✿")) "Bullets for headings" :group 'shrface :type '(repeat (string :tag "Bullet character")))

(defface shrface-href-face '((t :inherit org-link)) "Default face if `shrface-href-versatile' is nil" :group 'shrface-faces)

(defface shrface-href-other-face '((t :inherit org-link :foreground "#87cefa")) "Face used for other than http:// https:// ftp:// file:// mailto:// if `shrface-href-versatile' is NON-nil. For example, it can be used for fontifying charter links with epub files when using nov.el." :group 'shrface-faces)

(defface shrface-href-http-face '((t :inherit org-link :foreground "#39CCCC")) "Face used for , http:// if `shrface-href-versatile' is NON-nil" :group 'shrface-faces)

(defface shrface-href-https-face '((t :inherit org-link :foreground "#7FDBFF")) "Face used for , https:// if `shrface-href-versatile' is NON-nil" :group 'shrface-faces)

(defface shrface-href-ftp-face '((t :inherit org-link :foreground "#3D9970")) "Face used for , ftp:// if `shrface-href-versatile' is NON-nil" :group 'shrface-faces)

(defface shrface-href-file-face '((t :inherit org-link :foreground "#2ECC40")) "Face used for , file:// if `shrface-href-versatile' is NON-nil" :group 'shrface-faces)

(defface shrface-href-mailto-face '((t :inherit org-link :foreground "#FF851B")) "Face used for , mailto:// if `shrface-href-versatile' is NON-nil" :group 'shrface-faces)

(defface shrface-h1-face '((t :inherit org-level-1)) "Face used for

headlines." :group 'shrface-faces)

(defface shrface-h2-face '((t :inherit org-level-2)) "Face used for

headlines." :group 'shrface-faces)

(defface shrface-h3-face '((t :inherit org-level-3)) "Face used for

headlines." :group 'shrface-faces)

(defface shrface-h4-face '((t :inherit org-level-4)) "Face used for

headlines." :group 'shrface-faces)

(defface shrface-h5-face '((t :inherit org-level-5)) "Face used for

headlines." :group 'shrface-faces)

(defface shrface-h6-face '((t :inherit org-level-6)) "Face used for

headlines." :group 'shrface-faces)

(defface shrface-verbatim '((t :inherit org-verbatim)) "Face used for verbatim/emphasis - ." :group 'shrface-faces)

(defface shrface-item-bullet-face '((t :inherit org-list-dt)) "Face used for unordered list bullet" :group 'shrface-faces)

(defface shrface-item-number-face '((t :inherit org-list-dt)) "Face used for ordered list numbers" :group 'shrface-faces)

(defface shrface-description-list-term-face '((t :inherit org-list-dt)) "Face used for description list terms