Direct edit links to individual pages

This patch adds support for a configuration option `edit_uri` that
is used to generate a link directly to an individual page in the
source repository.

Fixes mkdocs#269

docs/user-guide/configuration.md

@@ -50,6 +50,37 @@ When set, provides a link to your GitHub or Bitbucket repository on each page.
 **default**: `'GitHub'` or `'Bitbucket'` if the `repo_url` matches those
 domains, otherwise `null`
 
+### edit_uri
+
+Path from the base `repo_url` to the docs directory when directly viewing a
+page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,
+etc), the branch, and the docs directory itself. Mkdocs concatenates `repo_url`
+and `edit_uri`, and appends the input path of the page.
+
+When set, provides a link directly to the page in your source repository. This
+makes it easier to find and edit the source for the page. If `repo_url` is not
+set, this option is ignored.
+
+For example, for a GitHub-hosted repository, the `edit_uri` would be as follows.
+(Note the `blob` path and `master` branch...)
+
+```yaml
+edit_uri: blob/master/docs/
+```
+
+For a Bitbucket-hosted repository, the equivalent `edit_uri` would be as
+follows. (Note the `src` path and `default` branch...)
+
+```yaml
+edit_uri: src/default/docs/
+```
+
+For other repository hosts, `edit_uri` works the same way. Simply specify the
+relative path to the docs directory.
+
+**default**: `blob/master/docs/` or `src/default/docs/` for GitHub or Bitbucket
+repos, respectively, if `repo_url` matches those domains, otherwise `null`
+
 ### site_description
 
 Set the site description. This will add a meta tag to the generated HTML header.

docs/user-guide/custom-themes.md

@@ -259,6 +259,11 @@ documentation page.
 The full, canonical URL to the current page. This includes the `site_url` from
 the configuration.
 
+##### page.edit_url
+
+The full URL to the input page in the source repository. Typically used to
+provide a link to edit the source page.
+
 ##### page.url
 
 The URL to the current page not including the `site_url` from the configuration.

mkdocs/commands/build.py

@@ -116,6 +116,9 @@ def get_page_context(page, content, toc, meta, config):
     if config['site_url']:
         page.set_canonical_url(config['site_url'])
 
+    if config['repo_url']:
+        page.set_edit_url(config['repo_url'], config['edit_uri'])
+
     page.content = content
     page.toc = toc
     page.meta = meta

mkdocs/config/config_options.py

@@ -202,6 +202,12 @@ def post_validation(self, config, key_name):
             else:
                 config['repo_name'] = repo_host.split('.')[0].title()
 
+        if config['repo_url'] is not None and config.get('edit_uri') is None:
+            if config['repo_name'].lower() == 'github':
+                config['edit_uri'] = 'blob/master/docs/'
+            elif config['repo_name'].lower() == 'bitbucket':
+                config['edit_uri'] = 'src/default/docs/'
+
 
 class Dir(Type):
     """

mkdocs/config/defaults.py

@@ -75,6 +75,12 @@
     # "GitHub" or "Bitbucket" for known url or Hostname for unknown urls.
     ('repo_name', config_options.Type(utils.string_types)),
 
+    # Specify a URI to the docs dir in the project source repo, relative to the
+    # repo_url. When set, a link directly to the page in the source repo will
+    # be added to the generated HTML. If repo_url is not set also, this option
+    # is ignored.
+    ('edit_uri', config_options.Type(utils.string_types)),
+
     # Specify which css or javascript files from the docs directory should be
     # additionally included in the site. Default, List of all .css and .js
     # files in the docs dir.

mkdocs/nav.py

@@ -151,6 +151,7 @@ def __init__(self, title, url, path, url_context):
         # Placeholders to be filled in later in the build
         # process when we have access to the config.
         self.canonical_url = None
+        self.edit_url = None
         self.content = None
         self.meta = None
         self.toc = None
@@ -186,6 +187,18 @@ def set_canonical_url(self, base):
             base += '/'
         self.canonical_url = utils.urljoin(base, self.abs_url.lstrip('/'))
 
+    def set_edit_url(self, repo_url, edit_uri):
+        if not repo_url.endswith('/'):
+            repo_url += '/'
+        if not edit_uri:
+            self.edit_url = repo_url
+        else:
+            if not edit_uri.endswith('/'):
+                edit_uri += '/'
+            self.edit_url = utils.urljoin(
+                repo_url + edit_uri,
+                self.input_path)
+
 
 class Header(object):
     def __init__(self, title, children):

mkdocs/tests/config/config_options_tests.py

@@ -125,6 +125,27 @@ def test_repo_name_custom(self):
         self.assertEqual(config['repo_url'], config['repo_url'])
         self.assertEqual(config['repo_name'], "Launchpad")
 
+    def test_edit_uri_github(self):
+
+        option = config_options.RepoURL()
+        config = {'repo_url': "https://github.com/mkdocs/mkdocs"}
+        option.post_validation(config, 'repo_url')
+        self.assertEqual(config['edit_uri'], 'blob/master/docs/')
+
+    def test_edit_uri_bitbucket(self):
+
+        option = config_options.RepoURL()
+        config = {'repo_url': "https://bitbucket.org/gutworth/six/"}
+        option.post_validation(config, 'repo_url')
+        self.assertEqual(config['edit_uri'], 'src/default/docs/')
+
+    def test_edit_uri_custom(self):
+
+        option = config_options.RepoURL()
+        config = {'repo_url': "https://launchpad.net/python-tuskarclient"}
+        option.post_validation(config, 'repo_url')
+        self.assertEqual(config.get('edit_uri'), None)
+
 
 class DirTest(unittest.TestCase):
 

mkdocs/themes/mkdocs/nav.html

@@ -69,9 +69,9 @@
               {%- endblock %}
 
               {%- block repo %}
-                {%- if repo_url %}
+                {%- if page and page.edit_url %}
                     <li>
-                        <a href="{{ repo_url }}">
+                        <a href="{{ page.edit_url }}">
                             {%- if repo_name == 'GitHub' %}
                                 <i class="fa fa-github"></i>
                             {%- elif repo_name == 'Bitbucket' -%}

mkdocs/themes/readthedocs/breadcrumbs.html

@@ -13,12 +13,13 @@
     {% if page %}<li>{{ page.title }}</li>{% endif %}
     <li class="wy-breadcrumbs-aside">
       {%- block repo %}
-      {% if repo_url %}
-        {% if repo_name == 'GitHub' %}
-          <a href="{{ repo_url }}" class="icon icon-github"> Edit on GitHub</a>
-        {% elif repo_name == 'Bitbucket' %}
-          <a href="{{ repo_url }}" class="icon icon-bitbucket"> Edit on BitBucket</a>
-        {% endif %}
+      {% if page and page.edit_url %}
+        <a href="{{ page.edit_url }}"
+        {%- if repo_name|lower == 'github' %}
+          class="icon icon-github"
+        {%- elif repo_name|lower == 'bitbucket' %}
+          class="icon icon-bitbucket"
+        {% endif %}> Edit on {{ repo_name }}</a>
       {% endif %}
       {%- endblock %}
     </li>