Improve edit_uri flexability

[jkobti]

Hi guys,
According to the documentation, I should be able to only add the link to my bitbucket repository to get edit links.
I added it like this: repo_url: https://bitbucket.org/josephkobti/testdocs/
but the links I'm getting are not working
i.e. https://bitbucket.org/josephkobti/testdocs/src/default/docs/index.md

I think maybe I should add the repo_url in another way, any suggestions?

[waylan]

What URL are you expecting to get?

IIRC, Bitbucket doesn't have an "edit" URL for documents in your repo. We can only point to the document, then the user needs to click on the "edit" button which uses a script on Bitbucket's site to switch to edit mode (there is no change to the URL). In other words, this is a limit of Bitbucket which we have no control over.

If, on the other hand, Bitbucket does offer an "edit" URL for documents, we would be happy to update MkDocs to support it. Please let us know what that URL scheme is and we'll add support.

[waylan]

Closing this due to a lack of information to act on.

[elvismdev]

@jkobti In my case I set edit_uri value to src/master/docs and that should point the users directly to the documentation file inside the Bitbucket repository source code. Therefore they can click on "edit" from the Bitbucket UI to make changes to the documentation .md file.

@waylan If that helps, this is how an edit URL in Bitbucket would open directly the file from the source code editor: https://bitbucket.org/elvismdev/my-project/src/master/docs/index.md?mode=edit&spa=0

[waylan]

@elvismdev thank you for providing Bitbiucket's edit URL format.

It would seem that MkDocs' current implementation is inadequate for general use. As it currently stands, an "edit URL" is composed by joining the following three parts:

{ repo_url }/{ edit_uri }/{ page.url }

However, Bitbucket would need:

{ repo_url }/src/{ branch }/{ page.url }?mode=edit&spa=0

And based on this recent report in #1437, a GitHub wiki would need:

{ repo_url }/wiki/{ page.title }/_edit

Given the above, it seems that rather than having a setting for edit_uri it would be more effective to have a setting for a edit_url_template which the user could define. Then MkDocs could use Python's string.format() to pass in the page object. I suppose it could accept the repo_url as well, but that shouldn't be necessary as the user could just include that in the edit_url_template.

[waylan]

Note that since #1224 we have supported query string based formats used by some hosts. However, this works because, like GitHub, the page path comes after the edit_uri. It's just that the page path is in a query string. All #1224 did was account for an edit_uri ending with the beginning of a query string and joined the page path appropriately.

What I'm proposing here would work in all cases with the various parts in any order. Users just need to be careful that to properly include or exclude slashes in the template. Under the hood it drastically simplifies things as we no longer need to worry about that. The problem is that the burden is now on the end user to do things correctly.

There could also be an issue where a value included in a query string would need to be escaped differently that when part of the path. Not sure how to address that. Although we currently don't address it, so maybe its not necessary.

[waylan]

See also some thoughts on a plugin for handling this.

[spinicist]

Hi,
It might be more appropriate to open a separate issue (or two) on this, but it appears that the "edit URL" is being incorrectly forced to lower-case.

I spotted this with my documentation (http://spinicist.github.io/QUIT) because I had only the repo_url specified and not edit_uri, and my docs_dir is "Docs" not "docs" (to fit my pre-existing naming convention before I started using mkdocs). The generated link was all lower-case, which resulted in a 404 on github.

I have now specified edit_uri to be "", which then makes repo_url work as a link to the repo front-page, which is actually what I wanted in the first place.

So:
1 - Unexpected behaviour that I had to set edit_uri to "" to get the desired behaviour
2 - edit_uri links appear to be incorrectly forced to lower-case.

Thanks for all the hard work, this is first problem I've had with mkdocs and it is very minor.

[jacebrowning]

For GitHub, the following seems to work:

repo_url: https://github.com/<owner>/<repo>
edit_uri: https://github.com/<owner>/<repo>/edit/<branch>/<docs-root>

e.g.

repo_url: https://github.com/jacebrowning/datafiles
edit_uri: https://github.com/jacebrowning/datafiles/edit/develop/docs

[nebgor]

#2212 highlights that even '/' is not a given before filename

[nejch]

For GitLab's Static Site Editor (from #2212), this would be something like:

{{ repo_url }}/-/sse/{{ branch }}/docs%2F{{ page.file.src_path | urlencode }}

Or optionally with a redirect back to the site in the query:

{{ repo_url }}/-/sse/{{ branch }}/docs%2F{{ page.file.src_path | urlencode }}?return_url={{ page.canonical_url | urlencode }}

Both the path and return_url would need to be URL-encoded. I don't think config.docs_dir can be used as it is the absolute path on the filesystem. branch would be the default branch from which the GitLab Pages are deployed (master/main etc). I guess this can be hardcoded by the project (edit: most likely needs to be URL-encoded as well, in case someone uses something like master/pages etc).

This makes me think @waylan that at least your idea of edit_url_template is necessary, but is some post-processing feasible with this (e.g. gitlab really needs these paths url-encoded). or would this be more feasible with plugins?

I'd be interested in adding this, although for now I managed to get GitLab's SSE to work with a small jinja hack in the base.html template.

For reference gitlab's middleman example template https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb#L16-18 and helper: https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/helpers/custom_helpers.rb#L3

[waylan]

This makes me think @waylan that at least your idea of edit_url_template is necessary, but is some post-processing feasible with this (e.g. gitlab really needs these paths url-encoded). or would this be more feasible with plugins?

If we go with an edit_uri_template my expectation is that we would pass in the parts as-is (no processing). That is why a plugin would be preferable. Any third party could create a plugin for any given service which meets the specific needs of that service. And you don't need to wait for us to get around to adding support for that service and then wait some more for us to make our next release, etc.

This should be easy for a plugin to address now. Each Page instance includes an edit_url attribute which simply contains the string representation of the URL which was build from the repo_url, edit_uri and src_path. If the repo_url and/or edit_uri are not available, the value is None (see mkdocs/structure/pages.py#L107). A plugin could replace that value with a value it derives from plugin specific config options (using the on_pre_page event). The value of this approach is that each plugin can define its own config options, so those options can be whatever is needed for the supported service. The plugin could also easily include additional processing such as url-encoding.

The one issue that a plugin may struggle with is providing an icon for the service. This was discussed here. We may need to provide a mechanism for the plugin to provide the icon and make it available for the theme.

[nejch]

Thanks for the quick feedback @waylan. Based on your info I put together a quick thing here: https://gitlab.com/nejch1/mkdocs-gitlab-static-site-editor, which does the job for me (initial PR here if you have an account to comment).

Does this makes sense? If so I might do some cleanup/polishing and publish this on pypi. Still unsure if it's overkill to have a plugin specifically for this, or if it should be a more generic plugin that can handle other use cases/platforms, but I can't think of any at the moment.

Hmm I wasn't even thinking about icons (some don't use repo-specific ones for Edit, see https://github.com/squidfunk/mkdocs-material/blob/094819e1e41b7a54aa2b5ed2a413cdc22fd5afd9/material/base.html#L161). But I see now the plugin should probably at least set repo_name to gitlab for the user even with the current setup, for on-prem instances.

[waylan]

Yes @nejch that’s the general idea. Whether you want to only support one service or multiple is up to you.

_{Sent with GitHawk}

[MichelZ]

I have created a plugin now for GitHub Wiki that changes the link to the correct format... For those needing GitHub Wiki support, give it a try?
https://pypi.org/project/mkdocs-github-wiki-edit-url/

[Hnasar]

For GitLab support too this would be useful. GitLab provides two ways to edit files:

1. a simple file editor - https://gitlab.com/group/repo/-/edit/main/docs/index.md
2. Web IDE (more features) - https://gitlab.com/-/ide/project/group/repo/edit/main/-/docs/index.md

GitLab defaults to 2) Web IDE but mkdocs doesn't provide a way to construct that kind of URL using the edit_uri field (only 1) works)

[oprypin]

• Add edit_uri_template config #2927

I propose a new config edit_uri_template that takes precedence over edit_uri.

These two are equivalent:

edit_uri: blob/master/docs/
edit_uri_template: blob/master/docs/{path}

Available expansions:

• {path} is the path to the .md file relative to docs_dir
• {path!q} is the same but urlquoted
• {path_noext} is the same without the extension

Let's collect some useful examples

• https://github.com/project/repo

  • https://github.com/project/repo/ blob/master/docs/{path} *
  • https://github.com/project/repo/ edit/master/docs/{path} *

• https://github.com/project/repo/wiki

  • https://github.com/project/repo/wiki/ {path_noext}
  • https://github.com/project/repo/wiki/ {path_noext}/_edit

• https://gitlab.com/project/repo

  • https://gitlab.com/project/repo/ -/ blob/master/docs/{path} *
  • https://gitlab.com/project/repo/ -/ edit/master/docs/{path} *
  • https://gitlab.com/project/repo/ -/sse/master/docs%2F{path!q}
  • https://gitlab.com/-/ide/project/group/repo/edit/master/-/docs/{path} *†

• https://bitbucket.org/project/repo

  • https://bitbucket.org/project/repo/ src/master/docs/{path} *†
  • https://bitbucket.org/project/repo/ src/master/docs/{path}?mode=edit

Explanations

• Some examples have a whitespace in between, it means that the prefix is implied from repo_url and doesn't need to be written out.
• "*" means it's already achievable, just use edit_uri without the {path} part.
• "†" means some commenters claimed it was unachievable with just edit_uri but actually it is

[ultrabug]

I like your proposal @oprypin, it does make sense to propose such a template variant

What I don't quite get tho is your proposed expansions taxonomy:

• {path} is the path to the .md file relative to docs_dir -> ok obviously looks like a f-string
• {path!q} is the same but urlquoted -> why use an exclamation mark? why not 'path_urlquoted'?
• {path_noext} is the same without the extension -> unless here you were implying that we could use {path_noext!q}?

[oprypin]

Ah yes, !q can be applied to any field, it's just that there are only these two fields. Maybe later we will find that more fields are needed.

[ultrabug]

Ok makes more sense now, that sounds great if correctly documented.

Do you want to rebase #2927 ? I can try to add a commit to the PR branch to update the documentation if you like.

[oprypin]

btw, and the weird exclamation mark syntax is just because I reuse the implementation of Python's format strings. Other features of format strings are available, although also currently unnecessary

[oprypin]

Ah.. I have the branch rebased but I didn't push it.
No but it's fine, I will write the documentation

[ultrabug]

btw, and the weird exclamation mark syntax is just because I reuse the implementation of Python's format strings

Saw that, elegant (should I say as always?) ;)