initial commit

README.md

@@ -0,0 +1,57 @@
+# Example [MkDocs](http://mkdocs.org/) website using GitLab Pages.
+
+Learn more about GitLab Pages at https://pages.gitlab.io and the official
+documentation http://doc.gitlab.com/ee/pages/README.html.
+
+## GitLab CI
+
+This project's static Pages are built by [GitLab CI][ci], following the steps
+defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
+
+```
+image: python:alpine
+
+before_script:
+  - pip install mkdocs
+  # add your custom theme (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) if not inside a theme_dir
+  # - pip install mkdocs-material
+
+pages:
+  script:
+  - mkdocs build
+  - mv site public
+  artifacts:
+    paths:
+    - public
+  only:
+  - master
+```
+
+## Building locally
+
+To work locally with this project, you'll have to follow the steps below:
+
+1. Fork, clone or download this project
+1. [Install](http://www.mkdocs.org/#installation) MkDocs
+1. Preview your project: `mkdocs serve`
+1. Add content
+1. Generate the website: `mkdocs build` (optional)
+
+Read more at MkDocs's [documentation](http://www.mkdocs.org/).
+
+### Preview your site
+
+If you clone or download this project to your local computer and run `mkdocs serve`,
+your site can be accessed under `localhost:8000`.
+
+## GitLab User or Group Pages
+
+To use this project as your user/group website, you will need one additional
+step: just rename your project to `namespace.gitlab.io`, where `namespace` is
+your `username` or `groupname`. This can be done by navigating to your
+project's **Settings**.
+
+You'll need to configure your site too: change this line
+in your `mkdocs.yml`, from `"https://pages.gitlab.io/hugo/"` to `site_url = "https://namespace.gitlab.io"`.
+
+Read more about [user/group Pages][userpages] and [project Pages][projpages].

docs/CNAME

@@ -0,0 +1 @@
+www.mkdocs.org

docs/about/contributing.md

@@ -0,0 +1,69 @@
+# Contributing to MkDocs
+
+An introduction to contributing to the MkDocs project.
+
+The MkDocs project welcomes, and depends, on contributions from developers and
+users in the open source community. Contributions can be made in a number of
+ways, a few examples are:
+
+- Code patches via pull requests
+- Documentation improvements
+- Bug reports and patch reviews
+
+## Code of Conduct
+
+Everyone interacting in the MkDocs project's codebases, issue trackers, chat
+rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
+
+## Reporting an Issue
+
+Please include as much detail as you can. Let us know your platform and MkDocs
+version. If the problem is visual (for example a theme or design issue) please
+add a screenshot and if you get an error please include the full error and
+traceback.
+
+## Testing the Development Version
+
+If you want to just install and try out the latest development version of
+MkDocs you can do so with the following command. This can be useful if you
+want to provide feedback for a new feature or want to confirm if a bug you
+have encountered is fixed in the git master. It is **strongly** recommended
+that you do this within a [virtualenv].
+
+```bash
+pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz
+```
+
+## Installing for Development
+
+First you'll need to fork and clone the repository. Once you have a local
+copy, run the following command. It is **strongly** recommended that you do
+this within a [virtualenv].
+
+```bash
+pip install --editable .
+```
+
+This will install MkDocs in development mode which binds the `mkdocs` command
+to the git repository.
+
+## Running the tests
+
+To run the tests, it is recommended that you use [Tox]. This just needs
+to be pip installed and then the test suite can be ran for MkDocs but running
+the command `tox` in the root of your MkDocs repository.
+
+It will attempt to run the tests against all of the Python versions we
+support. So don't be concerned if you are missing some and they fail. The rest
+will be verified by [Travis] when you submit a pull request.
+
+## Submitting Pull Requests
+
+Once you are happy with your changes or you are ready for some feedback, push
+it to your fork and send a pull request. For a change to be accepted it will
+most likely need to have tests and documentation if it is a new feature.
+
+[virtualenv]: https://virtualenv.pypa.io/en/latest/userguide.html
+[tox]: https://tox.readthedocs.io/en/latest/
+[travis]: https://travis-ci.org/repositories
+[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/

docs/about/license.md

@@ -0,0 +1,37 @@
+# License
+
+The legal stuff.
+
+---
+
+## Included projects
+
+Themes used under license from the ReadTheDocs projects.
+
+* ReadTheDocs theme - [View license](https://github.com/snide/sphinx_rtd_theme/blob/master/LICENSE).
+
+Many thanks to the authors and contributors of those wonderful projects.
+
+## MkDocs License (BSD)
+
+Copyright © 2014, Tom Christie. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list
+of conditions and the following disclaimer. Redistributions in binary form must
+reproduce the above copyright notice, this list of conditions and the following
+disclaimer in the documentation and/or other materials provided with the
+distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/about/release-notes.md

@@ -0,0 +1,542 @@
+# Release Notes
+
+---
+
+## Upgrading
+
+To upgrade MkDocs to the latest version, use pip:
+
+    pip install -U mkdocs
+
+You can determine your currently installed version using `mkdocs --version`:
+
+    $ mkdocs --version
+    mkdocs, version 0.15.2
+
+## Maintenance team
+
+The current and past members of the MkDocs team.
+
+* [@tomchristie](https://github.com/tomchristie/)
+* [@d0ugal](https://github.com/d0ugal/)
+* [@waylan](https://github.com/waylan/)
+
+## Version 0.16.1 (2016-12-22)
+
+* Ensure scrollspy behavior does not affect nav bar (#1094)
+* Only "load" a theme when it is explicitly requested by the user (#1105)
+
+## Version 0.16 (2016-11-04)
+
+### Major Additions to Version 0.16.0
+
+#### Template variables refactored. (#874)
+
+##### Page Context
+
+Page specific variable names in the template context have been refactored as
+defined in [Custom Themes](../user-guide/custom-themes/#page). The
+old variable names will issue a warning but continue to work for version 0.16,
+but may be removed in a future version.
+
+Any of the following old page variables should be updated to the new ones in
+user created and third-party templates:
+
+| Old Variable Name | New Variable Name   |
+| ----------------- | ------------------- |
+| current_page      | [page]              |
+| page_title        | [page.title]        |
+| content           | [page.content]      |
+| toc               | [page.toc]          |
+| meta              | [page.meta]         |
+| canonical_url     | [page.canonical_url]|
+| previous_page     | [page.previous_page]|
+| next_page         | [page.next_page]    |
+
+[page]: ../user-guide/custom-themes/#page
+[page.title]: ../user-guide/custom-themes/#pagetitle
+[page.content]: ../user-guide/custom-themes/#pagecontent
+[page.toc]: ../user-guide/custom-themes/#pagetoc
+[page.meta]: ../user-guide/custom-themes/#pagemeta
+[page.canonical_url]: ../user-guide/custom-themes/#pagecanonical_url
+[page.previous_page]: ../user-guide/custom-themes/#pageprevious_page
+[page.next_page]: ../user-guide/custom-themes/#pagenext_page
+
+##### Global Context
+
+Additionally, a number of global variables have been altered and/or deprecated
+and user created and third-party templates should be updated as outlined below:
+
+Previously, the global variable `include_nav` was altered programmatically based
+on the number of pages in the nav. The variable will issue a warning but
+continue to work for version 0.16, but may be removed in a future version. Use
+`{% if nav|length>1 %}` instead.
+
+Previously, the global variable `include_next_prev` was altered programmatically
+based on the number of pages in the nav. The variable will issue a warning but
+continue to work for version 0.16, but may be removed in a future version. Use
+`{% if page.next_page or page.previous_page %}` instead.
+
+Previously the global variable `page_description` was altered programmatically
+based on whether the current page was the homepage. Now it simply maps to
+`config['site_description']`. Use `{% if page.is_homepage %}` in the template to
+conditionally change the description.
+
+The global variable `homepage_url` maps directly to `nav.homepage.url` and is
+being deprecated. The variable will issue a warning but continue to work for
+version 0.16, but may be removed in a future version. Use `nav.homepage.url`
+instead.
+
+The global variable `favicon` maps to the configuration setting `site_favicon`.
+Both the template variable and the configuration setting are being deprecated
+and will issue a warning but continue to work for version 0.16, and may be
+removed in a future version. Use `{{ base_url }}/img/favicon.ico` in your
+template instead. Users can simply save a copy of their custom favicon icon to
+`img/favicon.ico` in either their `docs_dir` or `theme_dir`.
+
+A number of variables map directly to similarly named variables in the `config`.
+Those variables are being deprecated and will issue a warning but continue to
+work for version 0.16, but may be removed in a future version. Use
+`config.var_name` instead, where `var_name` is the name of one of the
+[configuration] variables.
+
+[configuration]: /user-guide/configuration.md
+
+Below is a summary of all of the changes made to the global context:
+
+| Old Variable Name | New Variable Name or Expression        |
+| ----------------- | -------------------------------------- |
+| current_page      | page                                   |
+| include_nav       | nav|length>1                   |
+| include_next_prev | (page.next_page or page.previous_page) |
+| site_name         | config.site_name                       |
+| site_author       | config.site_author                     |
+| page_description  | config.site_description                |
+| repo_url          | config.repo_url                        |
+| repo_name         | config.repo_name                       |
+| site_url          | config.site_url                        |
+| copyright         | config.copyright                       |
+| google_analytics  | config.google_analytics                |
+| homepage_url      | nav.homepage.url                       |
+| favicon           | {{ base_url }}/img/favicon.ico         |
+
+#### Increased Template Customization. (#607)
+
+The built-in themes have been updated by having each of their many parts wrapped
+in template blocks which allow each individual block to be easily overridden
+using the `theme_dir` config setting. Without any new settings, you can use a
+different analytics service, replace the default search function, or alter the
+behavior of the navigation, among other things. See the relevant
+[documentation][blocks] for more details.
+
+To enable this feature, the primary entry point for page templates has been
+changed from `base.html` to `main.html`. This allows `base.html` to continue to
+exist while allowing users to override `main.html` and extend `base.html`. For
+version 0.16, `base.html` will continue to work if no `main.html` template
+exists, but it is deprecated and will raise a warning. In version 1.0, a build
+will fail if no `main.html` template exists. Any custom and third party
+templates should be updated accordingly.
+
+The easiest way for a third party theme to be updated would be to simply add a
+`main.html` file which only contains the following line:
+
+```django
+{% extends "base.html" %}
+```
+
+That way, the theme contains the `main.html` entry point, and also supports
+overriding blocks in the same manner as the built-in themes. Third party themes
+are encouraged to wrap the various pieces of their templates in blocks in order
+to support such customization.
+
+[blocks]: ../user-guide/styling-your-docs/#overriding-template-blocks
+
+#### Auto-Populated `extra_css` and `extra_javascript` Deprecated. (#986)
+
+In previous versions of MkDocs, if the `extra_css` or `extra_javascript` config
+settings were empty, MkDocs would scan the `docs_dir` and auto-populate each
+setting with all of the CSS and JavaScript files found. This behavior is
+deprecated and a warning will be issued. In the next release, the auto-populate
+feature will stop working and any unlisted CSS and JavaScript files will not be
+included in the HTML templates. In other words, they will still be copied to the
+`site-dir`, but they will not have any effect on the theme if they are not
+explicitly listed.
+
+All CSS and javaScript files in the `docs_dir` should be explicitly listed in
+the `extra_css` or `extra_javascript` config settings going forward.
+
+#### Support for dirty builds. (#990)
+
+For large sites the build time required to create the pages can become problematic,
+thus a "dirty" build mode was created. This mode simply compares the modified time
+of the generated HTML and source markdown. If the markdown has changed since the
+HTML then the page is re-constructed. Otherwise, the page remains as is. This mode
+may be invoked in both the `mkdocs serve` and `mkdocs build` commands:
+
+```text
+mkdocs serve --dirtyreload
+```
+
+```text
+mkdocs build --dirty
+```
+
+It is important to note that this method for building the pages is for development
+of content only, since the navigation and other links do not get updated on other
+pages.
+
+#### Stricter Directory Validation
+
+Previously, a warning was issued if the `site_dir` was a child directory of the
+`docs_dir`. This now raises an error. Additionally, an error is now raised if
+the `docs_dir` is set to the directory which contains your config file rather
+than a child directory. You will need to rearrange you directory structure to
+better conform with the documented [layout].
+
+[layout]: ../user-guide/writing-your-docs/#file-layout
+
+### Other Changes and Additions to Version 0.16.0
+
+* Bugfix: Support `gh-deploy` command on Windows with Python 3 (#722)
+* Bugfix: Include .woff2 font files in Python package build (#894)
+* Various updates and improvements to Documentation Home Page/Tutorial (#870)
+* Bugfix: Support livereload for config file changes (#735)
+* Bugfix: Non-media template files are no longer copied with media files (#807)
+* Add a flag (-e/--theme-dir) to specify theme directory with the commands
+  `mkdocs build` and `mkdocs serve` (#832)
+* Fixed issues with Unicode file names under Windows and Python 2. (#833)
+* Improved the styling of in-line code in the MkDocs theme. (#718)
+* Bugfix: convert variables to JSON when being passed to JavaScript (#850)
+* Updated the ReadTheDocs theme to match the upstream font sizes and colors
+  more closely. (#857)
+* Fixes an issue with permalink markers showing when the mouse was far above
+  them (#843)
+* Bugfix: Handle periods in directory name when automatically creating the
+  pages config. (#728)
+* Update searching to Lunr 0.7, which comes with some performance enhancements
+  for larger documents (#859)
+* Bugfix: Support SOURCE_DATE_EPOCH environment variable for "reproducible"
+  builds (#938)
+* Follow links when copying media files (#869).
+* Change "Edit on..." links to point directly to the file in the source
+  repository, rather than to the root of the repository (#975), configurable
+  via the new [`edit_uri`](../user-guide/configuration.md#edit_uri) setting.
+* Bugfix: Don't override config value for strict mode if not specified on CLI
+  (#738).
+* Add a `--force` flag to the `gh-deploy` command to force the push to the
+  repository (#973).
+* Improve alignment for current selected menu item in readthedocs theme (#888).
+* `http://user.github.io/repo` => `https://user.github.io/repo/` (#1029).
+* Improve installation instructions (#1028).
+* Account for wide tables and consistently wrap inline code spans (#834).
+* Bugfix: Use absolute URLs in nav & media links from error templates (#77).
+
+## Version 0.15.3 (2016-02-18)
+
+* Improve the error message the given theme can't be found.
+* Fix an issue with relative symlinks (#639)
+
+## Version 0.15.2 (2016-02-08)
+
+* Fix an incorrect warning that states external themes [will be removed from
+  MkDocs](#add-support-for-installable-themes).
+
+## Version 0.15.1 (2016-01-30)
+
+* Lower the minimum supported Click version to 3.3 for package maintainers.
+  (#763)
+
+## Version 0.15.0 (2016-01-21)
+
+### Major Additions to Version 0.15.0
+
+#### Add support for installable themes
+
+MkDocs now supports themes that are distributed via Python packages. With this
+addition, the Bootstrap and Bootswatch themes have been moved to external git
+repositories and python packages. See their individual documentation for more
+details about these specific themes.
+
+* [MkDocs Bootstrap]
+* [MkDocs Bootswatch]
+
+[MkDocs Bootstrap]: http://mkdocs.github.io/mkdocs-bootstrap/
+[MkDocs Bootswatch]: http://mkdocs.github.io/mkdocs-bootswatch/
+
+They will be included with MkDocs by default until a future release. After that
+they will be installable with pip: `pip install mkdocs-bootstrap` and `pip
+install mkdocs-bootswatch`
+
+See the documentation for [Styling your docs] for more information about using
+and customising themes and [Custom themes] for creating and distributing new
+themes
+
+[Styling your docs]: /user-guide/styling-your-docs.md
+[Custom themes]: /user-guide/custom-themes.md
+
+### Other Changes and Additions to Version 0.15.0
+
+* Fix issues when using absolute links to Markdown files. (#628)
+* Deprecate support of Python 2.6, pending removal in 1.0.0. (#165)
+* Add official support for Python version 3.5.
+* Add support for [site_description] and [site_author] to the [ReadTheDocs]
+  theme. (#631)
+* Update FontAwesome to 4.5.0. (#789)
+* Increase IE support with X-UA-Compatible. (#785)
+* Added support for Python's `-m` flag. (#706)
+* Bugfix: Ensure consistent ordering of auto-populated pages. (#638)
+* Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long
+  for the page. (#204)
+* Bugfix: Add all ancestors to the page attribute `ancestors` rather than just
+  the initial one. (#693)
+* Bugfix: Include HTML in the build output again. (#691)
+* Bugfix: Provide filename to Read the Docs. (#721 and RTD#1480)
+* Bugfix: Silence Click's unicode_literals warning. (#708)
+
+[site_description]: /user-guide/configuration.md#site_description
+[site_author]: /user-guide/configuration.md#site_author
+[ReadTheDocs]: /user-guide/styling-your-docs.md#readthedocs
+
+## Version 0.14.0 (2015-06-09)
+
+* Improve Unicode handling by ensuring that all config strings are loaded as
+  Unicode. (#592)
+* Remove dependancy on the six library. (#583)
+* Remove dependancy on the ghp-import library. (#547)
+* Add `--quiet` and `--verbose` options to all subcommands. (#579)
+* Add short options (`-a`) to most command line options. (#579)
+* Add copyright footer for readthedocs theme. (#568)
+* If the requested port in `mkdocs serve` is already in use, don't show the
+  user a full stack trace. (#596)
+* Bugfix: Fix a JavaScript encoding problem when searching with spaces. (#586)
+* Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root.
+  (#578)
+* Bugfix: Handle (pass-through instead of dropping) HTML entities while
+  parsing TOC. (#612)
+* Bugfix: Default extra_templates to an empty list, don't automatically
+  discover them. (#616)
+
+## Version 0.13.3 (2015-06-02)
+
+* Bugfix: Reduce validation error to a warning if the site_dir is within
+  the docs_dir as this shouldn't cause any problems with building but will
+  inconvenience users building multiple times. (#580)
+
+## Version 0.13.2 (2015-05-30)
+
+* Bugfix: Ensure all errors and warnings are logged before exiting. (#536)
+* Bugfix: Fix compatibility issues with ReadTheDocs. (#554)
+
+## Version 0.13.1 (2015-05-27)
+
+* Bugfix: Fix a problem with minimal configurations which only contain a list
+  of paths in the pages config. (#562)
+
+## Version 0.13.0 (2015-05-26)
+
+### Deprecations to Version 0.13.0
+
+#### Deprecate the JSON command
+
+In this release the  `mkdocs json` command has been marked as deprecated and
+when used a deprecation warning will be shown. It will be removed in a [future
+release] of MkDocs, version 1.0 at the latest. The `mkdocs json` command
+provided  a convenient way for users to output the documentation contents as
+JSON files but with the additions of search to MkDocs this functionality is
+duplicated.
+
+A new index with all the contents from a MkDocs build is created in the
+[site_dir], so with the default value for the `site_dir` It can be found in
+`site/mkdocs/search_index.json`.
+
+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.md#site_dir
+
+#### Change the pages configuration
+
+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.md#configure-pages-and-navigation
+[nested pages]: /user-guide/writing-your-docs.md#multilevel-documentation
+
+#### Warn users about the removal of builtin themes
+
+All themes other than mkdocs and readthedocs will be moved into external
+packages in a future release of MkDocs. This will enable them to be more easily
+supported and updates outside MkDocs releases.
+
+### Major Additions to Version 0.13.0
+
+#### Search
+
+Support for search has now been added to MkDocs. This is based on the
+JavaScript library [lunr.js]. It has been added to both the `mkdocs` and
+`readthedocs` themes. See the custom theme documentation on [supporting search]
+for adding it to your own themes.
+
+[lunr.js]: http://lunrjs.com/
+[supporting search]: /user-guide/styling-your-docs.md#search-and-themes
+
+#### New Command Line Interface
+
+The command line interface for MkDocs has been re-written with the Python
+library [Click]. This means that MkDocs now has an easier to use interface
+with better help output.
+
+This change is partially backwards incompatible as while undocumented it was
+possible to pass any configuration option to the different commands. Now only
+a small subset of the configuration options can be passed to the commands. To
+see in full commands and available arguments use `mkdocs --help` and
+`mkdocs build --help` to have them displayed.
+
+[Click]: http://click.pocoo.org/4/
+
+#### Support Extra HTML and XML files
+
+Like the [extra_javascript] and [extra_css] configuration options, a new
+option named [extra_templates] has been added. This will automatically be
+populated with any `.html` or `.xml` files in the project docs directory.
+
+Users can place static HTML and XML files and they will be copied over, or they
+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.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 to Version 0.13.0
+
+* Add support for [Markdown extension configuration options]. (#435)
+* MkDocs now ships Python [wheels]. (#486)
+* Only include the build date and MkDocs version on the homepage. (#490)
+* Generate sitemaps for documentation builds. (#436)
+* Add a clearer way to define nested pages in the configuration. (#482)
+* Add an [extra config] option for passing arbitrary variables to the template. (#510)
+* Add `--no-livereload` to `mkdocs serve` for a simpler development server. (#511)
+* Add copyright display support to all themes (#549)
+* Add support for custom commit messages in a `mkdocs gh-deploy` (#516)
+* 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.md#extra
+[Markdown extension configuration options]: /user-guide/configuration.md#markdown_extensions
+[wheels]: http://pythonwheels.com/
+
+## Version 0.12.2 (2015-04-22)
+
+* Bugfix: Fix a regression where there would be an error if some child titles
+  were missing but others were provided in the pages config. (#464)
+
+## Version 0.12.1 (2015-04-14)
+
+* Bugfix: Fixed a CSS bug in the table of contents on some browsers where the
+  bottom item was not clickable.
+
+## Version 0.12.0 (2015-04-14)
+
+* Display the current MkDocs version in the CLI output. (#258)
+* Check for CNAME file when using gh-deploy. (#285)
+* Add the homepage back to the navigation on all themes. (#271)
+* Add a strict more for local link checking. (#279)
+* Add Google analytics support to all themes. (#333)
+* Add build date and MkDocs version to the ReadTheDocs and MkDocs theme
+  outputs. (#382)
+* Standardise highlighting across all themes and add missing languages. (#387)
+* Add a verbose flag. (-v) to show more details about what the build. (#147)
+* Add the option to specify a remote branch when deploying to GitHub. This
+  enables deploying to GitHub pages on personal and repo sites. (#354)
+* Add favicon support to the ReadTheDocs theme HTML. (#422)
+* Automatically refresh the browser when files are edited. (#163)
+* Bugfix: Never re-write URL's in code blocks. (#240)
+* Bugfix: Don't copy ditfiles when copying media from the `docs_dir`. (#254)
+* Bugfix: Fix the rendering of tables in the ReadTheDocs theme. (#106)
+* Bugfix: Add padding to the bottom of all bootstrap themes. (#255)
+* Bugfix: Fix issues with nested Markdown pages and the automatic pages
+  configuration. (#276)
+* Bugfix: Fix a URL parsing error with GitHub enterprise. (#284)
+* Bugfix: Don't error if the mkdocs.yml is completely empty. (#288)
+* Bugfix: Fix a number of problems with relative urls and Markdown files. (#292)
+* Bugfix: Don't stop the build if a page can't be found, continue with other
+  pages. (#150)
+* Bugfix: Remove the site_name from the page title, this needs to be added
+  manually. (#299)
+* Bugfix: Fix an issue with table of contents cutting off Markdown. (#294)
+* Bugfix: Fix hostname for BitBucket. (#339)
+* Bugfix: Ensure all links end with a slash. (#344)
+* Bugfix: Fix repo links in the readthedocs theme. (#365)
+* Bugfix: Include jQuery locally to avoid problems using MkDocs offline. (#143)
+* Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. (#384)
+* Bugfix: Remove inline CSS in the ReadTheDocs theme. (#393)
+* Bugfix: Fix problems with the child titles due to the order the pages config
+  was processed. (#395)
+* Bugfix: Don't error during live reload when the theme doesn't exist. (#373)
+* Bugfix: Fix problems with the Meta extension when it may not exist. (#398)
+* Bugfix: Wrap long inline code otherwise they will run off the screen. (#313)
+* Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to
+  fix problems with titles containing code. (#367)
+* Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden
+  under the navigation. (#7)
+* Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. (#295)
+* Bugfix: Fix an error when passing in a specific config file with
+  `mkdocs serve`. (#341)
+* Bugfix: Don't overwrite index.md diles with the `mkdocs new` command. (#412)
+* Bugfix: Remove bold and italic from code in the ReadTheDocs theme. (#411)
+* Bugfix: Display images inline in the MkDocs theme. (#415)
+* Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. (#319)
+* Bugfix: Don't delete hidden files when using `mkdocs build --clean`. (#346)
+* Bugfix: Don't block newer verions of Python-markdown on Python >= 2.7. (#376)
+* Bugfix: Fix encoding issues when opening files across platforms. (#428)
+
+## Version 0.11.1 (2014-11-20)
+
+* Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs
+  theme. (#233)
+
+## Version 0.11.0 (2014-11-18)
+
+* Render 404.html files if they exist for the current theme. (#194)
+* Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs
+  and ReadTheDocs themes. (#225)
+* Bugfix: Fix an issue with the google_analytics code. (#219)
+* Bugfix: Remove `__pycache__` from the package tar. (#196)
+* Bugfix: Fix markdown links that go to an anchor on the current page. (#197)
+* Bugfix: Don't add `prettyprint well` CSS classes to all HTML, only add it in
+  the MkDocs theme. (#183)
+* Bugfix: Display section titles in the ReadTheDocs theme. (#175)
+* Bugfix: Use the polling observer in watchdog so rebuilding works on
+  filesystems without inotify. (#184)
+* Bugfix: Improve error output for common configuration related errors. (#176)
+
+## Version 0.10.0 (2014-10-29)
+
+* Added support for Python 3.3 and 3.4. (#103)
+* Configurable Python-Markdown extensions with the config setting
+  `markdown_extensions`. (#74)
+* Added `mkdocs json` command to output your rendered
+  documentation as json files. (#128)
+* Added `--clean` switch to `build`, `json` and `gh-deploy` commands to
+  remove stale files from the output directory. (#157)
+* Support multiple theme directories to allow replacement of
+  individual templates rather than copying the full theme. (#129)
+* Bugfix: Fix `<ul>` rendering in readthedocs theme. (#171)
+* Bugfix: Improve the readthedocs theme on smaller displays. (#168)
+* Bugfix: Relaxed required python package versions to avoid clashes. (#104)
+* Bugfix: Fix issue rendering the table of contents with some configs. (#146)
+* Bugfix: Fix path for embedded images in sub pages. (#138)
+* Bugfix: Fix `use_directory_urls` config behaviour. (#63)
+* Bugfix: Support `extra_javascript` and `extra_css` in all themes. (#90)
+* Bugfix: Fix path-handling under Windows. (#121)
+* Bugfix: Fix the menu generation in the readthedocs theme. (#110)
+* Bugfix: Fix the mkdocs command creation under Windows. (#122)
+* Bugfix: Correctly handle external `extra_javascript` and `extra_css`. (#92)
+* Bugfix: Fixed favicon support. (#87)

docs/css/extra.css

@@ -0,0 +1,21 @@
+div.col-md-9 h1:first-of-type {
+    text-align: center;
+    font-size: 60px;
+    font-weight: 300;
+}
+
+div.col-md-9 p:first-of-type {
+    text-align: center;
+}
+
+div.col-md-9 p.admonition-title:first-of-type {
+    text-align: left;
+}
+
+div.col-md-9 h1:first-of-type .headerlink {
+    display: none;
+}
+
+code.no-highlight {
+    color: black;
+}

docs/index.md

@@ -0,0 +1,352 @@
+# MkDocs
+
+Project documentation with Markdown.
+
+---
+
+!!! Note
+	This site was built with GitLab Pages!.
+
+	Visit this project at [https://gitlab.com/pages/mkdocs](https://gitlab.com/pages/mkdocs).
+
+## Overview
+
+MkDocs is a **fast**, **simple** and **downright gorgeous** static site
+generator that's geared towards building project documentation. Documentation
+source files are written in Markdown, and configured with a single YAML
+configuration file.
+
+### Host anywhere
+
+MkDocs builds completely static HTML sites that you can host on GitHub pages,
+Amazon S3, or [anywhere][deploy] else you choose.
+
+### Great themes available
+
+There's a stack of good looking themes available for MkDocs. Choose between
+the built in themes: [mkdocs] and [readthedocs], select one of the 3rd
+party themes in the [MkDocs wiki], or [build your own].
+
+### Preview your site as you work
+
+The built-in dev-server allows you to preview your documentation as you're
+writing it. It will even auto-reload and refresh your browser whenever you save
+your changes.
+
+### Easy to customize
+
+Get your project documentation looking just the way you want it by customizing
+the theme.
+
+---
+
+## Installation
+
+### Install with a Package Manager
+
+If you have and use a package manager (such as [apt-get], [dnf], [homebrew],
+[yum], [chocolatey], etc.) to install packages on your system, then you may
+want to search for a "MkDocs" package and, if a recent version is available,
+install it with your package manager (check your system's documentation for
+details). That's it, you're done! Skip down to [Getting Started](#getting-started).
+
+If your package manager does not have a recent "MkDocs" package, you can still
+use your package manager to install "Python" and "pip". Then you can use pip to
+[install MkDocs](#installing-mkdocs).
+
+[apt-get]: https://help.ubuntu.com/community/AptGet/Howto
+[homebrew]: http://brew.sh/
+[dnf]: http://dnf.readthedocs.io/en/latest/index.html
+[yum]: http://yum.baseurl.org/
+[chocolatey]: https://chocolatey.org/
+
+### Manual Installation
+
+In order to manually install MkDocs you'll need [Python] installed on your
+system, as well as the Python package manager, [pip]. You can check if you have
+these already installed from the command line:
+
+```bash
+$ python --version
+Python 2.7.2
+$ pip --version
+pip 1.5.2
+```
+
+MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.
+
+#### Installing Python
+
+Install [Python] by downloading an installer appropriate for your system from
+[python.org] and running it.
+
+!!! Note
+
+    If you are installing Python on Windows, be sure to check the box to have
+    Python added to your PATH if the installer offers such an option (it's
+    normally off by default).
+
+    ![Add Python to PATH](img/win-py-install.png)
+
+[python.org]: https://www.python.org/downloads/
+
+#### Installing pip
+
+If you're using a recent version of Python, the Python package manager, [pip],
+is most likely installed by default. However, you may need to upgrade pip to the
+lasted version:
+
+```bash
+pip install --upgrade pip
+```
+
+If you need to install [pip] for the first time, download [get-pip.py].
+Then run the following command to install it:
+
+```bash
+python get-pip.py
+```
+
+#### Installing MkDocs
+
+Install the `mkdocs` package using pip:
+
+```bash
+pip install mkdocs
+```
+
+You should now have the `mkdocs` command installed on your system. Run `mkdocs
+--version` to check that everything worked okay.
+
+```bash
+$ mkdocs --version
+mkdocs, version 0.15.3
+```
+
+!!! Note
+    If you are using Windows, some of the above commands may not work
+    out-of-the-box.
+
+    A quick solution may be to preface every Python command with `python -m`
+    like this:
+
+        python -m pip install mkdocs
+        python -m mkdocs
+
+    For a more permanent solution, you may need to edit your `PATH` environment
+    variable to include the `Scripts` directory of your Python installation.
+    Recent versions of Python include a script to do this for you. Navigate to
+    your Python installation directory (for example `C:\Python34\`), open the
+    `Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double
+    clicking on it. Alternatively, you can [download][a2p] the script and run it
+    (`python win_add2path.py`).
+
+[a2p]: https://svn.python.org/projects/python/trunk/Tools/scripts/win_add2path.py
+
+---
+
+## Getting Started
+
+Getting started is super easy.
+
+```bash
+mkdocs new my-project
+cd my-project
+```
+
+Take a moment to review the initial project that has been created for you.
+
+![The initial MkDocs layout](img/initial-layout.png)
+
+There's a single configuration file named `mkdocs.yml`, and a folder named
+`docs` that will contain your documentation source files. Right now the `docs`
+folder just contains a single documentation page, named `index.md`.
+
+MkDocs comes with a built-in dev-server that lets you preview your documentation
+as you work on it. Make sure you're in the same directory as the `mkdocs.yml`
+configuration file, and then start the server by running the `mkdocs serve`
+command:
+
+```bash
+$ mkdocs serve
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
+[I 160402 15:50:43 handlers:58] Start watching changes
+[I 160402 15:50:43 handlers:60] Start detecting changes
+```
+
+Open up `http://127.0.0.1:8000/` in your browser, and you'll see the default
+home page being displayed:
+
+![The MkDocs live server](img/screenshot.png)
+
+The dev-server also supports auto-reloading, and will rebuild your documentation
+whenever anything in the configuration file, documentation directory, or theme
+directory changes.
+
+Open the `docs/index.md` document in your text editor of choice, change the
+initial heading to `MkLorum`, and save your changes. Your browser will
+auto-reload and you should see your updated documentation immediately.
+
+Now try editing the configuration file: `mkdocs.yml`. Change the
+[`site_name`][site_name] setting to `MkLorum` and save the file.
+
+```yaml
+site_name: MkLorum
+```
+
+Your browser should immediately reload, and you'll see your new site name take
+effect.
+
+![The site_name setting](img/site-name.png)
+
+## Adding pages
+
+Now add a second page to your documentation:
+
+```bash
+curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
+```
+
+As our documentation site will include some navigation headers, you may want to
+edit the configuration file and add some information about the order, title, and
+nesting of each page in the navigation header by adding a [`pages`][pages]
+setting:
+
+```yaml
+site_name: MkLorum
+pages:
+    - Home: index.md
+    - About: about.md
+```
+
+Save your changes and you'll now see a navigation bar with `Home` and `About`
+items on the left as well as `Search`, `Previous`, and `Next` items on the
+right.
+
+![Screenshot](img/multipage.png)
+
+Try the menu items and navigate back and forth between pages. Then click on
+`Search`. A search dialog will appear, allowing you to search for any text on
+any page. Notice that the search results include every occurrence of the search
+term on the site and links directly to the section of the page in which the
+search term appears. You get of all that with no effort or configuration on your
+part!
+
+![Screenshot](img/search.png)
+
+## Theming our documentation
+
+Now change the configuration file to alter how the documentation is displayed by
+changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting:
+
+```yaml
+site_name: MkLorum
+pages:
+    - Home: index.md
+    - About: about.md
+theme: readthedocs
+```
+
+Save your changes, and you'll see the ReadTheDocs theme being used.
+
+![Screenshot](img/readthedocs.png)
+
+## Changing the Favicon Icon
+
+By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create
+an `img` subdirectory in your `docs_dir` and copy your custom `favicon.ico` file
+to that directory. MkDocs will automaticaly detect and use that file as your
+favicon icon.
+
+[MkDocs favicon]: /img/favicon.ico
+
+## Building the site
+
+That's looking good. You're ready to deploy the first pass of your `MkLorum`
+documentation. First build the documentation:
+
+```bash
+mkdocs build
+```
+
+This will create a new directory, named `site`. Take a look inside the
+directory:
+
+```bash
+$ ls site
+about  fonts  index.html  license  search.html
+css    img    js          mkdocs   sitemap.xml
+```
+
+Notice that your source documentation has been output as two HTML files named
+`index.html` and `about/index.html`. You also have various other media that's
+been copied into the `site` directory as part of the documentation theme. You
+even have a `sitemap.xml` file and `mkdocs/search_index.json`.
+
+If you're using source code control such as `git` you probably don't want to
+check your documentation builds into the repository. Add a line containing
+`site/` to your `.gitignore` file.
+
+```bash
+echo "site/" >> .gitignore
+```
+
+If you're using another source code control tool you'll want to check it's
+documentation on how to ignore specific directories.
+
+After some time, files may be removed from the documentation but they will still
+reside in the `site` directory. To remove those stale files, just run `mkdocs`
+with the `--clean` switch.
+
+```bash
+mkdocs build --clean
+```
+
+## Other Commands and Options
+
+There are various other commands and options available. For a complete list of
+commands, use the `--help` flag:
+
+```bash
+mkdocs --help
+```
+
+To view a list of options available on a given command, use the `--help` flag
+with that command. For example, to get a list of all options available for the
+`build` command run the following:
+
+```bash
+mkdocs build --help
+```
+
+## Deploying
+
+The documentation site that you just built only uses static files so you'll be
+able to host it from pretty much anywhere. [GitHub project pages] and [Amazon
+S3] may be good hosting options, depending upon your needs. Upload the contents
+of the entire `site` directory to wherever you're hosting your website from and
+you're done. For specific instructions on a number of common hosts, see the
+[Deploying your Docs][deploy] page.
+
+## Getting help
+
+To get help with MkDocs, please use the [discussion group], [GitHub issues] or
+the MkDocs IRC channel `#mkdocs` on freenode.
+
+[deploy]: user-guide/deploying-your-docs/
+[mkdocs]: user-guide/styling-your-docs/#mkdocs
+[readthedocs]: user-guide/styling-your-docs/#readthedocs
+[MkDocs wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
+[build your own]: user-guide/custom-themes/
+[Amazon S3]: http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html
+[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
+[pages]: user-guide/configuration/#pages
+[discussion group]: https://groups.google.com/forum/#!forum/mkdocs
+[GitHub issues]: https://github.com/mkdocs/mkdocs/issues
+[GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually/
+[pip]: http://pip.readthedocs.io/en/stable/installing/
+[Python]: https://www.python.org/
+[site_name]: user-guide/configuration/#site_name
+[theme]: user-guide/configuration/#theme

docs/user-guide/configuration.md

@@ -0,0 +1,380 @@
+# Configuration
+
+Guide to all available configuration settings.
+
+---
+
+## Introduction
+
+Project settings are always configured by using a YAML configuration file in the
+project directory named `mkdocs.yml`.
+
+As a minimum this configuration file must contain the `site_name` setting. All
+other settings are optional.
+
+## Project information
+
+### site_name
+
+This is a **required setting**, and should be a string that is used as the main
+title for the project documentation. For example:
+
+```yaml
+site_name: Marshmallow Generator
+```
+
+When rendering the theme this setting will be passed as the `site_name` context
+variable.
+
+### site_url
+
+Set the canonical URL of the site. This will add a link tag with the canonical
+URL to the generated HTML header.
+
+**default**: `null`
+
+### repo_url
+
+When set, provides a link to your GitHub or Bitbucket repository on each page.
+
+```yaml
+repo_url: https://github.com/example/repository/
+```
+
+**default**: `null`
+
+### repo_name
+
+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 `edit` path and `master` branch...)
+
+```yaml
+edit_uri: edit/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**: `edit/master/docs/` or `src/default/docs/` for GitHub or Bitbucket
+repos, respectively, if `repo_url` matches those domains, otherwise `null`
+
+!!! note "Note:"
+    On GitHub, the `edit` path opens the page in the online GitHub editor. This
+    functionality requires that the user have and be logged in to a GitHub
+    account. Otherwise, the user will be redirected to a login/signup page.
+    Alternatively, use the `blob` path to open a read-only view, which supports
+    anonymous access. E.g. `blob/master/docs/`
+
+### site_description
+
+Set the site description. This will add a meta tag to the generated HTML header.
+
+**default**: `null`
+
+### site_author
+
+Set the name of the author. This will add a meta tag to the generated HTML
+header.
+
+**default**: `null`
+
+### copyright
+
+Set the copyright information to be included in the documentation by the theme.
+
+**default**: `null`
+
+### google_analytics
+
+Set the Google analytics tracking configuration.
+
+```yaml
+google_analytics: ['UA-36723568-3', 'mkdocs.org']
+```
+
+**default**: `null`
+
+### remote_branch
+
+Set the remote branch to commit to when using `gh-deploy` to deploy to Github
+Pages. This option can be overridden by a command line option in `gh-deploy`.
+
+**default**: `gh-pages`
+
+### remote_name
+
+Set the remote name to push to when using `gh-deploy` to deploy to Github Pages.
+This option can be overridden by a command line option in `gh-deploy`.
+
+**default**: `origin`
+
+## Documentation layout
+
+### pages
+
+This setting is used to determine the set of pages that should be built for the
+documentation. For example, the following would create Introduction, User Guide
+and About pages, given the three source files `index.md`, `user-guide.md` and
+`about.md`, respectively.
+
+```yaml
+pages:
+    - 'Introduction': 'index.md'
+    - 'User Guide': 'user-guide.md'
+    - 'About': 'about.md'
+```
+
+See the section on [configuring pages and navigation] for a more detailed
+breakdown, including how to create sub-sections.
+
+**default**: By default `pages` will contain an alphanumerically sorted, nested
+list of all the Markdown files found within the `docs_dir` and its
+sub-directories. If none are found it will be `[]` (an empty list).
+
+## Build directories
+
+### theme
+
+Sets the theme of your documentation site, for a list of available themes visit
+[styling your docs].
+
+**default**: `'mkdocs'`
+
+### theme_dir
+
+Lets you set a directory to a custom theme. This can either be a relative
+directory, in which case it is resolved relative to the directory containing
+your configuration file, or it can be an absolute directory path.
+
+See [styling your docs][theme_dir] for details if you would like to tweak an
+existing theme.
+
+See [custom themes] if you would like to build your own theme from the ground
+up.
+
+**default**: `null`
+
+### docs_dir
+
+Lets you set the directory containing the documentation source markdown files.
+This can either be a relative directory, in which case it is resolved relative
+to the directory containing you configuration file, or it can be an absolute
+directory path.
+
+**default**: `'docs'`
+
+### site_dir
+
+Lets you set the directory where the output HTML and other files are created.
+This can either be a relative directory, in which case it is resolved relative
+to the directory containing you configuration file, or it can be an absolute
+directory path.
+
+**default**: `'site'`
+
+!!! note "Note:"
+    If you are using source code control you will normally want to ensure that
+    your *build output* files are not committed into the repository, and only
+    keep the *source* files under version control. For example, if using `git`
+    you might add the following line to your `.gitignore` file:
+
+        site/
+
+    If you're using another source code control tool, you'll want to check its
+    documentation on how to ignore specific directories.
+
+### extra_css
+
+Set a list of CSS files in your `docs_dir` to be included by the theme. For
+example, the following example will include the the extra.css file within the
+css subdirectory in your [docs_dir](#docs_dir).
+
+```yaml
+extra_css:
+    - css/extra.css
+    - css/second_extra.css
+```
+
+**default**: `[]` (an empty list).
+
+### extra_javascript
+
+Set a list of JavaScript files in your `docs_dir` to be included by the theme.
+See the example in [extra_css] for usage.
+
+**default**: `[]` (an empty list).
+
+### extra_templates
+
+Set a list of templates in your `docs_dir` to be built by MkDocs. To see more
+about writing templates for MkDocs read the documentation about [custom themes]
+and specifically the section about the [variables that are available] to
+templates. See the example in [extra_css] for usage.
+
+**default**: `[]` (an empty list).
+
+### extra
+
+A set of key value pairs, where the values can be any valid YAML construct, that
+will be passed to the template. This allows for great flexibility when creating
+custom themes.
+
+For example, if you are using a theme that supports displaying the project
+version, you can pass it to the theme like this:
+
+```yaml
+extra:
+    version: 1.0
+```
+
+**default**: By default `extra` will be an empty key value mapping.
+
+## Preview controls
+
+### use_directory_urls
+
+This setting controls the style used for linking to pages within the
+documentation.
+
+The following table demonstrates how the URLs used on the site differ when
+setting `use_directory_urls` to `true` or `false`.
+
+Source file  | Generated HTML       | use_directory_urls=true  | use_directory_urls=false
+------------ | -------------------- | ------------------------ | ------------------------
+index.md     | index.html           | /                        | /index.html
+api-guide.md | api-guide/index.html | /api-guide/              | /api-guide/index.html
+about.md     | about/index.html     | /about/                  | /about/index.html
+
+The default style of `use_directory_urls=true` creates more user friendly URLs,
+and is usually what you'll want to use.
+
+The alternate style can occasionally be useful if you want your documentation to
+remain properly linked when opening pages directly from the file system, because
+it create links that point directly to the target *file* rather than the target
+*directory*.
+
+**default**: `true`
+
+### strict
+
+Determines if a broken link to a page within the documentation is considered a
+warning or an error (link to a page not listed in the pages setting). Set to
+true to halt processing when a broken link is found, false prints a warning.
+
+**default**: `false`
+
+### dev_addr
+
+Determines the address used when running `mkdocs serve`. Setting this allows you
+to use another port, or allows you to make the service accessible over your
+local network by using the `0.0.0.0` address.
+
+As with all settings, you can set this from the command line, which can be
+useful, for example:
+
+```bash
+mkdocs serve --dev-addr=0.0.0.0:80  # Run on port 80, on the local network.
+```
+
+**default**: `'127.0.0.1:8000'`
+
+## Formatting options
+
+### markdown_extensions
+
+MkDocs uses the [Python Markdown][pymkd] library to translate Markdown files
+into HTML. Python Markdown supports a variety of [extensions][pymdk-extensions]
+that customize how pages are formatted. This setting lets you enable a list of
+extensions beyond the ones that MkDocs uses by default (`meta`, `toc`, `tables`,
+and `fenced_code`).
+
+For example, to enable the [SmartyPants typography extension][smarty], use:
+
+```yaml
+markdown_extensions:
+    - smarty
+```
+
+Some extensions provide configuration options of their own. If you would like to
+set any configuration options, then you can nest a key/value mapping
+(`option_name: option value`) of any options that a given extension supports.
+See the documentation for the extension you are using to determine what options
+they support.
+
+For example, to enable permalinks in the (included) `toc` extension, use:
+
+```yaml
+markdown_extensions:
+    - toc:
+        permalink: True
+```
+
+Note that a colon (`:`) must follow the extension name (`toc`) and then on a new
+line the option name and value must be indented and seperated by a colon. If you
+would like to define multipe options for a single extension, each option must be
+defined on a seperate line:
+
+```yaml
+markdown_extensions:
+    - toc:
+        permalink: True
+        separator: "_"
+```
+
+Add an additional item to the list for each extension. If you have no
+configuration options to set for a specific extension, then simply omit options
+for that extension:
+
+```yaml
+markdown_extensions:
+    - smarty
+    - toc:
+        permalink: True
+    - sane_lists
+```
+
+!!! note "See Also:"
+    The Python-Markdown documentation provides a [list of extensions][exts]
+    which are available out-of-the-box. For a list of configuration options
+    available for a given extension, see the documentation for that extension.
+
+    You may also install and use various [third party extensions][3rd]. Consult
+    the documentation provided by those extensions for installation instructions
+    and available configuration options.
+
+**default**: `[]`
+
+[custom themes]: custom-themes.md
+[variables that are available]: custom-themes.md#template-variables
+[pymdk-extensions]: https://pythonhosted.org/Markdown/extensions/index.html
+[pymkd]: https://pythonhosted.org/Markdown/
+[smarty]: https://pythonhosted.org/Markdown/extensions/smarty.html
+[exts]:https://pythonhosted.org/Markdown/extensions/index.html
+[3rd]: https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions
+[configuring pages and navigation]: writing-your-docs.md#configure-pages-and-navigation
+[theme_dir]: styling-your-docs.md#using-the-theme_dir
+[styling your docs]: styling-your-docs.md
+[extra_css]: #extra_css

docs/user-guide/custom-themes.md

@@ -0,0 +1,483 @@
+# Custom themes
+
+A guide to creating and distributing custom themes.
+
+---
+
+!!! Note
+
+    If you are looking for third party themes, they are listed in the MkDocs
+    [community wiki](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). If
+    you want to share a theme you create, you should list it on the Wiki.
+
+When creating a new theme, you can either follow the steps in this guide to
+create one from scratch or you can download the `mkdocs-basic-theme` as a
+basic, yet complete, theme with all the boilerplate required. **You can find
+this base theme on [GitHub](https://github.com/mkdocs/mkdocs-basic-theme)**.
+It contains detailed comments in the code to describe the different features
+and their usage.
+
+## Creating a custom theme
+
+The bare minimum required for a custom theme is a `main.html` [Jinja2
+template] file. This should be placed in a directory which will be the
+`theme_dir` and it should be created next to the `mkdocs.yml` configuration
+file. Within `mkdocs.yml`, specify the `theme_dir` option and set it to the
+name of the directory containing `main.html`. For example, given this example
+project layout:
+
+    mkdocs.yml
+    docs/
+        index.md
+        about.md
+    custom_theme/
+        main.html
+        ...
+
+You would include the following settings in `mkdocs.yml` to use the custom theme
+directory:
+
+    theme: null
+    theme_dir: 'custom_theme'
+
+!!! Note
+
+    Generally, when building your own custom theme, the `theme` configuration
+    setting would be set to `null`. However, if used in combination with the
+    `theme_dir` configuration value a custom theme can be used to replace only
+    specific parts of a built-in theme. For example, with the above layout and
+    if you set `theme: "mkdocs"` then the `main.html` file in the `theme_dir`
+    would replace that in the theme but otherwise the `mkdocs` theme would
+    remain the same. This is useful if you want to make small adjustments to an
+    existing theme.
+
+    For more specific information, see [styling your docs].
+
+[styling your docs]: ./styling-your-docs.md#using-the-theme_dir
+
+## Basic theme
+
+The simplest `main.html` file is the following:
+
+```django
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>
+  </head>
+  <body>
+    {{ content }}
+  </body>
+</html>
+```
+
+Article content from each page specified in `mkdocs.yml` is inserted using the
+`{{ content }}` tag. Style-sheets and scripts can be brought into this theme as
+with a normal HTML file. Navbars and tables of contents can also be generated
+and included automatically, through the `nav` and `toc` objects, respectively.
+If you wish to write your own theme, it is recommended to start with one of
+the [built-in themes] and modify it accordingly.
+
+!!! Note
+
+    As MkDocs uses [Jinja] as its template engine, you have access to all the
+    power of Jinja, including [template inheritance]. You may notice that the
+    themes included with MkDocs make extensive use of template inheritance and
+    blocks, allowing users to easily override small bits and pieces of the
+    templates from the [theme_dir]. Therefore, the built-in themes are
+    implemented in a `base.html` file, which `main.html` extends. Although not
+    required, third party template authors are encouraged to follow a similar
+    pattern and may want to define the same [blocks] as are used in the built-in
+    themes for consistency.
+
+[Jinja]: http://jinja.pocoo.org/
+[template inheritance]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
+[theme_dir]: ./styling-your-docs.md#using-the-theme_dir
+[blocks]: ./styling-your-docs.md#overriding-template-blocks
+
+## Template Variables
+
+Each template in a theme is built with a template context. These are the
+variables that are available to themes. The context varies depending on the
+template that is being built. At the moment templates are either built with
+the global context or with a page specific context. The global context is used
+for HTML pages that don't represent an individual Markdown document, for
+example a 404.html page or search.html.
+
+### Global Context
+
+The following variables are available globally on any template.
+
+#### config
+
+The `config` variable is an instance of MkDocs' config object generated from the
+`mkdocs.yml` config file. While you can use any config option, some commonly
+used options include:
+
+* [config.site_name](./configuration.md#site_name)
+* [config.site_url](./configuration.md#site_url)
+* [config.site_author](./configuration.md#site_author)
+* [config.site_description](./configuration.md#site_description)
+* [config.repo_url](./configuration.md#repo_url)
+* [config.repo_name](./configuration.md#repo_name)
+* [config.copyright](./configuration.md#copyright)
+* [config.google_analytics](./configuration.md#google_analytics)
+
+#### nav
+
+The `nav` variable is used to create the navigation for the documentation.
+Following is a basic usage example which outputs the first and second level
+navigation as a nested list.
+
+```django
+{% if nav|length>1 %}
+    <ul>
+    {% for nav_item in nav %}
+        {% if nav_item.children %}
+            <li>{{ nav_item.title }}
+                <ul>
+                {% for nav_item in nav_item.children %}
+                    <li class="{% if nav_item.active%}current{%endif%}">
+                        <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                    </li>
+                {% endfor %}
+                </ul>
+            </li>
+        {% else %}
+            <li class="{% if nav_item.active%}current{%endif%}">
+                <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+            </li>
+        {% endif %}
+    {% endfor %}
+    </ul>
+{% endif %}
+```
+
+The `nav` object also contains a `hompage` object, which points to the `page`
+object of the homepage. For example, you may want to access `nav.homepage.url`.
+
+#### base_url
+
+The `base_url` provides a relative path to the root of the MkDocs project.
+This makes it easy to include links to static assets in your theme. For
+example, if your theme includes a `js` folder, to include `theme.js` from that
+folder on all pages you would do this:
+
+```django
+<script src="{{ base_url }}/js/theme.js"></script>
+```
+
+#### extra_css
+
+Contains a list of URLs to the style-sheets listed in the [extra_css]
+config setting. Unlike the config setting, which contains local paths, this
+variable contains absolute paths from the homepage.
+
+[extra_css]: configuration.md#extra_css
+
+#### extra_javascript
+
+Contains a list of URLs to the scripts listed in the [extra_javascript] config
+setting. Unlike the config setting, which contains local paths, this variable
+contains absolute paths from the homepage.
+
+[extra_javascript]: configuration.md#extra_javascript
+
+#### mkdocs_version
+
+Contains the current MkDocs version.
+
+#### build_date_utc
+
+A Python datetime object that represents the date and time the documentation
+was built in UTC. This is useful for showing how recently the documentation
+was updated.
+
+#### page
+
+In templates which are not rendered from a Markdown source file, the `page`
+variable is `None`. In templates which are rendered from a Markdown source file,
+the `page` variable contains a page object with the following attributes:
+
+##### page.title
+
+Contains the Title for the current page.
+
+##### page.content
+
+The rendered Markdown as HTML, this is the contents of the documentation.
+
+##### page.toc
+
+An object representing the Table of contents for a page. Displaying the table
+of contents as a simple list can be achieved like this.
+
+```django
+<ul>
+{% for toc_item in page.toc %}
+    <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
+    {% for toc_item in toc_item.children %}
+        <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
+    {% endfor %}
+{% endfor %}
+</ul>
+```
+
+##### page.meta
+
+A mapping of the metadata included at the top of the markdown page. In this
+example we define a `source` property above the page title.
+
+```no-highlight
+source: generics.py
+        mixins.py
+
+# Page title
+
+Content...
+```
+
+A template can access this metadata for the page with the `meta.source`
+variable. This could then be used to link to source files related to the
+documentation page.
+
+```django
+{% for filename in page.meta.source %}
+  <a class="github" href="https://github.com/.../{{ filename }}">
+    <span class="label label-info">{{ filename }}</span>
+  </a>
+{% endfor %}
+```
+
+##### page.canonical_url
+
+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.
+
+##### page.is_homepage
+
+Evaluates to `True` for the homepage of the site and `False` for all other
+pages. This can be used in conjunction with other attributes of the `page`
+object to alter the behavior. For example, to display a different title
+on the homepage:
+
+```django
+{% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}
+```
+
+##### page.previous_page
+
+The page object for the previous  page. The usage is the same as for
+`page`.
+
+##### page.next_page
+
+The page object for the next page.The usage is the same as for `page`.
+
+### Extra Context
+
+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:
+
+```yaml
+extra:
+    version: 0.13.0
+    links:
+        - https://github.com/mkdocs
+        - https://docs.readthedocs.org/en/latest/builds.html#mkdocs
+        - http://www.mkdocs.org/
+```
+
+And then displayed with this HTML in the custom theme.
+
+```django
+{{ config.extra.version }}
+
+{% if config.extra.links %}
+  <ul>
+  {% for link in config.extra.links %}
+      <li>{{ link }}</li>
+  {% endfor %}
+  </ul>
+{% endif %}
+```
+
+## Search and themes
+
+As of MkDocs `0.13` client side search support has been added to MkDocs with
+[Lunr.js].
+
+Search can either be added to every page in the theme or to a dedicated
+template which must be named `search.html`. The search template will be build
+with the same name and can be viewable with `mkdocs serve` at
+`http://localhost:8000/search.html`. An example of the two different
+approaches can be seen by comparing the `mkdocs` and `readthedocs` themes.
+
+The following HTML needs to be added to the theme so the JavaScript is loaded
+for Lunr.js.
+
+```django
+<script>var base_url = '{{ base_url }}';</script>
+<script data-main="{{ base_url }}/mkdocs/js/search.js" src="{{ base_url }}/mkdocs/js/require.js"></script>
+```
+
+!!! note
+
+    The above JavaScript will download the search index, for larger
+    documentation projects this can be a heavy operation. In those cases, it
+    is suggested that you either use the `search.html` approach to only
+    include search on one page or load the JavaScript on an event like a form
+    submit.
+
+This loads the JavaScript and sets a global variable `base_url` which allows
+the JavaScript to make the links relative to the current page. The above
+JavaScript, with the following HTML in a `search.html` template will add a
+full search implementation to your theme.
+
+```django
+<h1 id="search">Search Results</h1>
+
+<form action="search.html">
+  <input name="q" id="mkdocs-search-query" type="text" >
+</form>
+
+<div id="mkdocs-search-results">
+  Sorry, page not found.
+</div>
+```
+
+This works by looking for the specific ID's used in the above HTML. The input
+for the user to type the search query must have the ID `mkdocs-search-query`
+and `mkdocs-search-results` is the directory where the results will be placed.
+
+[Jinja2 template]: http://jinja.pocoo.org/docs/dev/
+[built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes
+[lunr.js]: http://lunrjs.com/
+
+## Packaging Themes
+
+MkDocs makes use of [Python packaging] to distribute themes. This comes with a
+few requirements.
+
+To see an example of a package containing one theme, see the [MkDocs Bootstrap
+theme] and to see a package that contains many themes, see the [MkDocs
+Bootswatch theme].
+
+!!! Note
+
+    It is not strictly necessary to package a theme, as the entire theme
+    can be contained in the `theme_dir`. If you have created a "one-off theme,"
+    that should be sufficent. However, if you intend to distribute your theme
+    for others to use, packaging the theme has some advantages. By packaging
+    your theme, your users can more easily install it and they can them take
+    advantage of the [theme_dir] to make tweaks to your theme to better suit
+    their needs.
+
+[Python packaging]: https://packaging.python.org/en/latest/
+[MkDocs Bootstrap theme]: http://mkdocs.github.io/mkdocs-bootstrap/
+[MkDocs Bootswatch theme]: http://mkdocs.github.io/mkdocs-bootswatch/
+
+### Package Layout
+
+The following layout is recommended for themes. Two files at the top level
+directory called `MANIFEST.in` amd `setup.py` beside the theme directory which
+contains an empty `__init__.py` file and your template and media files.
+
+```no-highlight
+.
+|-- MANIFEST.in
+|-- theme_name
+|   |-- __init__.py
+|   |-- main.py
+|   |-- styles.css
+`-- setup.py
+```
+
+The `MANIFEST.in` file should contain the following contents but with
+theme_name updated and any extra file extensions added to the include.
+
+```no-highlight
+recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+```
+
+The `setup.py` should include the following text with the modifications
+described below.
+
+```python
+from setuptools import setup, find_packages
+
+VERSION = '0.0.1'
+
+
+setup(
+    name="mkdocs-themename",
+    version=VERSION,
+    url='',
+    license='',
+    description='',
+    author='',
+    author_email='',
+    packages=find_packages(),
+    include_package_data=True,
+    entry_points={
+        'mkdocs.themes': [
+            'themename = theme_name',
+        ]
+    },
+    zip_safe=False
+)
+```
+
+Fill in the URL, license, description, author and author email address.
+
+The name should follow the convention `mkdocs-themename` (like `mkdocs-
+bootstrap` and `mkdocs-bootswatch`), starting with MkDocs, using hyphens to
+separate words and including the name of your theme.
+
+Most of the rest of the file can be left unedited. The last section we need to
+change is the entry_points. This is how MkDocs finds the theme(s) you are
+including in the package. The name on the left is the one that users will use
+in their mkdocs.yml and the one on the right is the directory containing your
+theme files.
+
+The directory you created at the start of this section with the main.html file
+should contain all of the other theme files. The minimum requirement is that
+it includes a `main.html` for the theme. It **must** also include a
+`__init__.py` file which should be empty, this file tells Python that the
+directory is a package.
+
+### Distributing Themes
+
+With the above changes, your theme should now be ready to install. This can be
+done with pip, using `pip install .` if you are still in the same directory as
+the setup.py.
+
+Most Python packages, including MkDocs, are distributed on PyPI. To do this,
+you should run the following command.
+
+```no-highlight
+python setup.py register
+```
+
+If you don't have an account setup, you should be prompted to create one.
+
+For a much more detailed guide, see the official Python packaging
+documentation for [Packaging and Distributing Projects].
+
+[Packaging and Distributing Projects]: https://packaging.python.org/en/latest/distributing/

docs/user-guide/deploying-your-docs.md

@@ -0,0 +1,140 @@
+# Deploying your docs
+
+A basic guide to deploying your docs to various hosting providers
+
+---
+
+## GitHub Pages
+
+If you host the source code for a project on [GitHub], you can easily use
+[GitHub Pages] to host the documentation for your project. After you `checkout`
+the primary working branch (usually `master`) of the git repository where you
+maintain the source documentation for your project, run the following command:
+
+```sh
+mkdocs gh-deploy
+```
+
+That's it! Behind the scenes, MkDocs will build your docs and use the [ghp-import]
+tool to commit them to the gh-pages branch and push the gh-pages branch to
+GitHub.
+
+Use `mkdocs gh-deploy --help` to get a full list of options available for the
+`gh-deploy` command.
+
+Be aware that you will not be able to review the built site before it is pushed
+to GitHub. Therefore, you may want to verify any changes you make to the docs
+beforehand by using the `build` or `serve` commands and reviewing the built
+files locally.
+
+!!! warning
+
+    You should never edit files in your gh-pages branch by hand if you're using
+    the `gh-deploy` command because you will lose your work.
+
+[GitHub]: https://github.com/
+[GitHub Pages]: https://pages.github.com/
+[ghp-import]: https://github.com/davisp/ghp-import
+
+## Read the Docs
+
+[Read the Docs][rtd] offers free documentation hosting. You can import your docs
+using any major version control system, including Mercurial, Git, Subversion,
+and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the
+[instructions] on their site to arrange the files in your repository properly,
+create an account and point it at your publicly hosted repository. If properly
+configured, your documentation will update each time you push commits to your
+public repository.
+
+!!! note
+
+    To benefit from all of the [features] offered by Read the Docs, you will need
+    to use the [Read the Docs theme][theme] which ships with MkDocs. The various
+    themes which may be referenced in Read the Docs' documentation are Sphinx
+    specific themes and will not work with MkDocs.
+
+[rtd]: https://readthedocs.org/
+[instructions]: https://read-the-docs.readthedocs.io/en/latest/getting_started.html#in-markdown
+[features]: http://read-the-docs.readthedocs.io/en/latest/features.html
+[theme]: /user-guide/styling-your-docs.md
+
+## PyPI
+
+If you maintain a [Python] project which is hosted on the [Python Package
+Index][PyPI] (PyPI), you can use the hosting provided at [pythonhosted.org] to
+host documentation for your project. Run the following commands from your
+project's root directory to upload your documentation:
+
+```sh
+mkdocs build
+python setup.py upload_docs --upload-dir=site
+```
+
+Your documentation will be hosted at `https://pythonhosted.org/<projectname>/`
+where `<projectname>` is the name you used to register your project with PyPI.
+
+There are a few prerequisites for the above to work:
+
+1. You must be using [Setuptools] in your `setup.py` script ([Distutils] does
+   not offer an `upload_docs` command).
+1. Your project must already be registered with PyPI (use `python setup.py
+   register`).
+1. Your `mkdocs.yml` config file and your "docs" directory (value assigned to
+   the [docs_dir] configuration option) are presumed to be in the root directory
+   of your project alongside your `setup.py` script.
+1. It is assumed that the default value (`"site"`) is assigned to the [site_dir]
+   configuration option in your `mkdocs.yaml` config file. If you have set a
+   different value, assign that value to the `--upload-dir` option.
+
+[Python]: http://www.python.org/
+[PyPI]: https://pypi.python.org/pypi
+[pythonhosted.org]: https://pythonhosted.org/
+[Setuptools]: https://pythonhosted.org/setuptools/
+[Distutils]: https://docs.python.org/2/distutils/
+[docs_dir]: configuration.md#docs_dir
+[site_dir]: configuration.md#site_dir
+
+## Other Providers
+
+Any hosting provider which can serve static files can be used to serve
+documentation generated by MkDocs. While it would be impossible to document how
+to upload the docs to every hosting provider out there, the following guidelines
+should provide some general assistance.
+
+When you build your site (using the `mkdocs build` command), all of the files
+are written to the directory assigned to the [site_dir] configuration option
+(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
+simply need to copy the contents of that directory to the root directory of your
+hosting provider's server. Depending on your hosting provider's setup, you may
+need to use a graphical or command line [ftp], [ssh] or [scp] client to transfer
+the files.
+
+For example, a typical set of commands from the command line might look
+something like this:
+
+```sh
+mkdocs build
+scp -r ./site user@host:/path/to/server/root
+```
+
+Of course, you will need to replace `user` with the username you have with your
+hosting provider and `host` with the appropriate domain name. Additionally, you
+will need to adjust the `/path/to/server/root` to match the configuration of
+your hosts' file system.
+
+[ftp]: https://en.wikipedia.org/wiki/File_Transfer_Protocol
+[ssh]: https://en.wikipedia.org/wiki/Secure_Shell
+[scp]: https://en.wikipedia.org/wiki/Secure_copy
+
+See your host's documentation for specifics. You will likely want to search
+their documentation for "ftp" or "uploading site".
+
+## 404 Pages
+
+When MkDocs builds the documentation it will include a 404.html file in the
+[build directory][site_dir]. This file will be automatically used when
+deploying to [GitHub](#github-pages) but only on a custom domain. Other web
+servers may be configured to use it but the feature won't always be available.
+See the documentation for your server of choice for more information.
+
+[site_dir]: ./configuration/#site_dir

docs/user-guide/styling-your-docs.md

@@ -0,0 +1,266 @@
+# Styling your docs
+
+How to style and theme your documentation.
+
+---
+
+MkDocs includes a couple [built-in themes] as well as various [third party
+themes], all of which can easily be customized with [extra CSS or
+JavaScript][docs_dir] or overridden from the [theme directory][theme_dir]. You
+can also create your own [custom theme] from the grown up for your
+documentation.
+
+To use a theme that is included in MkDocs, simply add this to your
+`mkdocs.yml` config file.
+
+    theme: readthedocs
+
+Replace [`readthedocs`](#readthedocs) with any of the [built-in themes] listed below.
+
+To create a new custom theme see the [Custom Themes][custom theme] page, or to
+more heavily customize an existing theme, see
+the [Customizing a Theme][customize] section below.
+
+## Built-in themes
+
+### mkdocs
+
+![mkdocs](/img/mkdocs.png)
+
+### readthedocs
+
+![ReadTheDocs](http://docs.readthedocs.io/en/latest/_images/screen_mobile.png)
+
+### Third Party Themes
+
+A list of third party themes can be found in the MkDocs [community wiki]. If you
+have created your own, please feel free to add it to the list.
+
+## Customizing a Theme
+
+If you would like to make a few tweaks to an existing theme, there is no need to
+create your own theme from scratch. For minor tweaks which only require some CSS
+and/or JavaScript, you can use the [docs_dir]. However, for more complex
+customizations, including overriding templates, you will need to use the
+[theme_dir].
+
+### Using the docs_dir
+
+The [extra_css] and [extra_javascript] configuration options can be used to
+make tweaks and customizations to existing themes. To use these, you simply
+need to include either CSS or JavaScript files within your [documentation
+directory].
+
+For example, to change the colour of the headers in your documentation, create
+a file called `extra.css` and place it next to the documentation Markdown. In
+that file add the following CSS.
+
+```CSS
+h1 {
+  color: red;
+}
+```
+
+!!! note
+
+    If you are deploying your documentation with [ReadTheDocs]. You will need
+    to explicitly list the CSS and JavaScript files you want to include in
+    your config. To do this, add the following to your mkdocs.yml.
+
+        extra_css: [extra.css]
+
+After making these changes, they should be visible when you run
+`mkdocs serve` - if you already had this running, you should see that the CSS
+changes were automatically picked up and the documentation will be updated.
+
+!!! note
+
+    Any extra CSS or JavaScript files will be added to the generated HTML
+    document after the page content. If you desire to include a JavaScript
+    library, you may have better success including the library by using the
+    [theme_dir].
+
+### Using the theme_dir
+
+The [theme_dir] configuration option can be used to point to a directory of
+files which override the files in the theme set on the [theme] configuration
+option. Any file in the `theme_dir` with the same name as a file in the `theme`
+will replace the file of the same name in the `theme`. Any additional files in
+the `theme_dir` will be added to the `theme`. The contents of the `theme_dir`
+should mirror the directory structure of the `theme`. You may include templates,
+JavaScript files, CSS files, images, fonts, or any other media included in a
+theme.
+
+!!! Note
+
+    For this to work, the `theme` setting must be set to a known installed theme.
+    If the `theme` setting is instead set to `null` (or not defined), then there
+    is no theme to override and the contents of the `theme_dir` must be a
+    complete, standalone theme. See [Custom Themes][custom theme] for more
+    information.
+
+For example, the [mkdocs] theme ([browse source]), contains the following
+directory structure (in part):
+
+```nohighlight
+- css\
+- fonts\
+- img\
+  - favicon.ico
+  - grid.png
+- js\
+- 404.html
+- base.html
+- content.html
+- nav-sub.html
+- nav.html
+- toc.html
+```
+
+To override any of the files contained in that theme, create a new directory
+next to your `docs_dir`:
+
+```bash
+mkdir custom_theme
+```
+
+And then point your `mkdocs.yml` configuration file at the new directory:
+
+```yaml
+theme_dir: custom_theme
+```
+
+To override the 404 error page ("file not found"), add a new template file named
+`404.html` to the `custom_theme` directory. For information on what can be
+included in a template, review the documentation for building a [custom theme].
+
+To override the favicon, you can add a new icon file at
+`custom_theme/img/favicon.ico`.
+
+To include a JavaScript library, copy the library to the `custom_theme/js/`
+directory.
+
+Your directory structure should now look like this:
+
+```nohighlight
+- docs/
+  - index.html
+- custom_theme/
+  - img/
+    - favicon.ico
+  - js/
+    - somelib.js
+  - 404.html
+- config.yml
+```
+
+!!! Note
+
+    Any files included in the `theme` but not included in the `theme_dir` will
+    still be utilized. The `theme_dir` will only override/replace files in the
+    `theme`. If you want to remove files, or build a theme from scratch, then
+    you should review the documentation for building a [custom theme].
+
+#### Overriding Template Blocks
+
+The built-in themes implement many of their parts inside template blocks which
+can be individually overridden in the `main.html` template. Simply create a
+`main.html` template file in your `theme_dir` and define replacement blocks
+within that file. Just make sure that the `main.html` extends `base.html`. For
+example, to alter the title of the MkDocs theme, your replacement `main.html`
+template would contain the following:
+
+```django
+{% extends "base.html" %}
+
+{% block title %}
+<title>Custom title goes here</title>
+{% endblock %}
+```
+
+In the above example, the title block defined in your custom `main.html` file
+will be used in place of the default title block defined in the parent theme.
+You may re-define as many blocks as you desire, as long as those blocks are
+defined in the parent. For example, you could replace the Google Analytics
+script with one for a different service or replace the search feature with your
+own. You will need to consult the parent theme you are using to determine what
+blocks are available to override. The MkDocs and ReadTheDocs themes provide the
+following blocks:
+
+* `site_meta`: Contains meta tags in the document head.
+* `htmltitle`: Contains the page title in the document head.
+* `styles`: Contains the link tags for stylesheets.
+* `libs`: Contains the JavaScript libraries (jQuery, etc) included in the page header.
+* `scripts`: Contains JavaScript scripts which should execute after a page loads.
+* `analytics`: Contains the analytics script.
+* `extrahead`: An empty block in the `<head>` to insert custom tags/scripts/etc.
+* `site_name`: Contains the site name in the navigation bar.
+* `site_nav`: Contains the site navigation in the navigation bar.
+* `search_box`: Contains the search box in the navigation bar.
+* `next_prev`: Contains the next and previous buttons in the navigation bar.
+* `repo`: Contains the repository link in the navigation bar.
+* `content`: Contains the page content and table of contents for the page.
+* `footer`: Contains the page footer.
+
+You may need to view the source template files to ensure your modifications will
+work with the structure of the site. See [Template Variables] for a list of
+variables you can use within your custom blocks. For a more complete
+explaination of blocks, consult the [Jinja documentation].
+
+#### Combining the theme_dir and Template Blocks
+
+Adding a JavaScript library to the `theme_dir` will make it available, but
+won't include it in the pages generated by MkDocs. Therefore, a link needs to
+be added to the library from the HTML.
+
+Starting the with directory structure above (truncated):
+
+```nohighlight
+- docs/
+- custom_theme/
+  - js/
+    - somelib.js
+- config.yml
+```
+
+A link to the `custom_theme/js/somelib.js` file needs to be added to the
+template. As `somelib.js` is a JavaScript library, it would logically go in the
+`libs` block. However, a new `libs` block that only includes the new script will
+replace the block defined in the parent template and any links to libraries in
+the parent template will be removed. To avoid breaking the template, a
+[super block] can be used with a call to `super` from within the block:
+
+```django
+{% extends "base.html" %}
+
+{% block libs %}
+    {{ super() }}
+    <script src="{{ base_url }}/js/somelib.js"></script>
+{% endblock %}
+```
+
+Note that the [base_url] template variable was used to ensure that the link is
+always relative to the current page.
+
+Now the generated pages will include links to the template provided libraries as
+well as the library included in the `theme_dir`. The same would be required for
+any additional CSS files included in the `theme_dir`.
+
+[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
+[built-in themes]: #built-in-themes
+[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
+[custom theme]: ./custom-themes.md
+[customize]: #customizing-a-theme
+[docs_dir]: #using-the-docs_dir
+[documentation directory]: ./configuration/#docs_dir
+[extra_css]: ./configuration.md#extra_css
+[extra_javascript]: ./configuration.md#extra_javascript
+[Jinja documentation]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
+[mkdocs]: #mkdocs
+[ReadTheDocs]: ./deploying-your-docs.md#readthedocs
+[Template Variables]: ./custom-themes.md#template-variables
+[theme]: ./configuration/#theme
+[theme_dir]: ./configuration/#theme_dir
+[third party themes]: #third-party-themes
+[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks
+[base_url]: ./custom-themes.md#base_url

docs/user-guide/writing-your-docs.md

@@ -0,0 +1,242 @@
+# Writing your docs
+
+How to write and layout your markdown source files.
+
+---
+
+## Configure Pages and Navigation
+
+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). An
+automatically created pages configuration will always be sorted
+alphanumerically by file name. You will need to manually define your pages
+configuration if you would like your pages sorted differantly.
+
+A simple pages configuration looks like this:
+
+```no-highlight
+pages:
+- 'index.md'
+- 'about.md'
+```
+
+With this example we will build two pages at the top level and they will
+automatically have their titles inferred from the filename. Assuming `docs_dir`
+has the default value, `docs`, the source files for this documentation would be
+`docs/index.md` and `docs/about.md`. To provide a custom name for these pages,
+they can be added before the filename.
+
+```no-highlight
+pages:
+- Home: 'index.md'
+- About: 'about.md'
+```
+
+### Multilevel documentation
+
+Subsections can be created by listing related pages together under a section
+title. For example:
+
+```no-highlight
+pages:
+- Home: 'index.md'
+- User Guide:
+    - 'Writing your docs': 'user-guide/writing-your-docs.md'
+    - 'Styling your docs': 'user-guide/styling-your-docs.md'
+- About:
+    - 'License': 'about/license.md'
+    - 'Release Notes': 'about/release-notes.md'
+```
+
+With the above configuration we have three top level sections: Home, User Guide
+and About. Then under User Guide we have two pages, Writing your docs and
+Styling your docs. Under the About section we also have two pages, License and
+Release Notes.
+
+## File layout
+
+Your documentation source should be written as regular Markdown files, and
+placed in a directory somewhere in your project. Normally this directory will be
+named `docs` and will exist at the top level of your project, alongside the
+`mkdocs.yml` configuration file.
+
+The simplest project you can create will look something like this:
+
+```no-highlight
+mkdocs.yml
+docs/
+    index.md
+```
+
+By convention your project homepage should always be named `index`. Any of the
+following extensions may be used for your Markdown source files: `markdown`,
+`mdown`, `mkdn`, `mkd`, `md`.
+
+You can also create multi-page documentation, by creating several markdown
+files:
+
+```no-highlight
+mkdocs.yml
+docs/
+    index.md
+    about.md
+    license.md
+```
+
+The file layout you use determines the URLs that are used for the generated
+pages. Given the above layout, pages would be generated for the following URLs:
+
+```no-highlight
+/
+/about/
+/license/
+```
+
+You can also include your Markdown files in nested directories if that better
+suits your documentation layout.
+
+```no-highlight
+docs/
+    index.md
+    user-guide/getting-started.md
+    user-guide/configuration-options.md
+    license.md
+```
+
+Source files inside nested directories will cause pages to be generated with
+nested URLs, like so:
+
+```no-highlight
+/
+/user-guide/getting-started/
+/user-guide/configuration-options/
+/license/
+```
+
+## Linking documents
+
+MkDocs allows you to interlink your documentation by using regular Markdown
+hyperlinks.
+
+### Internal hyperlinks
+
+When linking between pages in the documentation you can simply use the regular
+Markdown hyperlinking syntax, including the relative path to the Markdown
+document you wish to link to.
+
+    Please see the [project license](license.md) for further details.
+
+When the MkDocs build runs, these hyperlinks will automatically be transformed
+into a hyperlink to the appropriate HTML page.
+
+When working on your documentation you should be able to open the linked
+Markdown document in a new editor window simply by clicking on the link.
+
+If the target documentation file is in another directory you'll need to make
+sure to include any relative directory path in the hyperlink.
+
+    Please see the [project license](../about/license.md) for further details.
+
+You can also link to a section within a target documentation page by using an
+anchor link. The generated HTML will correctly transform the path portion of the
+hyperlink, and leave the anchor portion intact.
+
+    Please see the [project license](about.md#license) for further details.
+
+## Images and media
+
+As well as the Markdown source files, you can also include other file types in
+your documentation, which will be copied across when generating your
+documentation site. These might include images and other media.
+
+For example, if your project documentation needed to include a [GitHub pages
+CNAME
+file](https://help.github.com/articles/using-a-custom-domain-with-github-pages/)
+and a PNG formatted screenshot image then your file layout might look as
+follows:
+
+```no-highlight
+mkdocs.yml
+docs/
+    CNAME
+    index.md
+    about.md
+    license.md
+    img/
+        screenshot.png
+```
+
+To include images in your documentation source files, simply use any of the
+regular Markdown image syntaxes:
+
+```Markdown
+Cupcake indexer is a snazzy new project for indexing small cakes.
+
+![Screenshot](img/screenshot.png)
+
+*Above: Cupcake indexer in progress*
+```
+
+You image will now be embedded when you build the documentation, and should also
+be previewed if you're working on the documentation with a Markdown editor.
+
+## Markdown extensions
+
+MkDocs supports the following Markdown extensions.
+
+### Tables
+
+A simple table looks like this:
+
+```no-highlight
+First Header | Second Header | Third Header
+------------ | ------------- | ------------
+Content Cell | Content Cell  | Content Cell
+Content Cell | Content Cell  | Content Cell
+```
+
+If you wish, you can add a leading and tailing pipe to each line of the table:
+
+```no-highlight
+| First Header | Second Header | Third Header |
+| ------------ | ------------- | ------------ |
+| Content Cell | Content Cell  | Content Cell |
+| Content Cell | Content Cell  | Content Cell |
+```
+
+Specify alignment for each column by adding colons to separator lines:
+
+```no-highlight
+First Header | Second Header | Third Header
+:----------- |:-------------:| -----------:
+Left         | Center        | Right
+Left         | Center        | Right
+```
+
+### Fenced code blocks
+
+The first line should contain 3 or more backtick (`` ` ``) characters, and the
+last line should contain the same number of backtick characters (`` ` ``):
+
+~~~no-highlight
+```
+Fenced code blocks are like Standard
+Markdown’s regular code blocks, except that
+they’re not indented and instead rely on
+start and end fence lines to delimit the
+code block.
+```
+~~~
+
+With this approach, the language can optionally be specified on the first line
+after the backticks:
+
+~~~no-highlight
+```python
+def fn():
+    pass
+```
+~~~

mkdocs.yml

@@ -0,0 +1,29 @@
+site_name: MkDocs
+site_url: https://pages.gitlab.io/mkdocs
+site_description: Project documentation with Markdown.
+site_author: MkDocs Team
+
+repo_url: https://gitlab.com/pages/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
+    - Custom Themes: user-guide/custom-themes.md
+- About:
+    - Release Notes: about/release-notes.md
+    - Contributing: about/contributing.md
+    - License: about/license.md
+
+extra_css:
+    - css/extra.css
+
+markdown_extensions:
+    - toc:
+        permalink: 
+    - admonition:
+
+copyright: Copyright &copy; 2014 <a href="/release-notes/">Tom Christie</a>, Maintained by the <a href="/about/release-notes/#maintenance-team">MkDocs Team</a>.