What the GUI exposes

When browsing the source code in a repository, GitHub offers a button that says "Create New File":

Clicking on it brings the user to a page that looks something like this:

The specific link is as follows:

https://github.com/NetTopologySuite/NetTopologySuite/new/develop/NetTopologySuite

What we found

The dotnet/docfx developers discovered that you can use query string parameters to pre-fill some of the values for you.

• This allows that project to give end users a link that will let them overwrite the auto-generated documentation and/or add more information that isn't in the code, by creating files in an "overwrite" folder with the machine-readable name and initial contents so that the tool will be able to see that on the next run and incorporate it into the documentation site.

Specifically, the value query string parameter fills the main text box, and the filename query string parameter can be used to fill in the filename.

Issues

The value parameter seems to work just fine, but there are some issues with filename.

Goes up a level

When filename is specified at all, the last folder part of the URL seems to be ignored. Compare the following URL to the URL from above:

https://github.com/NetTopologySuite/NetTopologySuite/new/develop/NetTopologySuite?filename=Callees.cs&value=public+static+class+Callees%0A%7B%0A++++public+const+string+PrimaryCallee+=+%22Ghostbusters%22%3B%0A%7D

It takes you to a page that looks like this (compare the folder path to what we had above):

Workaround 1 breaks "cancel" link

The DocFX folks also saw this, but they found a workaround: append some dummy path after it like "new", so that it puts you into the same folder.

Compare this URL:

https://github.com/NetTopologySuite/NetTopologySuite/new/develop/NetTopologySuite/new?filename=Callees.cs&value=public+static+class+Callees%0A%7B%0A++++public+const+string+PrimaryCallee+=+%22Ghostbusters%22%3B%0A%7D

That brings us here:

However, clicking the encircled "cancel" link takes us to a nonexistent page. See discussion and other details in dotnet/docfx#3156:

https://github.com/NetTopologySuite/NetTopologySuite/tree/develop/NetTopologySuite/new

Workaround 2 doesn't stick through "cancel" and "back button"

So I had the idea that, instead of appending some dummy that doesn't exist, we could try duplicating the last folder in the filename query string parameter:

https://github.com/NetTopologySuite/NetTopologySuite/new/develop/NetTopologySuite?filename=NetTopologySuite/Callees.cs&value=public+static+class+Callees%0A%7B%0A++++public+const+string+PrimaryCallee+=+%22Ghostbusters%22%3B%0A%7D

That brought me here, and it seemed perfect!

"Cancel" worked just fine, bringing me back to the folder that would have contained the file. Then I clicked on my browser's "Back" button (Firefox 65), and:

...darn. It seems to have ignored the path information from the filename parameter for some reason.

What we really need

What we need is a supported way to pre-fill some of the information on the "Create New File" page in order to be able to help users contribute incremental, targeted improvements to documentation that can be consumed by a tool.