Advertise Markdown files in docs/ as "source" files

[i-ky]

Right now GitHub does not detect the language of this repo:

After the fix it will identify Markdown as the main language:

In my opinion, this will help people (e.g. documentation writers and beginner programmers) to find a project to contribute to.

[SeanTAllen]

We are unsure about doing this. @i-ky we can see on other repositories that this is done for at least non markdown languages. Do you know why the markdown isn't recognized here? If we were to accept this, we'd want to do it across various repositories that are "markdown driven".

[i-ky]

@SeanTAllen, thank you for the feedback!

Do you know why the markdown isn't recognized here?

Markdown is recognized, but Markdown is considered prose language (i.e. not source code). Also paths like docs/ and Readme.md are discarded as documentation by default. (See how linguist works.) I believe this is a heuristic based on the fact that many projects store documentation alongside source code in the same repo. We don't want to "dilute" or even overpower language stats with Markdown, TeX, HTML and other common documentation formats. Unfortunately, for projects that have separate documentation-only repos this heuristic does more damage than good.

If we were to accept this, we'd want to do it across various repositories that are "markdown driven".

Feel free to point me to other repos, I will be happy to help fine-tune language detection there as well.

I've already made similar PRs to other repos:

• Fix GitHub's language detection for the repo flatpak/flatpak-docs#404
• Advertise Markdown files as "source" files drolbr/overpass-doc#14
• Advertise Markdown files as "source" files llvm/clangd-www#73

[SeanTAllen]

@i-ky that makes sense. we'll discuss further next Tuesday at our sync meeting, if not sooner. Also relevant repos would be pony-patterns and ponylang-website. Also perhaps contributors.

[i-ky]

Also relevant repos would be pony-patterns and ponylang-website. Also perhaps contributors.

Filed PRs for pony-patterns, ponylang-website, contributors and rfcs:

1. Advertise Markdown files in docs/ as "source" files pony-patterns#69
2. Advertise Markdown files as "source" files ponylang-website#886
3. Advertise Markdown files as "source" files contributors#24
4. Advertise Markdown files in text/ as "source" files rfcs#212

I deliberately commit changes to default branches of my forks for you to see the effect on GitHub's language detection.

Also https://github.com/ponylang/sublime-pony does not have any source files detected. My experience with Sublime Text is very limited, so I am not sure which would be the best way forward. Maybe we can add a few gitattributes to tune language detection manually, maybe we can submit a feature request to linguist for better support of Sublime Text plugin repos.

Additionally .ctags file should probably be marked as "source" of https://github.com/ponylang/pony-ctags, but linguist does not seem to have support for such format.