Add docs and tests for edit_uri_template option

docs/user-guide/configuration.md

@@ -93,6 +93,24 @@ directory.
 edit_uri: root/path/docs/
 ```
 
+For example, having this config:
+
+```yaml
+repo_url: https://example.com/project/repo
+edit_uri: blob/main/docs/
+```
+
+means that a page named 'foo/bar.md' will have its edit link lead to:  
+<https://example.com/project/repo/blob/main/docs/foo/bar.md>
+
+`edit_uri` can actually be just an absolute URL, not necessarily relative to `repo_url`, so this can achieve the same result:
+
+```yaml
+repo_url: https://example.com/project/repo/blob/main/docs/
+```
+
+For more flexibility, see [edit_uri_template](#edit_uri_template) below.
+
 > NOTE:
 > On a few known hosts (specifically GitHub, Bitbucket and GitLab), the
 > `edit_uri` is derived from the 'repo_url' and does not need to be set
@@ -124,6 +142,63 @@ access.
 `src/default/docs/` for a Bitbucket repo, if `repo_url` matches those domains,
 otherwise `null`
 
+### edit_uri_template
+
+The more flexible variant of [edit_uri](#edit_uri). These two are equivalent:
+
+```yaml
+edit_uri: 'blob/main/docs/'
+edit_uri_template: 'blob/main/docs/{path}'
+```
+
+(they are also mutually exclusive -- don't specify both).
+
+Starting from here, you can change the positioning or formatting of the path, in case the default behavior of appending the path isn't enough.
+
+The contents of `edit_uri_template` are normal [Python format strings](https://docs.python.org/3/library/string.html#formatstrings), with only these fields available:
+
+* `{path}`, e.g. `foo/bar.md`
+* `{path_noext}`, e.g. `foo/bar`
+
+And the conversion flag `!q` is available, to percent-encode the field:
+
+* `{path!q}`, e.g. `foo%2Fbar.md`
+
+Here are some suggested configurations that can be useful:
+
+GitHub Wiki:  
+(e.g. `https://github.com/project/repo/wiki/foo/bar/_edit`)
+
+```yaml
+repo_url: 'https://github.com/project/repo/wiki'
+edit_uri_template: '{path_noext}/_edit'
+```
+
+BitBucket editor:  
+(e.g. `https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit`)
+
+```yaml
+repo_url: 'https://bitbucket.org/project/repo/'
+edit_uri_template: 'src/master/docs/{path}?mode=edit'
+```
+
+GitLab Static Site Editor:  
+(e.g. `https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md`)
+
+```yaml
+repo_url: 'https://gitlab.com/project/repo'
+edit_uri_template: '-/sse/master/docs%2F{path!q}'
+```
+
+GitLab Web IDE:  
+(e.g. `https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md`)
+
+```yaml
+edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}'
+```
+
+**default**: `null`
+
 ### site_description
 
 Set the site description. This will add a meta tag to the generated HTML header.

mkdocs/structure/pages.py

@@ -186,6 +186,7 @@ def _set_edit_url(
                 noext = posixpath.splitext(src_uri)[0]
                 edit_uri = edit_uri_template.format(path=src_uri, path_noext=noext)
             else:
+                assert edit_uri is not None and edit_uri.endswith('/')
                 edit_uri += src_uri
             if repo_url:
                 # Ensure urljoin behavior is correct

mkdocs/tests/config/config_options_tests.py

@@ -417,7 +417,7 @@ class Schema:
             self.get_config(Schema, {'option': 1})
 
 
-class RepoURLTest(TestCase):
+class EditURITest(TestCase):
     class Schema:
         repo_url = config_options.URL()
         repo_name = config_options.RepoName('repo_url')
@@ -490,6 +490,58 @@ def test_repo_name_custom_and_empty_edit_uri(self):
         )
         self.assertEqual(config.get('edit_uri'), 'edit/master/docs/')
 
+    def test_edit_uri_template_ok(self):
+        config = self.get_config(
+            self.Schema,
+            {
+                'repo_url': "https://github.com/mkdocs/mkdocs",
+                'edit_uri_template': 'edit/foo/docs/{path}',
+            },
+        )
+        self.assertEqual(config['edit_uri_template'], 'edit/foo/docs/{path}')
+
+    def test_edit_uri_template_errors(self):
+        with self.expect_error(edit_uri_template=re.compile(r'.*\}.*')):
+            self.get_config(
+                self.Schema,
+                {
+                    'repo_url': "https://github.com/mkdocs/mkdocs",
+                    'edit_uri_template': 'edit/master/{path',
+                },
+            )
+
+        with self.expect_error(edit_uri_template=re.compile(r'.*\bz\b.*')):
+            self.get_config(
+                self.Schema,
+                {
+                    'repo_url': "https://github.com/mkdocs/mkdocs",
+                    'edit_uri_template': 'edit/master/{path!z}',
+                },
+            )
+
+        with self.expect_error(edit_uri_template="Unknown template substitute: 'foo'"):
+            self.get_config(
+                self.Schema,
+                {
+                    'repo_url': "https://github.com/mkdocs/mkdocs",
+                    'edit_uri_template': 'edit/master/{foo}',
+                },
+            )
+
+    def test_edit_uri_template_warning(self):
+        config = self.get_config(
+            self.Schema,
+            {
+                'repo_url': "https://github.com/mkdocs/mkdocs",
+                'edit_uri': 'edit',
+                'edit_uri_template': 'edit/master/{path}',
+            },
+            warnings=dict(
+                edit_uri_template="The option 'edit_uri' has no effect when 'edit_uri_template' is set."
+            ),
+        )
+        self.assertEqual(config['edit_uri_template'], 'edit/master/{path}')
+
 
 class ListOfItemsTest(TestCase):
     def test_int_type(self):

mkdocs/tests/structure/page_tests.py

@@ -509,7 +509,40 @@ def test_page_edit_url(
                 edit_url2='http://example.com/edit/master/sub1/non-index.md',
             ),
             dict(
-                config={'repo_url': 'http://example.com', 'edit_uri': ''},  # Set to blank value
+                config={'edit_uri_template': 'https://github.com/project/repo/wiki/{path_noext}'},
+                edit_url='https://github.com/project/repo/wiki/testing',
+                edit_url2='https://github.com/project/repo/wiki/sub1/non-index',
+            ),
+            dict(
+                config={
+                    'repo_url': 'https://github.com/project/repo/wiki',
+                    'edit_uri_template': '{path_noext}/_edit',
+                },
+                edit_url='https://github.com/project/repo/wiki/testing/_edit',
+                edit_url2='https://github.com/project/repo/wiki/sub1/non-index/_edit',
+            ),
+            dict(
+                config={
+                    'repo_url': 'https://gitlab.com/project/repo',
+                    'edit_uri_template': '-/sse/master/docs%2F{path!q}',
+                },
+                edit_url='https://gitlab.com/project/repo/-/sse/master/docs%2Ftesting.md',
+                edit_url2='https://gitlab.com/project/repo/-/sse/master/docs%2Fsub1%2Fnon-index.md',
+            ),
+            dict(
+                config={
+                    'repo_url': 'https://bitbucket.org/project/repo/',
+                    'edit_uri_template': 'src/master/docs/{path}?mode=edit',
+                },
+                edit_url='https://bitbucket.org/project/repo/src/master/docs/testing.md?mode=edit',
+                edit_url2='https://bitbucket.org/project/repo/src/master/docs/sub1/non-index.md?mode=edit',
+            ),
+            dict(
+                config={
+                    'repo_url': 'http://example.com',
+                    'edit_uri': '',
+                    'edit_uri_template': '',
+                },  # Set to blank value
                 edit_url=None,
                 edit_url2=None,
             ),