Allow file navigation and git features on Markdown files

[Krinkle]

Problem

It's great that Gitiles has support for Markdown files. Letting that render out of the box has been very useful in various Wikimedia projects that we host in Gerrit.

One thing I commonly run into when considering to link to such file, is that they are prone to become dead-ends. That is, there is no way to navigate elsewhere from such file as the header is completely removed.

As an example:

https://gerrit.wikimedia.org/g/mediawiki/core/+/1b791f0687/docs/magicword.md

I would like to be able to navigate, without having inside knowledge of Gitiles URL structure and performing manual URL manipulation, to the following two places:

• Other files in the same directory, e.g.
  • https://gerrit.wikimedia.org/g/mediawiki/core/+/1b791f0687/docs/
• Other actions on the same file, such as "blame" and "log", e.g. ** https://gerrit.wikimedia.org/g/mediawiki/core/+log/1b791f0687/docs/magicword.md
  • https://gerrit.wikimedia.org/g/mediawiki/core/+blame/1b791f0687/docs/deferred.md

By comparison, when viewing a text file, these navigations are there by default: https://gerrit.wikimedia.org/g/mediawiki/core/+/1b791f0687/docs/deferred.txt

Alternative

I'm aware that there is a configuration option in Gerrit to turn off markdown rendering entirely, but I'd be great if (akin to Gitea, Phabricator, GitLab, and GitHub) there was a way to "just" render the file but otherwise treat it as any other resource.

Currently it seems the option is between rendering it as plain text like any other resource, or to go fully into the mode of a custom website navigation which defaults to having no navigation.

Proposal

• When there is no custom navigation configured, default to rendering the navigation as for regular resources (with the path navigation and the file/log/blame action links).
• And/or; A configuration option to "always" render the resource navigation. This would mean that for pages with custom site nav, the "Gitiles" header would be replaced but the path and file actions would remain.
• And/or: A configuration option to turn off support for custom site navigation and instead render the regular resource navigation always.

[hanwen]

have you tried this: https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Navigation-bar ?

you can see it in action at https://chromium.googlesource.com/infra/infra/+/master/doc/index.md

[Krinkle]

@hanwen Yes, this what I was referring to with "custom navigation" and is precisely what I can't use.

I don't think it's feasible to add to every markdown file: [parent dir] [file] [history] [blame]. Not in the least because those links would need to assume which branch/tag/commit to use, and not make much sense outside of Gerrit e.g. when viewing the code in other mirrors and code browsers, and because in most cases these markdown files are to be consumed outside Gerrit and thus those links would need to be filtered out somewhere.

So to clarify, I am not building a static website with Gerrit. These are markdown files just like the majority you might see on any repository on GitHub. It's just for light reading in the repository, and quite often the files are also part of another pipeline (e.g. Doxygen, or Jekyll), where previewing it here is just useful for permalinks to old versions, or perhaps during code review. And then there are just ad-hoc files like README and CHANGELOG that are useful to be able to render as rich text, but you don't want to lose the ability to go to the parent directory, or to view logs/blame etc.

[hanwen]

When there is no custom navigation configured, default to rendering the navigation as for regular resources (with the path navigation and the file/log/blame action links).

That sounds reasonable. Unfortunately, gitiles is in maintenance mode, so we can't schedule this work, but if you provide a change, someone could look at it.