This is my attempt to reduce clutter when viewing org-mode files. I think it looks noisy to look at all the markup, especially in README files when they are displayed in Dired buffers with my dired-auto-readme mode. When viewing org-files, I am usually mostly interested in the content, not so in markup. Org-view-mode is an attempt to create a read-only “viewer” mode. Thus per definition, this minor mode is for consuming org content, not so much for creating it. It could be actually renamed org-readme-mode, since I have created it mostly to read README files in git repos without unnecessary noise :-). Also, don’t expect this to work well with org-capture, agendas, etc.
The package is now available from Melpa repository, so if you have Melpa included in your package archives, you can install org-view-mode either via built-in Emacs package manager with
M-x package-install RET org-view-mode RET
Or if you use use-package you can just do:
(use-package org-view-mode
:ensure t)You can download org-view-mode.el somewhere and use package.el to install file: M-x package-install-file RET and follow the prompt.
You may use straight.el to install this package, or some combination of straight & use-package
;; straight.el
(straight-use-package
'(org-view-mode :type git :host github :repo "amno1/org-view-mode"))
;; use-package & straight
(use-package org-view-mode
:straight (org-view-mode :type git :host github :repo "amno1/org-view-mode"))Either clone this repo or just download ‘org-view-mode.el’.
Put org-view-mode.el somewhere in Emacs load-path. From there you can just require the file somewhere in your init file or add autoload for org-view-init mode to your init file.
Org-view does not use any external packages. Minimal Emacs version supported is probably 25.1.
M-x org-view-mode to turn it on/off.
Org-view-mode uses two mode maps: org-view-mode-map and org-view-edit-mode-map.
The former is active when read-only mode is on, while the latter is active when quick editing file. There really are not so many actions defines, only two: enter-edi mode and exit org-view-mode. Of course org-mode map(s) are active all the time. Maybe at some point in the future I might go through the mode and choose which ones to enable or disable, but for the current, be aware that all org-mode shortcuts are active and that some might not work due to read-only status of the buffer while in org-view-mode.
Some elements are centered in window in respect to fill-column value. Those are currently paragraphs marked with begin/end-centered, title, author, and email address. If fill-column is for some reason nil or invalid (less than 1), org-view will use the default fill-column of 80 columns. Controlled with:
org-view-default-fill-column
variable. Its value can be customized in customize options.
Org-view-mode will by default hide any line starting with ‘#+’ to the end of that line. Also the new line character before that line is hidden, so that there are no visible empty lines where hidden text is. You can set:
org-view-hide-keywords
to nil to disable it.
In addition to regular markup, even some agenda keywords are hidden: DEFAULT: and SCHEDULED:. Hiding those can be disabled by setting:
org-view-hide-agenda-keywords
to nil. Note that both variables have to be ‘t in order to hide agenda keywords.
To disable centering of title, author and email, set org-view-prettify-credentials to nil value.
Centering is done with respect to fill-column value.
Only the author and email keywords are prettified as of currently along with the title keyword too. Co-authors are not yet prettified and are hidden by default, as org-view does with other markup. Patch is welcome if someone would like to implement that.
By default outline-mode display ellipses instead of hidden text. Org-view-mode can hide those too. Unfortunately it does not see possible to hide ellipses only at some places, since it depends on a value in display-table. At least I don’t see how to change it, I have tried to bind selective-display-ellipses and org-ellipses in various ways in order to hide them, but it does not seem to do anything. Changing the value in buffer-display-table does the trick, but it is all or nothing approach. Since it also removes ellipses from headlines, there is no indication if the content is toggled or not. For that reason the default value is off. The variable in control is: //org-view-hide-ellipses/. Use it at your own risk..
By default org-view-mode hides leading stars in outline headings. You can disable it by setting org-view-hide-stars to nil.
Hiding tags and properties can be disabled by setting org-view-hide-tags and org-view-hide-properties to nil.
Org-view will by default display text marked as quote and verse with their own face and aligned to the left. To disable paragraph prettification set ort-view-prettify-paragraphs to nil.
The alignment is done in respect to the longest line in the paragraph. Variables to control the alignment with are org-view-quote-align and org-view-verse-align.
The control values you can assign to each are: ‘left, ‘right and ‘middle.
Paragraphs marked with begin/end-center are always aligned in the middle. The effect of each alignment is shown in the screenshot below:
In quote and verse paragraphs it is also possible to prettify the author if it is specified. The author should be prefixed with — (three dashes) and stretches to the end of the buffer line. By default, dashes are replaced with Unicode drawing characters: ───. This option is controlled with org-view-author-prefix.
Faces used to display quotes, verses and credentials are:
org-view-quote-face, org-view-verse-face and org-view-author-face
which can all be customized via customize options.
For other options avialable please see the org-view group in customize:
M-x customize-group RET org-view
Org view mode comes with an optional org-view-font feature. This gives you the
ability to use a variable pitch/alternate font for reading org documents.
You may utilize it by customizing the following variables:
org-view-font-enableto enable/disable theorg-view-fontfeatureorg-view-font-remaps(alist) to add/remove explicit face settings for org-modeorg-view-font-no-remap(list) to protect specific faces from being remapped
Use M-x customize-group org-view-font to view these customization options in one
view.
You may also customize the view font with elisp:
(require 'org-view-mode)
(setq org-view-font-enable)
(add-to-list 'org-view-font-remaps '(default . (:family "Noto Sans")))For example, if you would like to enable an additional mode, say org-bullets, and only in org-view-mode, you can do something like this:
(add-hook 'org-view-mode-hook
(lambda ()
(if org-view-mode
(org-bullets-mode +1)
(org-bullets-mode -1))) nil t)Org-bullets, replace stars in headings with unicode characters, so in order to see the bullets in org-mode, you have to tell org-view-mode not to hide stars, by customizing the org-view-hide-stars to nil.
Of course, you will have to apropriately load org-bullets somewhere in your init file as well.
There might be lots of issues I am not aware of, since I haven’t extensively used this with many org files.
I would like to hear input, ideas, suggestions and problems found. I don’t promise to implement everything or any at all, but if something can be implemented relatively easily and is useful, I would like to hear the idea. Let me know.
I am not a very good user of org-mode myself, so I don’t have any org-mode files. with complex markup of my own, so I have used some from others for both tests and the screencast above. I would like to thank the authors for putting up their code and README files and for letting us use them freely, in order of the appearance in the screencast above, to Omar Antolín Camarena for Orderless, Takaaki Ishikawa for moom, Protesilaos Stavrou for mct and Okamsn for loopy. Thank you.
GPL v3. For details, see the attached license file.