"Improve this Doc" URL goes back to a 404 when canceling out

[airbreather]

DocFX Version Used: docfx.console 2.37.2

Template used: default

Steps to Reproduce:

1. Write a .NET project on GitHub with at least one interesting member that can get an "Improve this Doc" link.
2. Generate API documentation for that project.
3. Browse the API documentation.
4. Click an "Improve this Doc" link.
5. Click the "Cancel" link near the top.

Expected Behavior:
You should be punted back to the overwrite directory that the file would have been created in, same as if you got to the "Create new file" page by clicking the button while browsing the overwrite directory on GitHub.

Actual Behavior:

It punts you back to a 404 page.

Live Sample:

https://nettopologysuite.github.io/NetTopologySuite.IO.GPX/api/NetTopologySuite.IO.GpxBoundingBox.html

• For example, the "Improve this Doc" for the summary points me here, and canceling punts you back here, which is the 404 I'm referring to.

[airbreather]

This may very well be a bug on GitHub's side, but I wanted to start here in case we think there's something we can do with the URL to make it work the way a user might expect it to.

[herohua]

@airbreather , I did not see a "Cancel" link on the page with the "Improve this Doc" link:

Could you provide more information?

[airbreather]

Ahh -- it appears that I only immediately see "Cancel" when logged in as someone with push access to the repo!

The equivalent page shows up when you click "Fork this repository and propose changes", and the same thing happens when I click "Cancel" there... tested on some random page for docfx:

Specifically, that was FileMappingItem --> Improve this Doc, which should (for someone with push access to dotnet/docfx) give what I saw on mine, which should (I think) punt you back to this, which 404s.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[airbreather]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

Thank you, friendly bot, for doing your part to help keep repositories clean.

This still appears to be an issue in the latest stable release (2.40.11).

[superyyrrzz]

This should be a repo config issue. When you click cancel, GitHub will lead you back to the directory you just try creating. If it does not exist, it will be 404.

To resolve this, you shall ensure the directory doc/overwrite/ exist in your repo. Of course, git does not support create an empty directory. You can add a placeholder file in it.

[airbreather]

To resolve this, you shall ensure the directory doc/overwrite/ exist in your repo. Of course, git does not support create an empty directory. You can add a placeholder file in it.

That doesn't seem to be enough, unfortunately. I do have a .gitkeep file here: https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/tree/master/doc/overwrite however, links such as this cancel back to this.

It looks like the problem is that the links on pages such as this one use the following format:

https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/master/doc/overwrite/new?filename=NetTopologySuite_IO_GpxBoundingBox.md&value=---%0Auid%3A%20NetTopologySuite.IO.GpxBoundingBox%0Asummary%3A%20%27*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax%27%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A

Which cancels back to:

https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/tree/master/doc/overwrite/new

When exploring around, I noticed that I can change overwrite/new?filename to overwrite/.gitkeep?filename, like so:

https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/master/doc/overwrite/.gitkeep?filename=NetTopologySuite_IO_GpxBoundingBox.md&value=---%0Auid%3A%20NetTopologySuite.IO.GpxBoundingBox%0Asummary%3A%20%27*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax%27%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A

Then the "cancel" link puts me to the dummy file I created in my "overwrite" folder:

https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/blob/master/doc/overwrite/.gitkeep

I think this is probably a GitHub bug. Removing all the query parameters and the final "/new" gives me a link like this, which works exactly as I expect it to work (of course, without the special name and contents that docfx require in order for it to do what we're trying to do):

https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/develop/doc/overwrite

As soon as I add the "filename" query parameter, it seems to go up a level.

I was able to manually come up with a URL that does work the way I wanted it to, however: changing overwrite/new?filename=whatWeGenerateNow to overwrite?filename=overwrite/whatWeGenerateNow like so:

https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/master/doc/overwrite?filename=overwrite/NetTopologySuite_IO_GpxBoundingBox.md&value=---%0Auid%3A%20NetTopologySuite.IO.GpxBoundingBox%0Asummary%3A%20%27*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax%27%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A

Brings me to a page that works exactly as I expect it to.

[superyyrrzz]

@airbreather Thank you for the experiments!

As soon as I add the "filename" query parameter, it seems to go up a level.

My investigation stuck here before. So I added the final /new to make it work. It is really interesting that duplicating overwrite can get a perfect URL! BTW, I also feel it like a GitHub bug.

You can try customizing template to make it work. Welcome to contribute back 😄 Related code:

docfx/src/docfx.website.themes/common/common.js

Line 86 in a977d26

url += '/new?filename=' + getHtmlId(uid) + '.md';

[airbreather]

I also feel it like a GitHub bug.

Yeah. I just played around with it a little bit more, and if I click cancel and then use the Back button on my browser (Firefox 65), GitHub starts ignoring that part of the filename=, which causes me to start editing doc/TheFilename.md instead of doc/overwrite/TheFilename.md like I was before.

[airbreather]

GitHub bug

I've opened isaacs/github#1527, and I'll be e-mailing GitHub support with a link to this issue shortly. Follow that issue for any updates on that side of things.

[airbreather]

Not sure when this was updated, but the "Cancel" button now returns me back to the repository's home page, which I think is good enough.