Display a Readme file in a Dired buffer if one exists. The content of the file is displayed below the directory content. Cursor can freely move into the Readme file content, and you can search, copy, click on links and call some Emacs functions on the content as avialable in respective modes. However, the file is read only so you can not modify it, and some other functionality normally found will not be available.
This is not yet in either Elpa nor Melpa, so currently you will have to either clone this repository or just download raw dired-auto-readme.el somewhere where your Emacs can find it.
To enable/disable dired-auto-readme-mode: M-x dired-auto-readme-mode.
There are few settings that can be modified, either via customize->Files->Dired Auto Readme or by setting the variables in init file or a running Emacs session.
dired-auto-readme-files - A list of regular expressions to specify what is considered as readme files. The expressions will be tried in the order as specified, so you can controll which file takes precidence.
Example:
(setq dired-auto-readme-file '("manifest\\W" ;; lets exclude manifest.jar
"readme\\.\\(org\\|rst\\|md\\|markdown\\)"The above code will first check if file with name MANIFEST if available, and if found, display that one, if not it look for a readme file.
We are combining here two major modes from two different buffers in one buffer, something Emacs is not ment to do, so there will be some problems. The real problem is that most minor modes expect to work with only one major mode buffer, in this case Dired. If a minor mode will do something over entire Dired buffer there will be issues, unfortunately. Sometimes it is enough to press ‘g’ to update dired buffer so it will render properly, but for some modes there will be artifacts, and other won’t work at all.
For example dired-auto-readme-mode does not play well with overlays. If you are using some mode that displays overlays, as for example dired-git-info, you will have to refresh your dired buffer after you toggle on/off dired-auto-readme-mode (just press ‘g’).
There are hundreds of packages and possible variations, there are probably other bugs I am not aware off. See if it works for you, and if/when you find problems, please report them or even better, give me a PR or send a patch.
What I do here is a dirty (and somewhat inneficient) trick. I simply open file in another buffer, let Emacs do the magic, and then copy buffer content inclusive properties over to dired buffer with font-lock (syntax hightlight) tuned to work only on dired portion of the buffer.
It is inneficient, but As I have tested, I don’t notice any speed problems on my computer, even on one older dual core laptop from 2016. I guess it would need a directory with hundred files or really big readme file for this to be noticable.
To speed up things when browsing directories, I suggest loading org-mode, rst-mode and markdown-mode in an idle-timer when Emacs starts.
This was inspired by very nice dired-show-readme by Kisaragi Hiu. However, dired-show-readme displays a Readme file as an image, and also uses external process to render a file to an image. It would be possible to use svg-renderer in Emacs to render to an svg image, however, a drawback of an image is, well, that it is an image. I find myself often wishing to click on a link in a Readme file, so I prefer having them as plain text so I can move cursor freely in and out and copy text, click on links etc.
<2024-02-29 tor>
After seveal fail attempts to copy over buffer-locals and all properties to fold spec, I finally gave up. What I believe would benefit Emacs was to refactor code for org-links in its own minor mode to make org-links available in any mode. However, to come around, mode-alist in dired-auto-readme now means to execute a hook after the text is inserted. At least I can initialize parts of org-mode that manage folding so links are rendered as descriptive. Rest seems to be more or less in text properties.
<2024-02-20 tis>
Again, more or less complete rework. We don’t use directory-files anymore. That should be quite a speedup on its own. The implication is that names are no longer case-sensitive, since we are using whatever ls program produces and same stuff that Dired sees.
We can now also control the order in which readme files are found, so it is possible to prefer some special file before a README file. Observe, that we are using looking-at-p to compare file names in Dired buffer, so craft your regexes carefully.
The internals are refactored to also be more efficient and do less work with copying visibility spec. Finally, but most! importantly there was a nasty bug which made font-lock always call our font-lock-region-functions which made Emacs font-lock really slow. It is now fixed and at least things seem to work fine for me for several days.
<2022-09-21 ons>
The package is now (almost) completely reworked again. I think it is getting to the point where I think it could be submitted as a package to Melpa. Fixed are some bugs and the implementation is reworked to be more efficient. Also, dealing with extra beautifying options, like displaying inlined images, markdown/org view modes, are now left for the end user as an option in respective mode hooks. That lets me remove few options, and simplify the package while making it more efficient too.
Gone is also private “mime” list, auto-readme-mode now automatically enables whichever mode is registered with Emacs with a given extension. There is still `dired-auto-readme-alist’ which holds cons pairs in form of (major-mode . hook). Hook is an user function called when a major-mode is enabled in README buffer.
<2022-02-10 tor>
Refactored more, made it to work with org-view-mode for even prettier dired renderings.
<2021-05-10 mån>
Completely reworked, with better org/markdown preview.
GPL v3. For details, see the attached license file.