Use a new MkDocs site

.gitlab-ci.yml

@@ -0,0 +1,17 @@
+image: python:alpine
+
+before_script:
+  - pip install mkdocs
+  # Add your custom theme if not inside a theme_dir
+  # (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
+  # - pip install mkdocs-material
+
+pages:
+  script:
+  - mkdocs build
+  - mv site public
+  artifacts:
+    paths:
+    - public
+  only:
+  - master

README.md

@@ -1,7 +1,13 @@
-# Example [MkDocs](http://mkdocs.org/) website using GitLab Pages.
+![Build Status](https://gitlab.com/pages/mkdocs/badges/master/build.svg)
+
+---
+
+Example [MkDocs] 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.
+documentation https://docs.gitlab.com/ce/user/project/pages/.
+
+---
 
 ## GitLab CI
 
@@ -13,7 +19,8 @@ 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
+  ## Add your custom theme if not inside a theme_dir
+  ## (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
   # - pip install mkdocs-material
 
 pages:
@@ -32,17 +39,13 @@ pages:
 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. [Install][] MkDocs
+1. Preview your project: `mkdocs serve`,
+   your site can be accessed under `localhost:8000`
 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`.
+Read more at MkDocs [documentation][].
 
 ## GitLab User or Group Pages
 
@@ -52,6 +55,32 @@ 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"`.
+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].
+
+## Did you fork this project?
+
+If you forked this project for your own use, please go to your project's
+**Settings** and remove the forking relationship, which won't be necessary
+unless you want to contribute back to the upstream project.
+
+## Troubleshooting
+
+1. CSS is missing! That means two things:
+
+    Either that you have wrongly set up the CSS URL in your templates, or
+    your static generator has a configuration option that needs to be explicitly
+    set in order to serve static assets under a relative URL.
+
+[ci]: https://about.gitlab.com/gitlab-ci/
+[mkdocs]: http://www.mkdocs.org
+[install]: http://www.mkdocs.org/#installation
+[documentation]: http://www.mkdocs.org
+[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
+[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
+
+---
 
-Read more about [user/group Pages][userpages] and [project Pages][projpages].
+Forked from https://gitlab.com/morph027/mkdocs

docs/CNAME

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

docs/about/contributing.md

@@ -1,69 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,542 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-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

@@ -1,352 +1,21 @@
-# MkDocs
+# Welcome to MkDocs
 
-Project documentation with Markdown.
+This is a test site hosted on [GitLab Pages](https://pages.gitlab.io). You can
+[browse its source code](https://gitlab.com/pages/mkdocs), fork it and start
+using it on your projects.
 
----
+For full documentation visit [mkdocs.org](http://mkdocs.org).
 
-!!! Note
-	This site was built with GitLab Pages!.
+## Commands
 
-	Visit this project at [https://gitlab.com/pages/mkdocs](https://gitlab.com/pages/mkdocs).
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs help` - Print this help message.
 
-## Overview
+## Project layout
 
-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
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

docs/user-guide/configuration.md

@@ -1,380 +0,0 @@
-# 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

@@ -1,483 +0,0 @@
-# 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

@@ -1,140 +0,0 @@
-# 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

@@ -1,266 +0,0 @@
-# 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

@@ -1,242 +0,0 @@
-# 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

@@ -1,29 +1 @@
-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>.
+site_name: My Docs by GitLab Pages