Skip to content

Latest commit

 

History

History
407 lines (331 loc) · 14.4 KB

FEATURES.org

File metadata and controls

407 lines (331 loc) · 14.4 KB

Features

Features

shrface-mode

PS: I personally don’t use it, instead of enabling a minor mode, I hacked the render function directly, check config.el

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

  1. imenu
  2. outline-minior-mode
  3. 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 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:

(setq shrface-bullets-bullet-list ("◉" "○" "✸" "✿"))

PS: The bullets setting can be derived from org-bullets-bullet-list or org-superstar-headline-bullets-list, if org-bullets or org-superstar is available.

Toggle headline bullets locally/temporary

The quick way to toggle(disable/enable) headline bullets locally/temporary:

M-x shrface-toggle-bullets

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:

(setq shrface-toggle-bullets t)

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:

(setq shrface-item-bullet "-")

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 shr-indentation 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:

(setq shrface-href-versatile t)

The following types of URL can be customized.

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

Supported faces

Here are the faces supported:

;;; 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 <href> face if `shrface-href-versatile' is nil"
  :group 'shrface-faces)

(defface shrface-href-other-face '((t :inherit org-link :foreground "#87cefa"))
  "Face used for <href> 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 <href>, 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 <href>, 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 <href>, 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 <href>, 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 <href>, mailto:// if `shrface-href-versatile' is
NON-nil"
  :group 'shrface-faces)

(defface shrface-h1-face '((t :inherit org-level-1))
  "Face used for <h1> headlines."
  :group 'shrface-faces)

(defface shrface-h2-face '((t :inherit org-level-2))
  "Face used for <h2> headlines."
  :group 'shrface-faces)

(defface shrface-h3-face '((t :inherit org-level-3))
  "Face used for <h3> headlines."
  :group 'shrface-faces)

(defface shrface-h4-face  '((t :inherit org-level-4))
  "Face used for <h4> headlines."
  :group 'shrface-faces)

(defface shrface-h5-face  '((t :inherit org-level-5))
  "Face used for <h5> headlines."
  :group 'shrface-faces)

(defface shrface-h6-face '((t :inherit org-level-6))
  "Face used for <h6> headlines."
  :group 'shrface-faces)

(defface shrface-verbatim '((t :inherit org-verbatim))
  "Face used for verbatim/emphasis - <em>."
  :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 <dt>"
  :group 'shrface-faces)

(defface shrface-figure '((t :inherit org-table))
  "Face used for figure <figure>, e.g. figure captions."
  :group 'shrface-faces)

;;; Faces for `shrface-analysis' realted buffers

(defface shrface-links-title-face '((t :inherit default))
  "Face used for *shrface-links* title"
  :group 'shrface-analysis-faces)

(defface shrface-links-url-face '((t :inherit font-lock-comment-face))
  "Face used for *shrface-links* url"
  :group 'shrface-analysis-faces)

(defface shrface-links-mouse-face '((t :inherit mode-line-highlight))
  "Face used for *shrface-links* mouse face"
  :group 'shrface-analysis-faces)

;;; Faces for `shrface-trail' realted buffers

(defface shrface-code '((t :inherit org-code))
  "TODO Face used for inline code"
  :group 'shrface-faces)

Export Html to Org

Exporting HTML to Org doesn’t need to enable shrface-mode, or run shrface-basic / shrface-trail, you just make sure you (require 'shrface) before using the exporting features:

  • shrface-html-export-as-org: Export current html buffer to an org buffer.
  • shrface-html-export-to-org: Export current html buffer to an org file.
  • shrface-org-title: Dynamically bound and overwrite the org title.
  • shrface-request-url: Dynamically bound the request url, so that shrface can fix the relative/absolute urls based on the request url.

If you use org-web-tools to download the http page into org, you can also override its pandoc engine with shr engine as following:

(advice-add 'org-web-tools--html-to-org-with-pandoc :override 'shrface-html-convert-as-org-string)

Here are two simple examples to use shrface-html-export-as-org, and shrface-html-export-to-org, using Request.

Download an URL and output an Org buffer/file:

(defun request-url-as-org (url)
  (interactive "sRequest url: ")
  (require 'shrface)
  (require 'request)
  (request url
    :parser 'buffer-string
    :headers '(("User-Agent" . "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36"))
    :sync nil
    :success (cl-function
              (lambda (&key data &allow-other-keys)
                (let ((shrface-request-url url))
                  (shrface-html-export-as-org data))))))

(defun request-url-to-org (url)
  (interactive "sRequest url: ")
  (require 'shrface)
  (require 'request)
  (request url
    :parser 'buffer-string
    :headers '(("User-Agent" . "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36"))
    :sync nil
    :success (cl-function
              (lambda (&key data &allow-other-keys)
                (let ((shrface-request-url url))
                  (shrface-html-export-to-org data "request.org"))))))

If you use org-web-tools, it is very easy to capture the web as a readable format:

(defun request-url-readable (url)
  (interactive "sRequest url: ")
  (require 'shrface)
  (require 'request)
  (require 'org-web-tools)
  (request url
    :parser 'buffer-string
    :headers '(("User-Agent" . "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36"))
    :sync nil
    :success (cl-function
              (lambda (&key data &allow-other-keys)
                (let* ((web (org-web-tools--eww-readable data))
                       (title (car web))
                       (html (cdr web))
                       (shrface-org-title title)
                       (shrface-request-url url))
                  (shrface-html-export-as-org html))))))

Enable org-like ellipsis

To enable shrface-ellipsis the “three-dots” after each headline when it is hidden just like org mode, please manually add the predefined function: shrface-outline-visibility-changed to outline-view-change-hook,

(add-hook 'outline-view-change-hook 'shrface-outline-visibility-changed)

Enable source codes highlight

You can install shr-tag-pre-highlight.el to enable source codes highlight and background color.

(use-package shr-tag-pre-highlight
  :ensure t
  :after shr
  :config
  (add-to-list 'shr-external-rendering-functions
               '(pre . shr-tag-pre-highlight))
  (when (version< emacs-version "26")
    (with-eval-after-load 'eww
      (advice-add 'eww-display-html :around
                  'eww-display-html--override-shr-external-rendering-functions))))

Hacking the shr-tag-pre-highlight.el

If you want to add indentation, background color, #+BEGIN_SRC lang, and #+END_SRC for, you can overwrite the function as following:

(require 'shr-tag-pre-highlight)
(add-to-list 'shr-external-rendering-functions '(pre . shrface-shr-tag-pre-highlight))
(defun shrface-shr-tag-pre-highlight (pre)
    "Highlighting code in PRE."
    (let* ((shr-folding-mode 'none)
           (shr-current-font 'default)
           (code (with-temp-buffer
                   (shr-generic pre)
                   ;; (indent-rigidly (point-min) (point-max) 2)
                   (buffer-string)))
           (lang (or (shr-tag-pre-highlight-guess-language-attr pre)
                     (let ((sym (language-detection-string code)))
                       (and sym (symbol-name sym)))))
           (mode (and lang
                      (shr-tag-pre-highlight--get-lang-mode lang))))
      (shr-ensure-newline)
      (shr-ensure-newline)
      (setq start (point))
      (insert
       (propertize (concat "#+BEGIN_SRC " lang "\n") 'face 'org-block-begin-line)
       (or (and (fboundp mode)
                (with-demoted-errors "Error while fontifying: %S"
                  (shr-tag-pre-highlight-fontify code mode)))
           code)
       (propertize "#+END_SRC" 'face 'org-block-end-line ))
      (shr-ensure-newline)
      (setq end (point))
      (if light
          (add-face-text-property start end '(:background "#D8DEE9" :extend t))
        (add-face-text-property start end '(:background "#292b2e" :extend t)))
      (shr-ensure-newline)
      (insert "\n")))

Sometimes a wrong language is detected, but it is still great for highlight, even just for eye pleasing.

Screenshots when both enable shrface and the code highlights

img/code-highlight.png