[[https://melpa.org/#/dired-auto-readme][file:https://melpa.org/packages/dired-auto-readme-badge.svg]]
[[./images/txt-mode.png]]
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 [[https://github.com/clemera/dired-git-info][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 [[https://gitlab.com/kisaragi-hiu/dired-show-readme][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.