+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]]

• [[#features][Features]]

• [[#releases][Releases]]

• [[#contributors][Contributors]]

• 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=.
• ~org-indent-mode~ support
• 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 ** My Setup Check [[file:config.el][config.el]]

This file is my personal configuration for ~shrface~ configured it along with other packages, and I updates it frequently. It can greatly improve your reading experience while also having great performance when using those packages.

You can use it as a reference to configure your own ~shrface~.

** Keybindings 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

;; my personaly keybindings (Doom Eamcs) (map! :map nov-mode-map :after nov :g "" 'shrface-outline-cycle ;; redundant, just make sure it works :nie "TAB" 'shrface-outline-cycle ;; redundant, just make sure it works :nie "S-" 'shrface-outline-cycle-buffer ;; redundant, just make sure it works :g [backtab] 'shrface-outline-cycle-buffer ;; redundant, just make sure it works :nie "" 'shrface-outline-cycle-buffer ;; redundant, just make sure it works :nie "C-j" 'shrface-next-headline :nie "C-k" 'shrface-previous-headline)

+END_SRC

• [[file:FEATURES.org][Features]]

• [[file:RELEASES.org][Releases]]

• Contributors

  +html: