Skip to content

feat(docs): add an "Edit on GitHub" entry to the page context menu - #2297

Open
GigaHierz wants to merge 1 commit into
mainfrom
GigaHierz/edit-on-github-context-menu
Open

feat(docs): add an "Edit on GitHub" entry to the page context menu#2297
GigaHierz wants to merge 1 commit into
mainfrom
GigaHierz/edit-on-github-context-menu

Conversation

@GigaHierz

Copy link
Copy Markdown
Contributor

Split out of #2293, where it was too wide a footprint for an orphan-audit PR.

Why

The docs used to have an "Edit this page" control and it was used internally. It does not render today, and the fix you would reach for first is not available.

feedback.suggestEdit was a mint.json v1 key. Against https://mintlify.com/docs.json — which docs.json line 2 already declares as its $schema:

$ curl -sL -A 'Mozilla/5.0' https://mintlify.com/docs.json -o mint-schema.json
$ grep -oiE "feedback|suggestEdit|raiseIssue|thumbsRating" mint-schema.json | sort -u
(no output)

Zero matches for all four, and no edit key of any kind in the schema. Nothing in Mintlify's own llms.txt describes such a control, and curl on a live page finds no "Suggest edits" / "Edit this page" affordance.

What this does

Adds a custom entry to contextual.options, which surfaces in the page context menu on every page next to Copy, View and the AI tool entries already configured.

The limitation, stated plainly

The link cannot be per page. Mintlify substitutes $path only inside query-parameter values, not in the base URL, so github.com/celo-org/docs/edit/main/<path>.mdx is not expressible through this mechanism. The entry opens the repository, and GitHub's own edit → pull request flow continues from there. The description says exactly that rather than implying a deep link.

I did try to do better. A per-page link is expressible via GitHub code search:

{ "base": "https://github.com/search", "query": [{ "key": "q", "value": "repo:celo-org/docs path:$path" }] }

but GitHub code search requires authentication, so a logged-out reader gets a login wall instead of the file. That is worse than landing on the repo, so I did not use it.

If the per-page control matters, it is a Mintlify feature request — worth adding to the support thread already open under #2238.

Verification

$ python3 -c "import json; json.load(open('docs.json'))"   # parses
$ npx mintlify broken-links
success no broken links found

Shape checked against the schema's custom contextual option: title, description, icon, href, with additionalProperties: false. I left iconType off deliberately — Mintlify's prose documents it but the published schema does not list it, so including it risks failing validation.

Companion change in #2293 rewords the support section on build-on-celo/index so it no longer promises a control that does not exist. That PR stands alone; this one can land before or after it.

Restores the edit-a-page affordance the docs used to have, in the only form the
current Mintlify configuration supports.

The old control came from mint.json v1's `feedback.suggestEdit`. That key no
longer exists: `feedback`, `suggestEdit`, `raiseIssue` and `thumbsRating` all
return zero matches against https://mintlify.com/docs.json, which this repo
already declares as its `$schema`, and the live site renders no edit control.

A custom entry in `contextual.options` is the closest supported mechanism. It
appears in the context menu on every page, alongside Copy, View and the AI
tool entries already configured.

Known limitation: the href cannot be built per page. Mintlify substitutes
`$path` only inside query parameter values, not in the base URL, so a deep link
to `github.com/celo-org/docs/edit/main/<path>.mdx` is not expressible. The entry
opens the repository and GitHub's own edit-and-pull-request flow continues from
there; the description says that rather than implying a per-page link.

The GitHub code-search alternative would give a per-page link but requires a
login, so a logged-out reader would hit an auth wall instead of the file.

Verified: docs.json parses against the schema shape for a custom contextual
option (title, description, icon, href); `mintlify broken-links` green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant