diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 422e7c90..6fbebe23 100644 --- a/docs/user-guide/configuration.md +++ b/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. diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md index cd4d8e8a..10df837a 100644 --- a/docs/user-guide/custom-themes.md +++ b/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. diff --git a/mkdocs/commands/build.py b/mkdocs/commands/build.py index a4ce837c..83e1a1c6 100644 --- a/mkdocs/commands/build.py +++ b/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 diff --git a/mkdocs/config/config_options.py b/mkdocs/config/config_options.py index e9065e00..25dd8b09 100644 --- a/mkdocs/config/config_options.py +++ b/mkdocs/config/config_options.py @@ -202,6 +202,12 @@ class RepoURL(URL): 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): """ diff --git a/mkdocs/config/defaults.py b/mkdocs/config/defaults.py index 3d8c71e2..a5ff9d77 100644 --- a/mkdocs/config/defaults.py +++ b/mkdocs/config/defaults.py @@ -75,6 +75,12 @@ DEFAULT_SCHEMA = ( # "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. diff --git a/mkdocs/nav.py b/mkdocs/nav.py index 4c5b08f2..3b4da601 100644 --- a/mkdocs/nav.py +++ b/mkdocs/nav.py @@ -151,6 +151,7 @@ class Page(object): # 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 @@ class Page(object): 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): diff --git a/mkdocs/tests/config/config_options_tests.py b/mkdocs/tests/config/config_options_tests.py index 3c040102..05898b19 100644 --- a/mkdocs/tests/config/config_options_tests.py +++ b/mkdocs/tests/config/config_options_tests.py @@ -125,6 +125,27 @@ class RepoURLTest(unittest.TestCase): 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): diff --git a/mkdocs/themes/mkdocs/nav.html b/mkdocs/themes/mkdocs/nav.html index bf3a8e77..7def66d6 100644 --- a/mkdocs/themes/mkdocs/nav.html +++ b/mkdocs/themes/mkdocs/nav.html @@ -69,9 +69,9 @@ {%- endblock %} {%- block repo %} - {%- if repo_url %} + {%- if page and page.edit_url %}
  • - + {%- if repo_name == 'GitHub' %} {%- elif repo_name == 'Bitbucket' -%} diff --git a/mkdocs/themes/readthedocs/breadcrumbs.html b/mkdocs/themes/readthedocs/breadcrumbs.html index e1a4f3a9..c169cd6c 100644 --- a/mkdocs/themes/readthedocs/breadcrumbs.html +++ b/mkdocs/themes/readthedocs/breadcrumbs.html @@ -13,12 +13,13 @@ {% if page %}
  • {{ page.title }}
    • {% endif %}
  • {%- block repo %} - {% if repo_url %} - {% if repo_name == 'GitHub' %} - Edit on GitHub - {% elif repo_name == 'Bitbucket' %} - Edit on BitBucket - {% endif %} + {% if page and page.edit_url %} + Edit on {{ repo_name }} {% endif %} {%- endblock %}