Subject of the feature

Linking directly to folders, showing the folder's readme, is supported by all three supported Git hosts — GitHub, Gitlab and Bitbucket, and also by this plugin.

However, this plugin considers anchors appended to those directory links invalid without checking (reported as missing-heading-in-file).

Problem

Linking to a section in a folder's readme directly (without linking explicitly to the readme file) is a pattern I like to use a lot in larger projects. It works perfectly fine in GitHub and Gitlab and should therefore not be reported as an issue by this plugin. (It should theoretically work in BitBucket as well since that also renders the readme below a directory's file list. But since BitBucket behaves more like an SPA it generally has trouble with anchors in cross-folder links.)

Expected behaviour

When provided a directory link with a hash, this plugin should consider that a link to the README.md of that folder and evaluate the hash accordingly.

If no readme exists, a missing-file should be appropriate.

I added a repro at loilo/repro-remark-directory-links-49. It shows some of the described warnings but exits early due to a runtime error that occurs when linking to the root folder with a hash appended.

Caveats

• In addition to headline anchors, the #readme anchor should be supported — however, this should already be taken care of by Allow links to point to the top of the document #48.

• Case sensitivity is a little bit unclear: While GitHub supports uppercase and lowercase readme file names, there's no documentation on which one is preferred if more than one matching file is present.

  I tested this a while ago and if I remember correctly, there is no way to determine priority from the file name, but actually the readme file committed first will be used. GitHub will even prefer a README.rst over a README.md if it was added earlier.

  Gitlab and BitBucket also support case-insensitive readme file names, but I have no idea (and have not done any tests) how they determine the preferred file.

  However, I'd probably ignore all this "multiple readme files" fluff as "weird edge case" and hands down just pick the first thing that looks like a /^readme.md$/g.