Docs: Link to Edit (Contribute) gives 404 on "configuration-files-new"

[martypdx]

Docs page(s)

https://eslint.org/docs/latest/use/configure/configuration-files-new

What documentation issue do you want to solve?

The "Edit File" button links to 404

What do you think is the correct solution?

Instead of linking to

https://github.com/eslint/eslint/edit/main/docs/src/use/configure/configuration-files-new.md

I believe it should link to:

https://github.com/eslint/eslint/edit/main/docs/src/use/configure/configuration-files.md

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response

[snitin315]

Thanks for the report, actually we auto-generate these links (since #16213), and the logic seems to be pointing to the main branch regardless of the eslint version.

eslint/docs/src/_data/sites/en.yml

Lines 116 to 118 in bde5105

	edit_link:
	start_with: https://github.com/eslint/eslint/edit/main/docs/
	text: Edit this page

eslint/docs/src/_includes/layouts/doc.html

Lines 99 to 108 in bde5105

	<div class="docs-edit-link">
	<a href="
	{% if edit_link %}
	{{ edit_link }}
	{% else %}
	{{ site.edit_link.start_with }}{{ page.inputPath }}
	{% endif %}
	"
	class="c-btn c-btn--secondary">{{ site.edit_link.text }}</a>
	</div>

So if you see docs for NEXT or HEAD, the Edit the Page button correctly links to https://github.com/eslint/eslint/edit/main/docs/src/use/configure/configuration-files.md

[snitin315]

I'm unsure if this is a bug or a limitation for our docs. We can provide edit links only for branches that exist, however for published releases we maintain tags which don't support editing files.

I'd like to know other team members' opinions on how to treat this case. cc @eslint/website-team

[kecrily]

I think that should be a limit. Maybe we shouldn't show the edit button on released versions.

[martypdx]

My assumption is that the purpose of the Edit Button is to make it easy to fork, edit markdown on Github, and PR to promote contributions. It is an invitation to help correct, clarify, and contribute.

Curious in practice for eslint if that happens, does the "Edit Button" lead to useful contributions?

I think that should be a limit. Maybe we shouldn't show the edit button on released versions.

In theory, assuming the docs are complete on release and don't need further input seems short-sighted. But if the edit button is not productive for generating contributions, then as maintainers I could see limiting that.

[nzakas]

This is just a quirk of the release that we should find a way to fix. This is the first major release we've had with the new docs site and there are all kinds of little inconsistencies we've found.

The docs for v8 are contained in the latest branch, and so we should be able to link to that only when there's a next branch. Sending PRs to the latest branch will trigger rebuilding the docs site and get it updated automatically.

So basically, what we should have is...

When we are in prerelease

1. Docs at /docs/latest should point their edit buttons at the latest branch
2. Docs at /docs/next should point their edit buttons at the main branch
3. Docs at /docs/head should point their edit buttons at the main branch

When we are not in prerelease

1. Docs at /docs/latest should point their edit buttons at the main branch
2. Docs at /docs/head should point their edit buttons at the main branch

(I'm also realizing this is super confusing and we probably need to revisit this approach after v9 is finalized.)

[snitin315]

I'll give this a shot.