diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 099571a8..db832820 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -70,7 +70,7 @@ This new file is created on every MkDocs build (with `mkdocs build`) and no configuration is needed to enable it. [future release]: https://github.com/mkdocs/mkdocs/pull/481 -[site_dir]: /user-guide/configuration/#site_dir +[site_dir]: /user-guide/configuration.md#site_dir #### Change the pages configuration @@ -78,8 +78,8 @@ Provide a [new way] to define pages, and specifically [nested pages], in the mkdocs.yml file and deprecate the existing approach, support will be removed with MkDocs 1.0. -[new way]: /user-guide/writing-your-docs/#configure-pages-and-navigation -[nested pages]: /user-guide/writing-your-docs/#multilevel-documentation +[new way]: /user-guide/writing-your-docs.md#configure-pages-and-navigation +[nested pages]: /user-guide/writing-your-docs.md#multilevel-documentation #### Warn users about the removal of builtin themes @@ -98,7 +98,7 @@ JavaScript library [lunr.js]. It has been added to both the `mkdocs` and for adding it to your own themes. [lunr.js]: http://lunrjs.com/ -[supporting search]: /user-guide/styling-your-docs/#search-and-themes +[supporting search]: /user-guide/styling-your-docs.md#search-and-themes #### New Command Line Interface @@ -126,10 +126,10 @@ can also use Jinja2 syntax and take advantage of the [global variables]. By default MkDocs will use this approach to create a sitemap for the documentation. -[extra_javascript]: /user-guide/configuration/#extra_javascript -[extra_css]: /user-guide/configuration/#extra_css -[extra_templates]: /user-guide/configuration/#extra_templates -[global variables]: /user-guide/styling-your-docs/#global-context +[extra_javascript]: /user-guide/configuration.md#extra_javascript +[extra_css]: /user-guide/configuration.md#extra_css +[extra_templates]: /user-guide/configuration.md#extra_templates +[global variables]: /user-guide/styling-your-docs.md#global-context ### Other Changes and Additions @@ -145,8 +145,8 @@ documentation. * Bugfix: Fix linking to media within the same directory as a markdown file called index.md (#535) * Bugfix: Fix errors with unicode filenames (#542). -[extra config]: /user-guide/configuration/#extra -[Markdown extension configuration options]: /user-guide/configuration/#markdown_extensions +[extra config]: /user-guide/configuration.md#extra +[Markdown extension configuration options]: /user-guide/configuration.md#markdown_extensions [wheels]: http://pythonwheels.com/ diff --git a/docs/index.md b/docs/index.md index efa22f62..5000d924 100644 --- a/docs/index.md +++ b/docs/index.md @@ -169,4 +169,4 @@ To get help with MkDocs, please use the [discussion group], [GitHub issues] or t [GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually [pip]: http://pip.readthedocs.org/en/latest/installing.html [Python]: https://www.python.org/ -[Deploying your Docs]: user-guide/deploying-your-docs/ +[Deploying your Docs]: user-guide/deploying-your-docs.md diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 041f3fdd..d6c2316d 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -105,7 +105,7 @@ This setting is used to determine the set of pages that should be built for the - 'User Guide': 'user-guide.md' - 'About': 'about.md' -See the section on [configuring pages and navigation](/user-guide/writing-your-docs/#configure-pages-and-navigation) for a more detailed breakdown, including how to create sub-sections. +See the section on [configuring pages and navigation](/user-guide/writing-your-docs.md#configure-pages-and-navigation) for a more detailed breakdown, including how to create sub-sections. ## Build directories @@ -273,8 +273,8 @@ for that extension: **default**: `[]` -[custom themes]: /user-guide/styling-your-docs/#custom-themes -[variables that are available]: /user-guide/styling-your-docs/#global-context +[custom themes]: /user-guide/styling-your-docs.md#custom-themes +[variables that are available]: /user-guide/styling-your-docs.md#global-context [pymdk-extensions]: http://pythonhosted.org/Markdown/extensions/index.html [pymkd]: http://pythonhosted.org/Markdown/ [smarty]: https://pythonhosted.org/Markdown/extensions/smarty.html diff --git a/docs/user-guide/deploying-your-docs.md b/docs/user-guide/deploying-your-docs.md index 374896da..d137d4f0 100644 --- a/docs/user-guide/deploying-your-docs.md +++ b/docs/user-guide/deploying-your-docs.md @@ -58,7 +58,7 @@ public repository. [rtd]: https://readthedocs.org/ [instructions]: https://read-the-docs.readthedocs.org/en/latest/getting_started.html#in-markdown [features]: http://read-the-docs.readthedocs.org/en/latest/features.html -[theme]: /user-guide/styling-your-docs/ +[theme]: /user-guide/styling-your-docs.md ## PyPI diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md index 4f211069..93ed8e9e 100644 --- a/docs/user-guide/styling-your-docs.md +++ b/docs/user-guide/styling-your-docs.md @@ -12,9 +12,9 @@ To use a theme that is included in MkDocs, simply add this to your `mkdocs.yml` Replace [`amelia`](#amelia) with any of the [builtin themes](#built-in-themes) listed below. -To customise a theme, simply place additional CSS and JavaScript files in the documentation directory next to the Markdown files and these will be automatically detected and added. Additionally, the [`extra_css`](/user-guide/configuration/#extra_css) and [`extra_javascript`](/user-guide/configuration/#extra_javascript) configuration options can be used to specifically include certain CSS or JavaScript files. +To customise a theme, simply place additional CSS and JavaScript files in the documentation directory next to the Markdown files and these will be automatically detected and added. Additionally, the [`extra_css`](/user-guide/configuration.md#extra_css) and [`extra_javascript`](/user-guide/configuration.md#extra_javascript) configuration options can be used to specifically include certain CSS or JavaScript files. -See the [configuration documentation](/user-guide/configuration/#theme) for more specific details about these options. +See the [configuration documentation](/user-guide/configuration.md#theme) for more specific details about these options. To create a new custom theme or more heavily customise an existing theme, see the [custom themes](#custom-themes) section below. @@ -123,7 +123,7 @@ Each template in a theme is built with a template context. These are the variabl #### Global Context -The following variables in the context map directly the the [configuration options](/user-guide/configuration/). +The following variables in the context map directly the the [configuration options](/user-guide/configuration.md). Variable Name | Configuration name ----------------- | ------------------- | @@ -255,7 +255,7 @@ The page object for the next page.The isage is the same as for `current_page`. #### Extra Context -Additional variables can be passed to the template with the [`extra`](/user-guide/configuration/#extra) configuration option. This is a set of key value pairs that can make custom templates far more flexible. +Additional variables can be passed to the template with the [`extra`](/user-guide/configuration.md#extra) configuration option. This is a set of key value pairs that can make custom templates far more flexible. For example, this could be used to include the project version of all pages and a list of links related to the project. This can be achieved with the following `extra` configuration: diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md index b6c3e67f..0614a182 100644 --- a/docs/user-guide/writing-your-docs.md +++ b/docs/user-guide/writing-your-docs.md @@ -6,7 +6,7 @@ How to write and layout your markdown source files. ## Configure Pages and Navigation -The [pages configuration](/user-guide/configuration/#pages) in your `mkdocs.yml` defines which pages are built by MkDocs and how they appear in the documentation navigation. If not provided, the pages configuration will be automatically created by discovering all the Markdown files in the [documentation directory](/user-guide/configuration/#docs_dir). +The [pages configuration](/user-guide/configuration.md#pages) in your `mkdocs.yml` defines which pages are built by MkDocs and how they appear in the documentation navigation. If not provided, the pages configuration will be automatically created by discovering all the Markdown files in the [documentation directory](/user-guide/configuration.md#docs_dir). A simple pages configuration looks like this: diff --git a/mkdocs.yml b/mkdocs.yml index c33fdcb3..d5736eeb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,10 +4,22 @@ site_description: Project documentation with Markdown. repo_url: https://github.com/mkdocs/mkdocs/ +pages: +- Home: index.md +- User Guide: + - Writing Your Docs: user-guide/writing-your-docs.md + - Styling Your Docs: user-guide/styling-your-docs.md + - Configuration: user-guide/configuration.md + - Deploying your docs: user-guide/deploying-your-docs.md +- About: + - Release Notes: about/release-notes.md + - Contributing: about/contributing.md + - License: about/license.md + markdown_extensions: - toc: - permalink: "" + permalink:  - admonition: -copyright: Copyright © 2014, Tom Christie. Maintenance and development by Dougal Matthews +copyright: Copyright © 2014 Tom Christie, Dougal Matthews. google_analytics: ['UA-27795084-5', 'mkdocs.org'] diff --git a/mkdocs/relative_path_ext.py b/mkdocs/relative_path_ext.py index 59fecf8c..ab8fe901 100644 --- a/mkdocs/relative_path_ext.py +++ b/mkdocs/relative_path_ext.py @@ -35,8 +35,11 @@ tutorial/install.md | tutorial/install/ | ../img/initial-layout.png | tutorial/intro.md | tutorial/intro/ | ../../img/initial-layout.png | """ + from __future__ import unicode_literals + import logging +import os from markdown.extensions import Extension from markdown.treeprocessors import Treeprocessor @@ -68,6 +71,10 @@ def path_to_url(url, nav, strict): # If the site navigation has been provided, then validate # the internal hyperlink, making sure the target actually exists. target_file = nav.file_context.make_absolute(path) + + if target_file.startswith(os.path.sep): + target_file = target_file[1:] + if target_file not in nav.source_files: source_file = nav.file_context.current_file msg = ( diff --git a/mkdocs/tests/build_tests.py b/mkdocs/tests/build_tests.py index 9ee4bcac..d2bf0900 100644 --- a/mkdocs/tests/build_tests.py +++ b/mkdocs/tests/build_tests.py @@ -342,6 +342,17 @@ class BuildTests(unittest.TestCase): MarkdownNotFound, build.convert_markdown, invalid, load_config({'strict': True}), site_nav) + def test_absolute_link(self): + pages = [ + 'index.md', + 'sub/index.md', + ] + site_nav = nav.SiteNavigation(pages) + + markdown = "[test 1](/index.md) [test 2](/sub/index.md)" + cfg = load_config({'strict': True}) + build.convert_markdown(markdown, cfg, site_nav) + def test_extension_config(self): """ Test that a dictionary of 'markdown_extensions' is recognized as