diff --git a/__init__.pyc b/__init__.pyc index 71c431d5..6fe6e160 100644 Binary files a/__init__.pyc and b/__init__.pyc differ diff --git a/__pycache__/__init__.cpython-33.pyc b/__pycache__/__init__.cpython-33.pyc new file mode 100644 index 00000000..6ad08228 Binary files /dev/null and b/__pycache__/__init__.cpython-33.pyc differ diff --git a/__pycache__/__init__.cpython-34.pyc b/__pycache__/__init__.cpython-34.pyc new file mode 100644 index 00000000..004f0efd Binary files /dev/null and b/__pycache__/__init__.cpython-34.pyc differ diff --git a/__pycache__/__init__.cpython-35.pyc b/__pycache__/__init__.cpython-35.pyc new file mode 100644 index 00000000..2bc8dd3a Binary files /dev/null and b/__pycache__/__init__.cpython-35.pyc differ diff --git a/about/contributing/index.json b/about/contributing/index.json new file mode 100644 index 00000000..0405be64 --- /dev/null +++ b/about/contributing/index.json @@ -0,0 +1,6 @@ +{ + "content": "

Contributing to MkDocs\uf0c1

\n

An introduction to contributing to the MkDocs project.

\n

The MkDocs project welcomes, and depends, on contributions from developers and\nusers in the open source community. Contributions can be made in a number of\nways, a few examples are:

\n\n

Reporting an Issue\uf0c1

\n

Please include as much detail as you can. Let us know your platform and MkDocs\nversion. If the problem is visual (for example a theme or design issue) please\nadd a screenshot and if you get an error please include the the full error and\ntraceback.

\n

Testing the Development Version\uf0c1

\n

If you want to just install and try out the latest development version of\nMkDocs you can do so with the following command. This can be useful if you\nwant to provide feedback for a new feature or want to confirm if a bug you\nhave encountered is fixed in the git master. It is strongly recommended\nthat you do this within a virtualenv.

\n
pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz\n
\n\n

Installing for Development\uf0c1

\n

First you'll need to fork and clone the repository. Once you have a local\ncopy, run the following command. It is strongly recommended that you do\nthis within a virtualenv.

\n
pip install --editable .\n
\n\n

This will install MkDocs in development mode which binds the mkdocs command\nto the git repository.

\n

Running the tests\uf0c1

\n

To run the tests, it is recommended that you use Tox. This just needs\nto be pip installed and then the test suite can be ran for MkDocs but running\nthe command tox in the root of your MkDocs repository.

\n

It will attempt to run the tests against all of the Python versions we\nsupport. So don't be concerned if you are missing some and they fail. The rest\nwill be verified by Travis when you submit a pull request.

\n

Submitting Pull Requests\uf0c1

\n

Once you are happy with your changes or you are ready for some feedback, push\nit to your fork and send a pull request. For a change to be accepted it will\nmost likely need to have tests and documentation if it is a new feature.

", + "url": "/about/contributing/", + "language": "en", + "title": "Contributing" +} \ No newline at end of file diff --git a/about/license/index.json b/about/license/index.json new file mode 100644 index 00000000..4aa0274e --- /dev/null +++ b/about/license/index.json @@ -0,0 +1,6 @@ +{ + "content": "

License\uf0c1

\n

The legal stuff.

\n
\n

Included projects\uf0c1

\n

Themes used under license from the Bootstrap, ReadTheDocs, GhostWriter and\nBootswatch projects.

\n\n

Many thanks to the authors and contributors of those wonderful projects.

\n

MkDocs License (BSD)\uf0c1

\n

Copyright \u00a9 2014, Tom Christie. All rights reserved.

\n

Redistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:

\n

Redistributions of source code must retain the above copyright notice, this list\nof conditions and the following disclaimer. Redistributions in binary form must\nreproduce the above copyright notice, this list of conditions and the following\ndisclaimer in the documentation and/or other materials provided with the\ndistribution.

\n

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR\nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON\nANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

", + "url": "/about/license/", + "language": "en", + "title": "License" +} \ No newline at end of file diff --git a/about/release-notes/index.html b/about/release-notes/index.html index d0208ae3..274af0cf 100644 --- a/about/release-notes/index.html +++ b/about/release-notes/index.html @@ -180,6 +180,8 @@
  • Upgrading
    • +
  • Version 0.15.1 (2016-01-30)
    • +
  • Version 0.15.0 (2016-01-21)
  • Version 0.14.0 (2015-06-09)
    • @@ -219,6 +221,11 @@ 
    $ mkdocs --version
 mkdocs, version 0.14.0
    +

    Version 0.15.1 (2016-01-30)

    +

    Version 0.15.0 (2016-01-21)

    Major Additions to Version 0.15.0

    Add support for installable themes

    diff --git a/about/release-notes/index.json b/about/release-notes/index.json new file mode 100644 index 00000000..be71bcb8 --- /dev/null +++ b/about/release-notes/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    Release Notes\uf0c1

    \n
    \n

    Upgrading\uf0c1

    \n

    To upgrade MkDocs to the latest version, use pip:

    \n
    pip install -U mkdocs\n
    \n

    You can determine your currently installed version using mkdocs --version:

    \n
    $ mkdocs --version\nmkdocs, version 0.14.0\n
    \n

    Version 0.15.0 (2016-01-21)\uf0c1

    \n

    Major Additions to Version 0.15.0\uf0c1

    \n

    Add support for installable themes\uf0c1

    \n

    MkDocs now supports themes that are distributed via Python packages. With this\naddition, the Bootstrap and Bootswatch themes have been moved to external git\nrepositories and python packages. See their individual documentation for more\ndetails about these specific themes.

    \n\n

    They will be included with MkDocs by default until the 1.0 release. After that\nthey will be installable with pip: pip install mkdocs-bootstrap and pip\ninstall mkdocs-bootswatch

    \n

    See the documentation for Styling your docs for more information about using\nand customising themes and Custom themes for creating and distributing new\nthemes

    \n

    Other Changes and Additions to Version 0.15.0\uf0c1

    \n\n

    Version 0.14.0 (2015-06-09)\uf0c1

    \n\n

    Version 0.13.3 (2015-06-02)\uf0c1

    \n\n

    Version 0.13.2 (2015-05-30)\uf0c1

    \n\n

    Version 0.13.1 (2015-05-27)\uf0c1

    \n\n

    Version 0.13.0 (2015-05-26)\uf0c1

    \n

    Deprecations to Version 0.13.0\uf0c1

    \n

    Deprecate the JSON command\uf0c1

    \n

    In this release the mkdocs json command has been marked as deprecated and\nwhen used a deprecation warning will be shown. It will be removed in a future\nrelease of MkDocs, version 1.0 at the latest. The mkdocs json command\nprovided a convenient way for users to output the documentation contents as\nJSON files but with the additions of search to MkDocs this functionality is\nduplicated.

    \n

    A new index with all the contents from a MkDocs build is created in the\nsite_dir, so with the default value for the site_dir It can be found in\nsite/mkdocs/search_index.json.

    \n

    This new file is created on every MkDocs build (with mkdocs build) and\nno configuration is needed to enable it.

    \n

    Change the pages configuration\uf0c1

    \n

    Provide a new way to define pages, and specifically nested pages, in the\nmkdocs.yml file and deprecate the existing approach, support will be removed\nwith MkDocs 1.0.

    \n

    Warn users about the removal of builtin themes\uf0c1

    \n

    All themes other than mkdocs and readthedocs will be moved into external\npackages in a future release of MkDocs. This will enable them to be more easily\nsupported and updates outside MkDocs releases.

    \n

    Major Additions to Version 0.13.0\uf0c1

    \n

    Search\uf0c1

    \n

    Support for search has now been added to MkDocs. This is based on the\nJavaScript library lunr.js. It has been added to both the mkdocs and\nreadthedocs themes. See the custom theme documentation on supporting search\nfor adding it to your own themes.

    \n

    New Command Line Interface\uf0c1

    \n

    The command line interface for MkDocs has been re-written with the Python\nlibrary Click. This means that MkDocs now has an easier to use interface\nwith better help output.

    \n

    This change is partially backwards incompatible as while undocumented it was\npossible to pass any configuration option to the different commands. Now only\na small subset of the configuration options can be passed to the commands. To\nsee in full commands and available arguments use mkdocs --help and\nmkdocs build --help to have them displayed.

    \n

    Support Extra HTML and XML files\uf0c1

    \n

    Like the extra_javascript and extra_css configuration options, a new\noption named extra_templates has been added. This will automatically be\npopulated with any .html or .xml files in the project docs directory.

    \n

    Users can place static HTML and XML files and they will be copied over, or they\ncan also use Jinja2 syntax and take advantage of the global variables.

    \n

    By default MkDocs will use this approach to create a sitemap for the\ndocumentation.

    \n

    Other Changes and Additions to Version 0.13.0\uf0c1

    \n\n

    Version 0.12.2 (2015-04-22)\uf0c1

    \n\n

    Version 0.12.1 (2015-04-14)\uf0c1

    \n\n

    Version 0.12.0 (2015-04-14)\uf0c1

    \n\n

    Version 0.11.1 (2014-11-20)\uf0c1

    \n\n

    Version 0.11.0 (2014-11-18)\uf0c1

    \n\n

    Version 0.10.0 (2014-10-29)\uf0c1

    \n", + "url": "/about/release-notes/", + "language": "en", + "title": "Release Notes" +} \ No newline at end of file diff --git a/fonts/FontAwesome.otf b/fonts/FontAwesome.otf new file mode 100644 index 00000000..3ed7f8b4 Binary files /dev/null and b/fonts/FontAwesome.otf differ diff --git a/fonts/fontawesome-webfont.woff2 b/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..500e5172 Binary files /dev/null and b/fonts/fontawesome-webfont.woff2 differ diff --git a/index.html b/index.html index 059705d1..b908ee7b 100644 --- a/index.html +++ b/index.html @@ -407,6 +407,6 @@ the MkDocs IRC channel #mkdocs on freenode.

    diff --git a/index.json b/index.json new file mode 100644 index 00000000..102ebeac --- /dev/null +++ b/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    MkDocs\uf0c1

    \n

    Project documentation with Markdown.

    \n
    \n

    Overview\uf0c1

    \n

    MkDocs is a fast, simple and downright gorgeous static site\ngenerator that's geared towards building project documentation. Documentation\nsource files are written in Markdown, and configured with a single YAML\nconfiguration file.

    \n

    Host anywhere\uf0c1

    \n

    Builds completely static HTML sites that you can host on GitHub pages, Amazon\nS3, or anywhere else you choose.

    \n

    Great themes available\uf0c1

    \n

    There's a stack of good looking themes included by default. Choose from\nbootstrap, readthedocs, or any of the 12 bootswatch themes.

    \n

    Preview your site as you work\uf0c1

    \n

    The built-in devserver allows you to preview your documentation as you're\nwriting it. It will even auto-reload whenever you save any changes, so all you\nneed to do to see your latest edits is refresh your browser.

    \n

    Easy to customize\uf0c1

    \n

    Get your project documentation looking just the way you want it by customizing\nthe theme.

    \n
    \n

    Installation\uf0c1

    \n

    In order to install MkDocs you'll need Python installed on your system, as\nwell as the Python package manager, pip. You can check if you have these\nalready installed like so:

    \n
    $ python --version\nPython 2.7.2\n$ pip --version\npip 1.5.2\n
    \n\n

    MkDocs supports Python 2.6, 2.7, 3.3 and 3.4.

    \n

    On Windows we recommend that you install Python and pip with Chocolatey.

    \n

    Install the mkdocs package using pip:

    \n
    pip install mkdocs\n
    \n\n

    You should now have the mkdocs command installed on your system. Run mkdocs\n--version to check that everything worked okay.

    \n
    $ mkdocs --version\nmkdocs, version 0.14.0\n
    \n\n
    \n

    Getting started\uf0c1

    \n

    Getting started is super easy.

    \n
    mkdocs new my-project\ncd my-project\n
    \n\n

    Let's take a moment to review the initial project that's been created for us.

    \n

    \"The

    \n

    There's a single configuration file named mkdocs.yml, and a folder named\ndocs that will contain our documentation source files. Right now the docs\nfolder just contains a single documentation page, named index.md.

    \n

    MkDocs comes with a built-in webserver that lets you preview your documentation\nas you work on it. We start the webserver by making sure we're in the same\ndirectory as the mkdocs.yml config file, and then running the mkdocs serve\ncommand:

    \n
    $ mkdocs serve\nRunning at: http://127.0.0.1:8000/\n
    \n\n

    Open up http://127.0.0.1:8000/ in your browser, and\nyou'll see the index page being displayed:

    \n

    \"The

    \n

    The webserver also supports auto-reloading, and will rebuild your documentation\nwhenever anything in the configuration file, documentation directory or theme\ndirectory changes.

    \n

    Go ahead and edit the docs/index.md file now and save the file. Then simply\nhit reload in the browser and you'll see your updated documentation.

    \n

    Now's also a good time to edit the configuration file, mkdocs.yml. Change the\nsite_name setting to something else and save the file.

    \n

    \"Editing

    \n

    Once you hit reload in the browser you'll see your new site name take effect.

    \n

    \"The

    \n

    Adding pages\uf0c1

    \n

    Go ahead and edit the docs/index.md document, and change the initial heading to\nMkLorum, then reload the site in your browser, and you should see the change\ntake effect immediately.

    \n

    Let's also add a second page to our documentation:

    \n
    curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md\n
    \n\n

    We'd like our documentation site to include some navigation headers, so we'll\nedit the configuration file and add some information about the order and title\nto use for out headers:

    \n
    site_name: MkLorum\npages:\n- Home: index.md\n- About: about.md\n
    \n\n

    Refresh the browser and you'll now see a navigation bar with Home and About\nheaders.

    \n

    Theming our documentation\uf0c1

    \n

    While we're here can also change the configuration file to alter how the\ndocumentation is displayed. Let's go ahead and change the theme. Edit the\nmkdocs.yml file to the following:

    \n
    site_name: MkLorum\npages:\n- Home: index.md\n- About: about.md\ntheme: readthedocs\n
    \n\n

    Refresh the browser again, and you'll now see the ReadTheDocs theme being used.

    \n

    \"Screenshot\"

    \n

    Building the site\uf0c1

    \n

    That's looking good. We're ready to deploy the first pass of our MkLorum\ndocumentation now. Let's build the documentation.

    \n
    mkdocs build\n
    \n\n

    This will create a new directory, named site. Let's take a look inside the\ndirectory:

    \n
    ls site\nabout css fonts img index.html js\n
    \n\n

    Notice that our source documentation has been output as two HTML files named\nindex.html and about/index.html. We also have various other media that's\nbeen copied into the site directory as part of the documentation theme.

    \n

    If you're using source code control such as git you probably don't want to\ncheck your documentation builds into the repository. Add a line containing\nsite/ to your .gitignore file.

    \n
    echo "site/" >> .gitignore\n
    \n\n

    If you're using another source code control you'll want to check it's\ndocumentation on how to ignore specific directories.

    \n

    After some time, files may be removed from the documentation but they will still\nreside in the site directory. To remove those stale files, just run mkdocs\nwith the --clean switch.

    \n
    mkdocs build --clean\n
    \n\n

    Other Commands and Options\uf0c1

    \n

    There are various other commands and options available. For a complete list of\ncommands, use the --help flag:

    \n
    mkdocs --help\n
    \n\n

    To view a list of options available on a given command, use the --help flag\nwith that command. For example, to get a list of all options available for the\nbuild command run the following:

    \n
    mkdocs build --help\n
    \n\n

    Deploying\uf0c1

    \n

    The documentation site that we've just built only uses static files so you'll be\nable to host it from pretty much anywhere. GitHub project pages and Amazon\nS3 are good hosting options. Upload the contents of the entire site directory\nto wherever you're hosting your website from and you're done. For specific\ninstructions for a number of common hosts, see the Deploying your Docs page.

    \n

    Getting help\uf0c1

    \n

    To get help with MkDocs, please use the discussion group, GitHub issues or\nthe MkDocs IRC channel #mkdocs on freenode.

    ", + "url": "/", + "language": "en", + "title": "Home" +} \ No newline at end of file diff --git a/license/highlight.js/LICENSE b/license/highlight.js/LICENSE new file mode 100644 index 00000000..422deb73 --- /dev/null +++ b/license/highlight.js/LICENSE @@ -0,0 +1,24 @@ +Copyright (c) 2006, Ivan Sagalaev +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. + * Neither the name of highlight.js nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS AND 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. diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json index aed1e0c5..81f62b41 100644 --- a/mkdocs/search_index.json +++ b/mkdocs/search_index.json @@ -552,7 +552,7 @@ }, { "location": "/about/release-notes/", - "text": "Release Notes\n\uf0c1\n\n\n\n\nUpgrading\n\uf0c1\n\n\nTo upgrade MkDocs to the latest version, use pip:\n\n\npip install -U mkdocs\n\n\n\nYou can determine your currently installed version using \nmkdocs --version\n:\n\n\n$ mkdocs --version\nmkdocs, version 0.14.0\n\n\n\nVersion 0.15.0 (2016-01-21)\n\uf0c1\n\n\nMajor Additions to Version 0.15.0\n\uf0c1\n\n\nAdd support for installable themes\n\uf0c1\n\n\nMkDocs now supports themes that are distributed via Python packages. With this\naddition, the Bootstrap and Bootswatch themes have been moved to external git\nrepositories and python packages. See their individual documentation for more\ndetails about these specific themes.\n\n\n\n\nMkDocs Bootstrap\n\n\nMkDocs Bootswatch\n\n\n\n\nThey will be included with MkDocs by default until the 1.0 release. After that\nthey will be installable with pip: \npip install mkdocs-bootstrap\n and \npip\ninstall mkdocs-bootswatch\n\n\nSee the documentation for \nStyling your docs\n for more information about using\nand customising themes and \nCustom themes\n for creating and distributing new\nthemes\n\n\nOther Changes and Additions to Version 0.15.0\n\uf0c1\n\n\n\n\nFix issues when using absolute links to Markdown files. (#628)\n\n\nDeprecate support of Python 2.6, pending removal in 1.0.0. (#165)\n\n\nAdd official support for Python version 3.5.\n\n\nAdd support for \nsite_description\n and \nsite_author\n to the \nReadTheDocs\n\n theme. (#631)\n\n\nUpdate FontAwesome to 4.5.0. (#789)\n\n\nIncrease IE support with X-UA-Compatible. (#785)\n\n\nAdded support for Python's \n-m\n flag. (#706)\n\n\nBugfix: Ensure consistent ordering of auto-populated pages. (#638)\n\n\nBugfix: Scroll the tables of contents on the MkDocs theme if it is too long\n for the page. (#204)\n\n\nBugfix: Add all ancestors to the page attribute \nancestors\n rather than just\n the initial one. (#693)\n\n\nBugfix: Include HTML in the build output again. (#691)\n\n\nBugfix: Provide filename to Read the Docs. (#721 and RTD#1480)\n\n\nBugfix: Silence Click's unicode_literals warning. (#708)\n\n\n\n\nVersion 0.14.0 (2015-06-09)\n\uf0c1\n\n\n\n\nImprove Unicode handling by ensuring that all config strings are loaded as\n Unicode. (#592)\n\n\nRemove dependancy on the six library. (#583)\n\n\nRemove dependancy on the ghp-import library. (#547)\n\n\nAdd \n--quiet\n and \n--verbose\n options to all subcommands. (#579)\n\n\nAdd short options (\n-a\n) to most command line options. (#579)\n\n\nAdd copyright footer for readthedocs theme. (#568)\n\n\nIf the requested port in \nmkdocs serve\n is already in use, don't show the\n user a full stack trace. (#596)\n\n\nBugfix: Fix a JavaScript encoding problem when searching with spaces. (#586)\n\n\nBugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root.\n (#578)\n\n\nBugfix: Handle (pass-through instead of dropping) HTML entities while\n parsing TOC. (#612)\n\n\nBugfix: Default extra_templates to an empty list, don't automatically\n discover them. (#616)\n\n\n\n\nVersion 0.13.3 (2015-06-02)\n\uf0c1\n\n\n\n\nBugfix: Reduce validation error to a warning if the site_dir is within\n the docs_dir as this shouldn't cause any problems with building but will\n inconvenience users building multiple times. (#580)\n\n\n\n\nVersion 0.13.2 (2015-05-30)\n\uf0c1\n\n\n\n\nBugfix: Ensure all errors and warnings are logged before exiting. (#536)\n\n\nBugfix: Fix compatibility issues with ReadTheDocs. (#554)\n\n\n\n\nVersion 0.13.1 (2015-05-27)\n\uf0c1\n\n\n\n\nBugfix: Fix a problem with minimal configurations which only contain a list\n of paths in the pages config. (#562)\n\n\n\n\nVersion 0.13.0 (2015-05-26)\n\uf0c1\n\n\nDeprecations to Version 0.13.0\n\uf0c1\n\n\nDeprecate the JSON command\n\uf0c1\n\n\nIn this release the \nmkdocs json\n command has been marked as deprecated and\nwhen used a deprecation warning will be shown. It will be removed in a \nfuture\nrelease\n of MkDocs, version 1.0 at the latest. The \nmkdocs json\n command\nprovided a convenient way for users to output the documentation contents as\nJSON files but with the additions of search to MkDocs this functionality is\nduplicated.\n\n\nA new index with all the contents from a MkDocs build is created in the\n\nsite_dir\n, so with the default value for the \nsite_dir\n It can be found in\n\nsite/mkdocs/search_index.json\n.\n\n\nThis new file is created on every MkDocs build (with \nmkdocs build\n) and\nno configuration is needed to enable it.\n\n\nChange the pages configuration\n\uf0c1\n\n\nProvide a \nnew way\n to define pages, and specifically \nnested pages\n, in the\nmkdocs.yml file and deprecate the existing approach, support will be removed\nwith MkDocs 1.0.\n\n\nWarn users about the removal of builtin themes\n\uf0c1\n\n\nAll themes other than mkdocs and readthedocs will be moved into external\npackages in a future release of MkDocs. This will enable them to be more easily\nsupported and updates outside MkDocs releases.\n\n\nMajor Additions to Version 0.13.0\n\uf0c1\n\n\nSearch\n\uf0c1\n\n\nSupport for search has now been added to MkDocs. This is based on the\nJavaScript library \nlunr.js\n. It has been added to both the \nmkdocs\n and\n\nreadthedocs\n themes. See the custom theme documentation on \nsupporting search\n\nfor adding it to your own themes.\n\n\nNew Command Line Interface\n\uf0c1\n\n\nThe command line interface for MkDocs has been re-written with the Python\nlibrary \nClick\n. This means that MkDocs now has an easier to use interface\nwith better help output.\n\n\nThis change is partially backwards incompatible as while undocumented it was\npossible to pass any configuration option to the different commands. Now only\na small subset of the configuration options can be passed to the commands. To\nsee in full commands and available arguments use \nmkdocs --help\n and\n\nmkdocs build --help\n to have them displayed.\n\n\nSupport Extra HTML and XML files\n\uf0c1\n\n\nLike the \nextra_javascript\n and \nextra_css\n configuration options, a new\noption named \nextra_templates\n has been added. This will automatically be\npopulated with any \n.html\n or \n.xml\n files in the project docs directory.\n\n\nUsers can place static HTML and XML files and they will be copied over, or they\ncan also use Jinja2 syntax and take advantage of the \nglobal variables\n.\n\n\nBy default MkDocs will use this approach to create a sitemap for the\ndocumentation.\n\n\nOther Changes and Additions to Version 0.13.0\n\uf0c1\n\n\n\n\nAdd support for \nMarkdown extension configuration options\n. (#435)\n\n\nMkDocs now ships Python \nwheels\n. (#486)\n\n\nOnly include the build date and MkDocs version on the homepage. (#490)\n\n\nGenerate sitemaps for documentation builds. (#436)\n\n\nAdd a clearer way to define nested pages in the configuration. (#482)\n\n\nAdd an \nextra config\n option for passing arbitrary variables to the template. (#510)\n\n\nAdd \n--no-livereload\n to \nmkdocs serve\n for a simpler development server. (#511)\n\n\nAdd copyright display support to all themes (#549)\n\n\nAdd support for custom commit messages in a \nmkdocs gh-deploy\n (#516)\n\n\nBugfix: Fix linking to media within the same directory as a markdown file\n called index.md (#535)\n\n\nBugfix: Fix errors with unicode filenames (#542).\n\n\n\n\nVersion 0.12.2 (2015-04-22)\n\uf0c1\n\n\n\n\nBugfix: Fix a regression where there would be an error if some child titles\n were missing but others were provided in the pages config. (#464)\n\n\n\n\nVersion 0.12.1 (2015-04-14)\n\uf0c1\n\n\n\n\nBugfix: Fixed a CSS bug in the table of contents on some browsers where the\n bottom item was not clickable.\n\n\n\n\nVersion 0.12.0 (2015-04-14)\n\uf0c1\n\n\n\n\nDisplay the current MkDocs version in the CLI output. (#258)\n\n\nCheck for CNAME file when using gh-deploy. (#285)\n\n\nAdd the homepage back to the navigation on all themes. (#271)\n\n\nAdd a strict more for local link checking. (#279)\n\n\nAdd Google analytics support to all themes. (#333)\n\n\nAdd build date and MkDocs version to the ReadTheDocs and MkDocs theme\n outputs. (#382)\n\n\nStandardise highlighting across all themes and add missing languages. (#387)\n\n\nAdd a verbose flag. (-v) to show more details about what the build. (#147)\n\n\nAdd the option to specify a remote branch when deploying to GitHub. This\n enables deploying to GitHub pages on personal and repo sites. (#354)\n\n\nAdd favicon support to the ReadTheDocs theme HTML. (#422)\n\n\nAutomatically refresh the browser when files are edited. (#163)\n\n\nBugfix: Never re-write URL's in code blocks. (#240)\n\n\nBugfix: Don't copy ditfiles when copying media from the \ndocs_dir\n. (#254)\n\n\nBugfix: Fix the rendering of tables in the ReadTheDocs theme. (#106)\n\n\nBugfix: Add padding to the bottom of all bootstrap themes. (#255)\n\n\nBugfix: Fix issues with nested Markdown pages and the automatic pages\n configuration. (#276)\n\n\nBugfix: Fix a URL parsing error with GitHub enterprise. (#284)\n\n\nBugfix: Don't error if the mkdocs.yml is completely empty. (#288)\n\n\nBugfix: Fix a number of problems with relative urls and Markdown files. (#292)\n\n\nBugfix: Don't stop the build if a page can't be found, continue with other\n pages. (#150)\n\n\nBugfix: Remove the site_name from the page title, this needs to be added\n manually. (#299)\n\n\nBugfix: Fix an issue with table of contents cutting off Markdown. (#294)\n\n\nBugfix: Fix hostname for BitBucket. (#339)\n\n\nBugfix: Ensure all links end with a slash. (#344)\n\n\nBugfix: Fix repo links in the readthedocs theme. (#365)\n\n\nBugfix: Include jQuery locally to avoid problems using MkDocs offline. (#143)\n\n\nBugfix: Don't allow the docs_dir to be in the site_dir or vice versa. (#384)\n\n\nBugfix: Remove inline CSS in the ReadTheDocs theme. (#393)\n\n\nBugfix: Fix problems with the child titles due to the order the pages config\n was processed. (#395)\n\n\nBugfix: Don't error during live reload when the theme doesn't exist. (#373)\n\n\nBugfix: Fix problems with the Meta extension when it may not exist. (#398)\n\n\nBugfix: Wrap long inline code otherwise they will run off the screen. (#313)\n\n\nBugfix: Remove HTML parsing regular expressions and parse with HTMLParser to\n fix problems with titles containing code. (#367)\n\n\nBugfix: Fix an issue with the scroll to anchor causing the title to be hidden\n under the navigation. (#7)\n\n\nBugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. (#295)\n\n\nBugfix: Fix an error when passing in a specific config file with\n \nmkdocs serve\n. (#341)\n\n\nBugfix: Don't overwrite index.md diles with the \nmkdocs new\n command. (#412)\n\n\nBugfix: Remove bold and italic from code in the ReadTheDocs theme. (#411)\n\n\nBugfix: Display images inline in the MkDocs theme. (#415)\n\n\nBugfix: Fix problems with no-highlight in the ReadTheDocs theme. (#319)\n\n\nBugfix: Don't delete hidden files when using \nmkdocs build --clean\n. (#346)\n\n\nBugfix: Don't block newer verions of Python-markdown on Python \n= 2.7. (#376)\n\n\nBugfix: Fix encoding issues when opening files across platforms. (#428)\n\n\n\n\nVersion 0.11.1 (2014-11-20)\n\uf0c1\n\n\n\n\nBugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs\n theme. (#233)\n\n\n\n\nVersion 0.11.0 (2014-11-18)\n\uf0c1\n\n\n\n\nRender 404.html files if they exist for the current theme. (#194)\n\n\nBugfix: Fix long nav bars, table rendering and code highlighting in MkDocs\n and ReadTheDocs themes. (#225)\n\n\nBugfix: Fix an issue with the google_analytics code. (#219)\n\n\nBugfix: Remove \n__pycache__\n from the package tar. (#196)\n\n\nBugfix: Fix markdown links that go to an anchor on the current page. (#197)\n\n\nBugfix: Don't add \nprettyprint well\n CSS classes to all HTML, only add it in\n the MkDocs theme. (#183)\n\n\nBugfix: Display section titles in the ReadTheDocs theme. (#175)\n\n\nBugfix: Use the polling observer in watchdog so rebuilding works on\n filesystems without inotify. (#184)\n\n\nBugfix: Improve error output for common configuration related errors. (#176)\n\n\n\n\nVersion 0.10.0 (2014-10-29)\n\uf0c1\n\n\n\n\nAdded support for Python 3.3 and 3.4. (#103)\n\n\nConfigurable Python-Markdown extensions with the config setting\n \nmarkdown_extensions\n. (#74)\n\n\nAdded \nmkdocs json\n command to output your rendered\n documentation as json files. (#128)\n\n\nAdded \n--clean\n switch to \nbuild\n, \njson\n and \ngh-deploy\n commands to\n remove stale files from the output directory. (#157)\n\n\nSupport multiple theme directories to allow replacement of\n individual templates rather than copying the full theme. (#129)\n\n\nBugfix: Fix \nul\n rendering in readthedocs theme. (#171)\n\n\nBugfix: Improve the readthedocs theme on smaller displays. (#168)\n\n\nBugfix: Relaxed required python package versions to avoid clashes. (#104)\n\n\nBugfix: Fix issue rendering the table of contents with some configs. (#146)\n\n\nBugfix: Fix path for embedded images in sub pages. (#138)\n\n\nBugfix: Fix \nuse_directory_urls\n config behaviour. (#63)\n\n\nBugfix: Support \nextra_javascript\n and \nextra_css\n in all themes. (#90)\n\n\nBugfix: Fix path-handling under Windows. (#121)\n\n\nBugfix: Fix the menu generation in the readthedocs theme. (#110)\n\n\nBugfix: Fix the mkdocs command creation under Windows. (#122)\n\n\nBugfix: Correctly handle external \nextra_javascript\n and \nextra_css\n. (#92)\n\n\nBugfix: Fixed favicon support. (#87)", + "text": "Release Notes\n\uf0c1\n\n\n\n\nUpgrading\n\uf0c1\n\n\nTo upgrade MkDocs to the latest version, use pip:\n\n\npip install -U mkdocs\n\n\n\nYou can determine your currently installed version using \nmkdocs --version\n:\n\n\n$ mkdocs --version\nmkdocs, version 0.14.0\n\n\n\nVersion 0.15.1 (2016-01-30)\n\uf0c1\n\n\n\n\nLower the minimum supported Click version to 3.3 for upstream\n package maintainers.\n\n\n\n\nVersion 0.15.0 (2016-01-21)\n\uf0c1\n\n\nMajor Additions to Version 0.15.0\n\uf0c1\n\n\nAdd support for installable themes\n\uf0c1\n\n\nMkDocs now supports themes that are distributed via Python packages. With this\naddition, the Bootstrap and Bootswatch themes have been moved to external git\nrepositories and python packages. See their individual documentation for more\ndetails about these specific themes.\n\n\n\n\nMkDocs Bootstrap\n\n\nMkDocs Bootswatch\n\n\n\n\nThey will be included with MkDocs by default until the 1.0 release. After that\nthey will be installable with pip: \npip install mkdocs-bootstrap\n and \npip\ninstall mkdocs-bootswatch\n\n\nSee the documentation for \nStyling your docs\n for more information about using\nand customising themes and \nCustom themes\n for creating and distributing new\nthemes\n\n\nOther Changes and Additions to Version 0.15.0\n\uf0c1\n\n\n\n\nFix issues when using absolute links to Markdown files. (#628)\n\n\nDeprecate support of Python 2.6, pending removal in 1.0.0. (#165)\n\n\nAdd official support for Python version 3.5.\n\n\nAdd support for \nsite_description\n and \nsite_author\n to the \nReadTheDocs\n\n theme. (#631)\n\n\nUpdate FontAwesome to 4.5.0. (#789)\n\n\nIncrease IE support with X-UA-Compatible. (#785)\n\n\nAdded support for Python's \n-m\n flag. (#706)\n\n\nBugfix: Ensure consistent ordering of auto-populated pages. (#638)\n\n\nBugfix: Scroll the tables of contents on the MkDocs theme if it is too long\n for the page. (#204)\n\n\nBugfix: Add all ancestors to the page attribute \nancestors\n rather than just\n the initial one. (#693)\n\n\nBugfix: Include HTML in the build output again. (#691)\n\n\nBugfix: Provide filename to Read the Docs. (#721 and RTD#1480)\n\n\nBugfix: Silence Click's unicode_literals warning. (#708)\n\n\n\n\nVersion 0.14.0 (2015-06-09)\n\uf0c1\n\n\n\n\nImprove Unicode handling by ensuring that all config strings are loaded as\n Unicode. (#592)\n\n\nRemove dependancy on the six library. (#583)\n\n\nRemove dependancy on the ghp-import library. (#547)\n\n\nAdd \n--quiet\n and \n--verbose\n options to all subcommands. (#579)\n\n\nAdd short options (\n-a\n) to most command line options. (#579)\n\n\nAdd copyright footer for readthedocs theme. (#568)\n\n\nIf the requested port in \nmkdocs serve\n is already in use, don't show the\n user a full stack trace. (#596)\n\n\nBugfix: Fix a JavaScript encoding problem when searching with spaces. (#586)\n\n\nBugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root.\n (#578)\n\n\nBugfix: Handle (pass-through instead of dropping) HTML entities while\n parsing TOC. (#612)\n\n\nBugfix: Default extra_templates to an empty list, don't automatically\n discover them. (#616)\n\n\n\n\nVersion 0.13.3 (2015-06-02)\n\uf0c1\n\n\n\n\nBugfix: Reduce validation error to a warning if the site_dir is within\n the docs_dir as this shouldn't cause any problems with building but will\n inconvenience users building multiple times. (#580)\n\n\n\n\nVersion 0.13.2 (2015-05-30)\n\uf0c1\n\n\n\n\nBugfix: Ensure all errors and warnings are logged before exiting. (#536)\n\n\nBugfix: Fix compatibility issues with ReadTheDocs. (#554)\n\n\n\n\nVersion 0.13.1 (2015-05-27)\n\uf0c1\n\n\n\n\nBugfix: Fix a problem with minimal configurations which only contain a list\n of paths in the pages config. (#562)\n\n\n\n\nVersion 0.13.0 (2015-05-26)\n\uf0c1\n\n\nDeprecations to Version 0.13.0\n\uf0c1\n\n\nDeprecate the JSON command\n\uf0c1\n\n\nIn this release the \nmkdocs json\n command has been marked as deprecated and\nwhen used a deprecation warning will be shown. It will be removed in a \nfuture\nrelease\n of MkDocs, version 1.0 at the latest. The \nmkdocs json\n command\nprovided a convenient way for users to output the documentation contents as\nJSON files but with the additions of search to MkDocs this functionality is\nduplicated.\n\n\nA new index with all the contents from a MkDocs build is created in the\n\nsite_dir\n, so with the default value for the \nsite_dir\n It can be found in\n\nsite/mkdocs/search_index.json\n.\n\n\nThis new file is created on every MkDocs build (with \nmkdocs build\n) and\nno configuration is needed to enable it.\n\n\nChange the pages configuration\n\uf0c1\n\n\nProvide a \nnew way\n to define pages, and specifically \nnested pages\n, in the\nmkdocs.yml file and deprecate the existing approach, support will be removed\nwith MkDocs 1.0.\n\n\nWarn users about the removal of builtin themes\n\uf0c1\n\n\nAll themes other than mkdocs and readthedocs will be moved into external\npackages in a future release of MkDocs. This will enable them to be more easily\nsupported and updates outside MkDocs releases.\n\n\nMajor Additions to Version 0.13.0\n\uf0c1\n\n\nSearch\n\uf0c1\n\n\nSupport for search has now been added to MkDocs. This is based on the\nJavaScript library \nlunr.js\n. It has been added to both the \nmkdocs\n and\n\nreadthedocs\n themes. See the custom theme documentation on \nsupporting search\n\nfor adding it to your own themes.\n\n\nNew Command Line Interface\n\uf0c1\n\n\nThe command line interface for MkDocs has been re-written with the Python\nlibrary \nClick\n. This means that MkDocs now has an easier to use interface\nwith better help output.\n\n\nThis change is partially backwards incompatible as while undocumented it was\npossible to pass any configuration option to the different commands. Now only\na small subset of the configuration options can be passed to the commands. To\nsee in full commands and available arguments use \nmkdocs --help\n and\n\nmkdocs build --help\n to have them displayed.\n\n\nSupport Extra HTML and XML files\n\uf0c1\n\n\nLike the \nextra_javascript\n and \nextra_css\n configuration options, a new\noption named \nextra_templates\n has been added. This will automatically be\npopulated with any \n.html\n or \n.xml\n files in the project docs directory.\n\n\nUsers can place static HTML and XML files and they will be copied over, or they\ncan also use Jinja2 syntax and take advantage of the \nglobal variables\n.\n\n\nBy default MkDocs will use this approach to create a sitemap for the\ndocumentation.\n\n\nOther Changes and Additions to Version 0.13.0\n\uf0c1\n\n\n\n\nAdd support for \nMarkdown extension configuration options\n. (#435)\n\n\nMkDocs now ships Python \nwheels\n. (#486)\n\n\nOnly include the build date and MkDocs version on the homepage. (#490)\n\n\nGenerate sitemaps for documentation builds. (#436)\n\n\nAdd a clearer way to define nested pages in the configuration. (#482)\n\n\nAdd an \nextra config\n option for passing arbitrary variables to the template. (#510)\n\n\nAdd \n--no-livereload\n to \nmkdocs serve\n for a simpler development server. (#511)\n\n\nAdd copyright display support to all themes (#549)\n\n\nAdd support for custom commit messages in a \nmkdocs gh-deploy\n (#516)\n\n\nBugfix: Fix linking to media within the same directory as a markdown file\n called index.md (#535)\n\n\nBugfix: Fix errors with unicode filenames (#542).\n\n\n\n\nVersion 0.12.2 (2015-04-22)\n\uf0c1\n\n\n\n\nBugfix: Fix a regression where there would be an error if some child titles\n were missing but others were provided in the pages config. (#464)\n\n\n\n\nVersion 0.12.1 (2015-04-14)\n\uf0c1\n\n\n\n\nBugfix: Fixed a CSS bug in the table of contents on some browsers where the\n bottom item was not clickable.\n\n\n\n\nVersion 0.12.0 (2015-04-14)\n\uf0c1\n\n\n\n\nDisplay the current MkDocs version in the CLI output. (#258)\n\n\nCheck for CNAME file when using gh-deploy. (#285)\n\n\nAdd the homepage back to the navigation on all themes. (#271)\n\n\nAdd a strict more for local link checking. (#279)\n\n\nAdd Google analytics support to all themes. (#333)\n\n\nAdd build date and MkDocs version to the ReadTheDocs and MkDocs theme\n outputs. (#382)\n\n\nStandardise highlighting across all themes and add missing languages. (#387)\n\n\nAdd a verbose flag. (-v) to show more details about what the build. (#147)\n\n\nAdd the option to specify a remote branch when deploying to GitHub. This\n enables deploying to GitHub pages on personal and repo sites. (#354)\n\n\nAdd favicon support to the ReadTheDocs theme HTML. (#422)\n\n\nAutomatically refresh the browser when files are edited. (#163)\n\n\nBugfix: Never re-write URL's in code blocks. (#240)\n\n\nBugfix: Don't copy ditfiles when copying media from the \ndocs_dir\n. (#254)\n\n\nBugfix: Fix the rendering of tables in the ReadTheDocs theme. (#106)\n\n\nBugfix: Add padding to the bottom of all bootstrap themes. (#255)\n\n\nBugfix: Fix issues with nested Markdown pages and the automatic pages\n configuration. (#276)\n\n\nBugfix: Fix a URL parsing error with GitHub enterprise. (#284)\n\n\nBugfix: Don't error if the mkdocs.yml is completely empty. (#288)\n\n\nBugfix: Fix a number of problems with relative urls and Markdown files. (#292)\n\n\nBugfix: Don't stop the build if a page can't be found, continue with other\n pages. (#150)\n\n\nBugfix: Remove the site_name from the page title, this needs to be added\n manually. (#299)\n\n\nBugfix: Fix an issue with table of contents cutting off Markdown. (#294)\n\n\nBugfix: Fix hostname for BitBucket. (#339)\n\n\nBugfix: Ensure all links end with a slash. (#344)\n\n\nBugfix: Fix repo links in the readthedocs theme. (#365)\n\n\nBugfix: Include jQuery locally to avoid problems using MkDocs offline. (#143)\n\n\nBugfix: Don't allow the docs_dir to be in the site_dir or vice versa. (#384)\n\n\nBugfix: Remove inline CSS in the ReadTheDocs theme. (#393)\n\n\nBugfix: Fix problems with the child titles due to the order the pages config\n was processed. (#395)\n\n\nBugfix: Don't error during live reload when the theme doesn't exist. (#373)\n\n\nBugfix: Fix problems with the Meta extension when it may not exist. (#398)\n\n\nBugfix: Wrap long inline code otherwise they will run off the screen. (#313)\n\n\nBugfix: Remove HTML parsing regular expressions and parse with HTMLParser to\n fix problems with titles containing code. (#367)\n\n\nBugfix: Fix an issue with the scroll to anchor causing the title to be hidden\n under the navigation. (#7)\n\n\nBugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. (#295)\n\n\nBugfix: Fix an error when passing in a specific config file with\n \nmkdocs serve\n. (#341)\n\n\nBugfix: Don't overwrite index.md diles with the \nmkdocs new\n command. (#412)\n\n\nBugfix: Remove bold and italic from code in the ReadTheDocs theme. (#411)\n\n\nBugfix: Display images inline in the MkDocs theme. (#415)\n\n\nBugfix: Fix problems with no-highlight in the ReadTheDocs theme. (#319)\n\n\nBugfix: Don't delete hidden files when using \nmkdocs build --clean\n. (#346)\n\n\nBugfix: Don't block newer verions of Python-markdown on Python \n= 2.7. (#376)\n\n\nBugfix: Fix encoding issues when opening files across platforms. (#428)\n\n\n\n\nVersion 0.11.1 (2014-11-20)\n\uf0c1\n\n\n\n\nBugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs\n theme. (#233)\n\n\n\n\nVersion 0.11.0 (2014-11-18)\n\uf0c1\n\n\n\n\nRender 404.html files if they exist for the current theme. (#194)\n\n\nBugfix: Fix long nav bars, table rendering and code highlighting in MkDocs\n and ReadTheDocs themes. (#225)\n\n\nBugfix: Fix an issue with the google_analytics code. (#219)\n\n\nBugfix: Remove \n__pycache__\n from the package tar. (#196)\n\n\nBugfix: Fix markdown links that go to an anchor on the current page. (#197)\n\n\nBugfix: Don't add \nprettyprint well\n CSS classes to all HTML, only add it in\n the MkDocs theme. (#183)\n\n\nBugfix: Display section titles in the ReadTheDocs theme. (#175)\n\n\nBugfix: Use the polling observer in watchdog so rebuilding works on\n filesystems without inotify. (#184)\n\n\nBugfix: Improve error output for common configuration related errors. (#176)\n\n\n\n\nVersion 0.10.0 (2014-10-29)\n\uf0c1\n\n\n\n\nAdded support for Python 3.3 and 3.4. (#103)\n\n\nConfigurable Python-Markdown extensions with the config setting\n \nmarkdown_extensions\n. (#74)\n\n\nAdded \nmkdocs json\n command to output your rendered\n documentation as json files. (#128)\n\n\nAdded \n--clean\n switch to \nbuild\n, \njson\n and \ngh-deploy\n commands to\n remove stale files from the output directory. (#157)\n\n\nSupport multiple theme directories to allow replacement of\n individual templates rather than copying the full theme. (#129)\n\n\nBugfix: Fix \nul\n rendering in readthedocs theme. (#171)\n\n\nBugfix: Improve the readthedocs theme on smaller displays. (#168)\n\n\nBugfix: Relaxed required python package versions to avoid clashes. (#104)\n\n\nBugfix: Fix issue rendering the table of contents with some configs. (#146)\n\n\nBugfix: Fix path for embedded images in sub pages. (#138)\n\n\nBugfix: Fix \nuse_directory_urls\n config behaviour. (#63)\n\n\nBugfix: Support \nextra_javascript\n and \nextra_css\n in all themes. (#90)\n\n\nBugfix: Fix path-handling under Windows. (#121)\n\n\nBugfix: Fix the menu generation in the readthedocs theme. (#110)\n\n\nBugfix: Fix the mkdocs command creation under Windows. (#122)\n\n\nBugfix: Correctly handle external \nextra_javascript\n and \nextra_css\n. (#92)\n\n\nBugfix: Fixed favicon support. (#87)", "title": "Release Notes" }, { @@ -565,6 +565,11 @@ "text": "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\nmkdocs, version 0.14.0", "title": "Upgrading" }, + { + "location": "/about/release-notes/#version-0151-2016-01-30", + "text": "Lower the minimum supported Click version to 3.3 for upstream\n package maintainers.", + "title": "Version 0.15.1 (2016-01-30)" + }, { "location": "/about/release-notes/#version-0150-2016-01-21", "text": "", diff --git a/sitemap.xml b/sitemap.xml index 830e26a3..ef6f557a 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -4,7 +4,7 @@ http://www.mkdocs.org/ - 2016-01-21 + 2016-01-30 daily @@ -13,31 +13,31 @@ http://www.mkdocs.org/user-guide/writing-your-docs/ - 2016-01-21 + 2016-01-30 daily http://www.mkdocs.org/user-guide/styling-your-docs/ - 2016-01-21 + 2016-01-30 daily http://www.mkdocs.org/user-guide/configuration/ - 2016-01-21 + 2016-01-30 daily http://www.mkdocs.org/user-guide/deploying-your-docs/ - 2016-01-21 + 2016-01-30 daily http://www.mkdocs.org/user-guide/custom-themes/ - 2016-01-21 + 2016-01-30 daily @@ -47,19 +47,19 @@ http://www.mkdocs.org/about/release-notes/ - 2016-01-21 + 2016-01-30 daily http://www.mkdocs.org/about/contributing/ - 2016-01-21 + 2016-01-30 daily http://www.mkdocs.org/about/license/ - 2016-01-21 + 2016-01-30 daily diff --git a/user-guide/configuration/index.json b/user-guide/configuration/index.json new file mode 100644 index 00000000..13543d0b --- /dev/null +++ b/user-guide/configuration/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    Configuration\uf0c1

    \n

    Guide to all available configuration settings.

    \n
    \n

    Introduction\uf0c1

    \n

    Project settings are always configured by using a YAML configuration file in the\nproject directory named mkdocs.yml.

    \n

    As a minimum this configuration file must contain the site_name setting. All\nother settings are optional.

    \n

    Project information\uf0c1

    \n

    site_name\uf0c1

    \n

    This is a required setting, and should be a string that is used as the main\ntitle for the project documentation. For example:

    \n
    site_name: Marshmallow Generator\n
    \n\n

    When rendering the theme this setting will be passed as the site_name context\nvariable.

    \n

    site_url\uf0c1

    \n

    Set the canonical URL of the site. This will add a link tag with the canonical\nURL to the generated HTML header.

    \n

    default: null

    \n

    repo_url\uf0c1

    \n

    When set, provides a link to your GitHub or Bitbucket repository on each page.

    \n
    repo_url: https://github.com/example/repository/\n
    \n\n

    default: null

    \n

    repo_name\uf0c1

    \n

    When set, provides a link to your GitHub or Bitbucket repository on each page.

    \n

    default: 'GitHub' or 'Bitbucket' if the repo_url matches those\ndomains, otherwise null

    \n

    site_description\uf0c1

    \n

    Set the site description. This will add a meta tag to the generated HTML header.

    \n

    default: null

    \n

    site_author\uf0c1

    \n

    Set the name of the author. This will add a meta tag to the generated HTML\nheader.

    \n

    default: null

    \n

    site_favicon\uf0c1

    \n

    Set the favicon to use. Putting a favicon.ico into the docs/ directory, the\nconfig would look as follows:

    \n
    site_favicon: favicon.ico\n
    \n\n

    default: null

    \n

    copyright\uf0c1

    \n

    Set the copyright information to be included in the documentation by the theme.

    \n

    default: null

    \n

    google_analytics\uf0c1

    \n

    Set the Google analytics tracking configuration.

    \n
    google_analytics: ['UA-36723568-3', 'mkdocs.org']\n
    \n\n

    default: null

    \n

    remote_branch\uf0c1

    \n

    Set the remote branch to commit to when using gh-deploy to deploy to Github\nPages. This option can be overridden by a command line option in gh-deploy.

    \n

    default: gh-pages

    \n

    remote_name\uf0c1

    \n

    Set the remote name to push to when using gh-deploy to deploy to Github Pages.\nThis option can be overridden by a command line option in gh-deploy.

    \n

    default: gh-pages

    \n

    Documentation layout\uf0c1

    \n

    pages\uf0c1

    \n

    This setting is used to determine the set of pages that should be built for the\ndocumentation. For example, the following would create Introduction, User Guide\nand About pages, given the three source files index.md, user-guide.md and\nabout.md, respectively.

    \n
    pages:\n    - 'Introduction': 'index.md'\n    - 'User Guide': 'user-guide.md'\n    - 'About': 'about.md'\n
    \n\n

    See the section on configuring pages and\nnavigation for\na more detailed breakdown, including how to create sub-sections.

    \n

    Build directories\uf0c1

    \n

    theme\uf0c1

    \n

    Sets the theme of your documentation site, for a list of available themes visit\nstyling your docs.

    \n

    default: 'mkdocs'

    \n

    theme_dir\uf0c1

    \n

    Lets you set a directory to a custom theme. This can either be a relative\ndirectory, in which case it is resolved relative to the directory containing\nyour configuration file, or it can be an absolute directory path.

    \n

    See styling your docs for an explanation\nof custom themes.

    \n

    default: null

    \n

    docs_dir\uf0c1

    \n

    Lets you set the directory containing the documentation source markdown files.\nThis can either be a relative directory, in which case it is resolved relative\nto the directory containing you configuration file, or it can be an absolute\ndirectory path.

    \n

    default: 'docs'

    \n

    site_dir\uf0c1

    \n

    Lets you set the directory where the output HTML and other files are created.\nThis can either be a relative directory, in which case it is resolved relative\nto the directory containing you configuration file, or it can be an absolute\ndirectory path.

    \n

    default: 'site'

    \n
    \n

    Note:

    \n

    If you are using source code control you will normally want to ensure that\nyour build output files are not committed into the repository, and only\nkeep the source files under version control. For example, if using git\nyou might add the following line to your .gitignore file:

    \n
    site/\n
    \n

    If you're using another source code control tool, you'll want to check its\ndocumentation on how to ignore specific directories.

    \n
    \n

    extra_css\uf0c1

    \n

    Set a list of CSS files to be included by the theme. For example, the\nfollowing example will include the the extra.css file within the css\nsubdirectory in your docs_dir.

    \n
    extra_css:\n    - css/extra.css\n    - css/second_extra.css\n
    \n\n

    default: By default extra_css will contain a list of all the CSS files\nfound within the docs_dir, if none are found it will be [] (an empty list).

    \n

    extra_javascript\uf0c1

    \n

    Set a list of JavaScript files to be included by the theme. See the example\nin extra_css for usage.

    \n

    default: By default extra_javascript will contain a list of all the\nJavaScript files found within the docs_dir, if none are found it will be []\n(an empty list).

    \n

    extra_templates\uf0c1

    \n

    Set a list of templates to be built by MkDocs. To see more about writing\ntemplates for MkDocs read the documentation about custom themes and\nspecifically the section about the variables that are available to templates.\nSee the example in extra_css for usage.

    \n

    default: Unlike extra_css and extra_javascript, by default extra_templates\nwill be [] (an empty list).

    \n

    extra\uf0c1

    \n

    A set of key value pairs, where the values can be any valid YAML construct, that\nwill be passed to the template. This allows for great flexibility when creating\ncustom themes.

    \n

    For example, if you are using a theme that supports displaying the project\nversion, you can pass it to the theme like this:

    \n
    extra:\n    version: 1.0\n
    \n\n

    default: By default extra will be an empty key value mapping.

    \n

    Preview controls\uf0c1

    \n

    use_directory_urls\uf0c1

    \n

    This setting controls the style used for linking to pages within the\ndocumentation.

    \n

    The following table demonstrates how the URLs used on the site differ when\nsetting use_directory_urls to true or false.

    \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Source fileGenerated HTMLuse_directory_urls=trueuse_directory_urls=false
    index.mdindex.html//index.html
    api-guide.mdapi-guide/index.html/api-guide//api-guide/index.html
    about.mdabout/index.html/about//about/index.html
    \n

    The default style of use_directory_urls=true creates more user friendly URLs,\nand is usually what you'll want to use.

    \n

    The alternate style can occasionally be useful if you want your documentation to\nremain properly linked when opening pages directly from the file system, because\nit create links that point directly to the target file rather than the target\ndirectory.

    \n

    default: true

    \n

    strict\uf0c1

    \n

    Determines if a broken link to a page within the documentation is considered a\nwarning or an error (link to a page not listed in the pages setting). Set to\ntrue to halt processing when a broken link is found, false prints a warning.

    \n

    default: false

    \n

    dev_addr\uf0c1

    \n

    Determines the address used when running mkdocs serve. Setting this allows you\nto use another port, or allows you to make the service accessible over your\nlocal network by using the 0.0.0.0 address.

    \n

    As with all settings, you can set this from the command line, which can be\nuseful, for example:

    \n
    mkdocs serve --dev-addr=0.0.0.0:80  # Run on port 80, on the local network.\n
    \n\n

    default: '127.0.0.1:8000'

    \n

    Formatting options\uf0c1

    \n

    markdown_extensions\uf0c1

    \n

    MkDocs uses the Python Markdown library to translate Markdown files\ninto HTML. Python Markdown supports a variety of extensions\nthat customize how pages are formatted. This setting lets you enable a list of\nextensions beyond the ones that MkDocs uses by default (meta, toc, tables,\nand fenced_code).

    \n

    For example, to enable the SmartyPants typography extension, use:

    \n
    markdown_extensions:\n    - smarty\n
    \n\n

    Some extensions provide configuration options of their own. If you would like to\nset any configuration options, then you can nest a key/value mapping\n(option_name: option value) of any options that a given extension supports.\nSee the documentation for the extension you are using to determine what options\nthey support.

    \n

    For example, to enable permalinks in the (included) toc extension, use:

    \n
    markdown_extensions:\n    - toc:\n        permalink: True\n
    \n\n

    Note that a colon (:) must follow the extension name (toc) and then on a new\nline the option name and value must be indented and seperated by a colon. If you\nwould like to define multipe options for a single extension, each option must be\ndefined on a seperate line:

    \n
    markdown_extensions:\n    - toc:\n        permalink: True\n        separator: "_"\n
    \n\n

    Add an additional item to the list for each extension. If you have no\nconfiguration options to set for a specific extension, then simply omit options\nfor that extension:

    \n
    markdown_extensions:\n    - smarty\n    - toc:\n        permalink: True\n    - sane_lists\n
    \n\n
    \n

    See Also:

    \n

    The Python-Markdown documentation provides a list of extensions\nwhich are available out-of-the-box. For a list of configuration options\navailable for a given extension, see the documentation for that extension.

    \n

    You may also install and use various third party extensions. Consult\nthe documentation provided by those extensions for installation instructions\nand available configuration options.

    \n
    \n

    default: []

    ", + "url": "/user-guide/configuration/", + "language": "en", + "title": "Configuration" +} \ No newline at end of file diff --git a/user-guide/custom-themes/index.json b/user-guide/custom-themes/index.json new file mode 100644 index 00000000..2987a0ff --- /dev/null +++ b/user-guide/custom-themes/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    Custom themes\uf0c1

    \n

    A guide to creating and distributing custom themes.

    \n
    \n

    When creating a new theme, you can either follow the steps in this guide to\ncreate one from scratch or you can download the mkdocs-basic-theme as a\nbasic, yet complete, theme with all the boilerplate required. You can find\nthis base theme on GitHub.\nIt contains detailed comments in the code to describe the different features\nand their usage.

    \n

    Creating a custom theme\uf0c1

    \n

    The bare minimum required for a custom theme is a base.html Jinja2\ntemplate file. This should be placed in a directory which will be the\ntheme_dir and it should be created next to the mkdocs.yml configuration\nfile. Within mkdocs.yml, specify the theme_dir option and set it to the\nname of the directory containing base.html. For example, given this example\nproject layout:

    \n
    mkdocs.yml\ndocs/\n    index.md\n    about.md\ncustom_theme/\n    base.html\n    ...\n
    \n

    You would include the following setting to use the custom theme directory:

    \n
    theme_dir: 'custom_theme'\n
    \n

    If used in combination with the theme configuration value a custom theme can\nbe used to replace only specific parts of a built-in theme. For example, with\nthe above layout and if you set theme: mkdocs then the base.html file\nwould replace that in the theme but otherwise it would remain the same. This\nis useful if you want to make small adjustments to an existing theme.

    \n

    Basic theme\uf0c1

    \n

    The simplest base.html file is the following:

    \n
    <!DOCTYPE html>\n<html>\n  <head>\n    <title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>\n  </head>\n  <body>\n    {{ content }}\n  </body>\n</html>\n
    \n\n

    Article content from each page specified in mkdocs.yml is inserted using the\n{{ content }} tag. Stylesheets and scripts can be brought into this theme as\nwith a normal HTML file. Navbars and tables of contents can also be generated\nand included automatically, through the nav and toc objects, respectively.\nIf you wish to write your own theme, it is recommended to start with one of\nthe built-in themes and modify it accordingly.

    \n

    Template Variables\uf0c1

    \n

    Each template in a theme is built with a template context. These are the\nvariables that are available to themes. The context varies depending on the\ntemplate that is being built. At the moment templates are either built with\nthe global context or with a page specific context. The global context is used\nfor HTML pages that don't represent an individual Markdown document, for\nexample a 404.html page or search.html.

    \n

    Global Context\uf0c1

    \n

    The following variables in the context map directly the configuration options\n.

    \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Variable NameConfiguration name
    site_namesite_name
    site_authorsite_author
    faviconsite_favicon
    page_descriptionsite_description
    repo_urlrepo_url
    repo_namerepo_name
    site_urlsite_url
    extra_cssextra_css
    extra_javascriptextra_javascript
    extraextra
    include_navinclude_nav
    include_next_previnclude_next_prev
    copyrightcopyright
    google_analyticsgoogle_analytics
    \n

    The following variables provide information about the navigation and location.

    \n

    nav\uf0c1

    \n

    The nav variable is used to create the navigation for the documentation.\nFollowing is a basic usage example which outputs the first and second level\nnavigation as a nested list.

    \n
    <ul>\n  {% for nav_item in nav %}\n      {% if nav_item.children %}\n          <li>{{ nav_item.title }}\n              <ul>\n              {% for nav_item in nav_item.children %}\n                  <li class="{% if nav_item.active%}current{%endif%}">\n                      <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>\n                  </li>\n              {% endfor %}\n              </ul>\n          </li>\n      {% else %}\n          <li class="{% if nav_item.active%}current{%endif%}">\n              <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>\n          </li>\n      {% endif %}\n\n  {% endfor %}\n</ul>\n
    \n\n

    base_url\uf0c1

    \n

    The base_url provides a relative path to the root of the MkDocs project.\nThis makes it easy to include links to static assets in your theme. For\nexample, if your theme includes a js folder, to include theme.js from that\nfolder on all pages you would do this:

    \n
    <script src="{{ base_url }}/js/theme.js"></script>\n
    \n\n

    homepage_url\uf0c1

    \n

    Provides a relative path to the documentation homepage.

    \n

    mkdocs_version\uf0c1

    \n

    Contains the current MkDocs version.

    \n

    build_date_utc\uf0c1

    \n

    A Python datetime object that represents the date and time the documentation\nwas built in UTC. This is useful for showing how recently the documentation\nwas updated.

    \n

    Page Context\uf0c1

    \n

    The page context includes all of the above Global context and the following\nadditional variables.

    \n

    page_title\uf0c1

    \n

    Contains the Title for the current page.

    \n

    page_description\uf0c1

    \n

    Contains the description for the current page on the homepage, it is blank on\nother pages.

    \n

    content\uf0c1

    \n

    The rendered Markdown as HTML, this is the contents of the documentation.

    \n

    toc\uf0c1

    \n

    An object representing the Table of contents for a page. Displaying the table\nof contents as a simple list can be achieved like this.

    \n
    <ul>\n{% for toc_item in toc %}\n    <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>\n    {% for toc_item in toc_item.children %}\n        <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>\n    {% endfor %}\n{% endfor %}\n</ul>\n
    \n\n

    meta\uf0c1

    \n

    A mapping of the metadata included at the top of the markdown page. In this\nexample we define a source property above the page title.

    \n
    source: generics.py\n        mixins.py\n\n# Page title\n\nContent...\n
    \n\n

    A template can access this metadata for the page with the meta.source\nvariable. This could then be used to link to source files related to the\ndocumentation page.

    \n
    {% for filename in meta.source %}\n  <a class="github" href="https://github.com/.../{{ filename }}">\n    <span class="label label-info">{{ filename }}</span>\n  </a>\n{% endfor %}\n
    \n\n

    canonical_url\uf0c1

    \n

    The full, canonical URL to the current page. This includes the site_url from\nthe configuration.

    \n

    current_page\uf0c1

    \n

    The page object for the current page. The page path and url properties can be\ndisplayed like this.

    \n
    <h1>{{ current_page.title }}</h1>\n<p> This page is at {{ current_page.url }}</p>\n
    \n\n

    previous_page\uf0c1

    \n

    The page object for the previous page. The usage is the same as for\ncurrent_page.

    \n

    next_page\uf0c1

    \n

    The page object for the next page.The usage is the same as for current_page.

    \n

    Extra Context\uf0c1

    \n

    Additional variables can be passed to the template with the\nextra configuration option. This is a\nset of key value pairs that can make custom templates far more flexible.

    \n

    For example, this could be used to include the project version of all pages\nand a list of links related to the project. This can be achieved with the\nfollowing extra configuration:

    \n
    extra:\n    version: 0.13.0\n    links:\n        - https://github.com/mkdocs\n        - https://docs.readthedocs.org/en/latest/builds.html#mkdocs\n        - http://www.mkdocs.org/\n
    \n\n

    And then displayed with this HTML in the custom theme.

    \n
    {{ config.extra.version }}\n\n{% if config.extra.links %}\n  <ul>\n  {% for link in config.extra.links %}\n      <li>{{ link }}</li>\n  {% endfor %}\n  </ul>\n{% endif %}\n
    \n\n

    Search and themes\uf0c1

    \n

    As of MkDocs 0.13 client side search support has been added to MkDocs with\nLunr.js.

    \n

    Search can either be added to every page in the theme or to a dedicated\ntemplate which must be named search.html. The search template will be build\nwith the same name and can be viewable with mkdocs serve at\nhttp://localhost:8000/search.html. An example of the two different\napproaches can be seen by comparing the mkdocs and readthedocs themes.

    \n

    The following HTML needs to be added to the theme so the JavaScript is loaded\nfor Lunr.js.

    \n
    <script>var base_url = '{{ base_url }}';</script>\n<script data-main="{{ base_url }}/mkdocs/js/search.js" src="{{ base_url }}/mkdocs/js/require.js"></script>\n
    \n\n
    \n

    Note

    \n

    The above JavaScript will download the search index, for larger\ndocumentation projects this can be a heavy operation. In those cases, it\nis suggested that you either use the search.html approach to only\ninclude search on one page or load the JavaScript on an event like a form\nsubmit.

    \n
    \n

    This loads the JavaScript and sets a global variable base_url which allows\nthe JavaScript to make the links relative to the current page. The above\nJavaScript, with the following HTML in a search.html template will add a\nfull search implementation to your theme.

    \n
    <h1 id="search">Search Results</h1>\n\n<form action="search.html">\n  <input name="q" id="mkdocs-search-query" type="text" >\n</form>\n\n<div id="mkdocs-search-results">\n  Sorry, page not found.\n</div>\n
    \n\n

    This works by looking for the specific ID's used in the above HTML. The input\nfor the user to type the search query must have the ID mkdocs-search-query\nand mkdocs-search-results is the directory where the results will be placed.

    \n

    Packaging Themes\uf0c1

    \n

    MkDocs makes use of Python packaging to distribute themes. This comes with a\nfew requirements.

    \n

    To see an example of a package containing one theme, see the MkDocs Bootstrap\ntheme and to see a package that contains many themes, see the MkDocs\nBootswatch theme.

    \n

    Package Layout\uf0c1

    \n

    The following layout is recommended for themes. Two files at the top level\ndirectory called MANIFEST.in amd setup.py. Then a directory with the name\nof your theme and containing a base.html file and a __init__.py.

    \n
    .\n|-- MANIFEST.in\n|-- theme_name\n|   |-- base.html\n|   |-- __init__.py\n`-- setup.py\n
    \n\n

    The MANIFEST.in file should contain the following contents but with\ntheme_name updated and any extra file extensions added to the include.

    \n
    recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff\nrecursive-exclude * __pycache__\nrecursive-exclude * *.py[co]\n
    \n\n

    The setup.py should include the following text with the modifications\ndescribed below.

    \n
    from setuptools import setup, find_packages\n\nVERSION = '0.0.1'\n\n\nsetup(\n    name="mkdocs-themename",\n    version=VERSION,\n    url='',\n    license='',\n    description='',\n    author='',\n    author_email='',\n    packages=find_packages(),\n    include_package_data=True,\n    entry_points={\n        'mkdocs.themes': [\n            'themename = theme_name',\n        ]\n    },\n    zip_safe=False\n)\n
    \n\n

    Fill in the URL, license, description, author and author email address.

    \n

    The name should follow the convention mkdocs-themename (like mkdocs-\nbootstrap and mkdocs-bootswatch), starting with MkDocs, using hyphens to\nseparate words and including the name of your theme.

    \n

    Most of the rest of the file can be left unedited. The last section we need to\nchange is the entry_points. This is how MkDocs finds the theme(s) you are\nincluding in the package. The name on the left is the one that users will use\nin their mkdocs.yml and the one on the right is the directory containing your\ntheme files.

    \n

    The directory you created at the start of this section with the base.html file\nshould contain all of the other theme files. The minimum requirement is that\nit includes a base.html for the theme. It must also include a\n__init__.py file which should be empty, this file tells Python that the\ndirectory is a package.

    \n

    Distributing Themes\uf0c1

    \n

    With the above changes, your theme should now be ready to install. This can be\ndone with pip, using pip install . if you are still in the same directory as\nthe setup.py.

    \n

    Most Python packages, including MkDocs, are distributed on PyPI. To do this,\nyou should run the following command.

    \n
    python setup.py register\n
    \n\n

    If you don't have an account setup, you should be prompted to create one.

    \n

    For a much more detailed guide, see the official Python packaging\ndocumentation for Packaging and Distributing Projects.

    ", + "url": "/user-guide/custom-themes/", + "language": "en", + "title": "Custom Themes" +} \ No newline at end of file diff --git a/user-guide/deploying-your-docs/index.json b/user-guide/deploying-your-docs/index.json new file mode 100644 index 00000000..52217c60 --- /dev/null +++ b/user-guide/deploying-your-docs/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    Deploying your docs\uf0c1

    \n

    A basic guide to deploying your docs to various hosting providers

    \n
    \n

    GitHub Pages\uf0c1

    \n

    If you host the source code for a project on GitHub, you can easily use\nGitHub Pages to host the documentation for your project. After you checkout\nthe primary working branch (usually master) of the git repository where you\nmaintain the source documentation for your project, run the following command:

    \n
    mkdocs gh-deploy --clean\n
    \n\n

    That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import\ntool to commit them to the gh-pages branch and push the gh-pages branch to\nGitHub.

    \n

    Use mkdocs gh-deploy --help to get a full list of options available for the\ngh-deploy command.

    \n

    Be aware that you will not be able to review the built site before it is pushed\nto GitHub. Therefore, you may want to verify any changes you make to the docs\nbeforehand by using the build or serve commands and reviewing the built\nfiles locally.

    \n
    \n

    Warning

    \n

    You should never edit files in your gh-pages branch by hand if you're using\nthe gh-deploy command because you will lose your work.

    \n
    \n

    Read the Docs\uf0c1

    \n

    Read the Docs offers free documentation hosting. You can import your docs\nusing any major version control system, including Mercurial, Git, Subversion,\nand Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the\ninstructions on their site to arrange the files in your repository properly,\ncreate an account and point it at your publicly hosted repository. If properly\nconfigured, your documentation will update each time you push commits to your\npublic repository.

    \n
    \n

    Note

    \n

    To benefit from all of the features offered by Read the Docs, you will need\nto use the Read the Docs theme which ships with MkDocs. The various\nthemes which may be referenced in Read the Docs' documentation are Sphinx\nspecific themes and will not work with MkDocs.

    \n
    \n

    PyPI\uf0c1

    \n

    If you maintain a Python project which is hosted on the Python Package\nIndex (PyPI), you can use the hosting provided at pythonhosted.org to\nhost documentation for your project. Run the following commands from your\nproject's root directory to upload your documentation:

    \n
    mkdocs build --clean\npython setup.py upload_docs --upload-dir=site\n
    \n\n

    You documentation will be hosted at http://pythonhosted.org/<projectname>/\nwhere <projectname> is the name you used to register your project with PyPI.

    \n

    There are a few prerequisites for the above to work:

    \n
      \n
    1. You must be using Setuptools in your setup.py script (Distutils does\n not offer an upload_docs command).
      2. \n
    2. Your project must already be registered with PyPI (use python setup.py\n register).
      3. \n
    3. Your mkdocs.yml config file and your \"docs\" directory (value assigned to\n the docs_dir configuration option) are presumed to be in the root directory\n of your project alongside your setup.py script.
      4. \n
    4. It is assumed that the default value (\"site\") is assigned to the site_dir\n configuration option in your mkdocs.yaml config file. If you have set a\n different value, assign that value to the --upload-dir option.
      5. \n
    \n

    Other Providers\uf0c1

    \n

    Any hosting provider which can serve static files can be used to serve\ndocumentation generated by MkDocs. While it would be impossible to document how\nto upload the docs to every hosting provider out there, the following guidelines\nshould provide some general assistance.

    \n

    When you build your site (using the mkdocs build command), all of the files\nare written to the directory assigned to the site_dir configuration option\n(defaults to \"site\") in your mkdocs.yaml config file. Generally, you will\nsimply need to copy the contents of that directory to the root directory of your\nhosting provider's server. Depending on your hosting provider's setup, you may\nneed to use a graphical or command line ftp, ssh or scp client to transfer\nthe files.

    \n

    For example, a typical set of commands from the command line might look\nsomething like this:

    \n
    mkdocs build --clean\nscp -r ./site usr@host:/path/to/server/root\n
    \n\n

    Of course, you will need to replace user with the username you have with your\nhosting provider and host with the appropriate domain name. Additionally, you\nwill need to adjust the /path/to/server/root to match the configuration of\nyour hosts' file system.

    \n

    See your host's documentation for specifics. You will likely want to search\ntheir documentation for \"ftp\" or \"uploading site\".

    ", + "url": "/user-guide/deploying-your-docs/", + "language": "en", + "title": "Deploying Your Docs" +} \ No newline at end of file diff --git a/user-guide/styling-your-docs/index.json b/user-guide/styling-your-docs/index.json new file mode 100644 index 00000000..9f80c046 --- /dev/null +++ b/user-guide/styling-your-docs/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    Styling your docs\uf0c1

    \n

    How to style and theme your documentation.

    \n
    \n

    MkDocs includes a number of different builtin themes and\nexternal themes which can easily be\ncustomised with extra CSS or JavaScript or you can\ncreate a custom theme for your documentation.

    \n

    To use a theme that is included in MkDocs, simply add this to your\nmkdocs.yml config file.

    \n
    theme: readthedocs\n
    \n

    Replace readthedocs with any of the builtin themes listed below.

    \n

    To create a new custom theme or more heavily customise an existing theme, see\nthe custom themes section below.

    \n

    Built-in themes\uf0c1

    \n

    mkdocs\uf0c1

    \n

    \"mkdocs\"

    \n

    readthedocs\uf0c1

    \n

    \"ReadTheDocs\"

    \n

    Bootstrap and Bootswatch Themes\uf0c1

    \n

    MkDocs also includes themes provided by two packages. MkDocs Bootstrap and\nMkDocs Bootswatch. The Bootstrap theme provides a theme based on Bootstrap\nand the Bootstrap theme provides 12 different themed Bootstrap themes based on\nthe Bootswatch project.

    \n
    \n

    Note

    \n

    The Bootstrap and Bootswatch themes will not be included by default from\nMkDocs version 1.0. They will need to be installed manually with pip\ninstall mkdocs-bootstrap or pip install mkdocs-bootswatch.

    \n
    \n

    Bootstrap\uf0c1

    \n

    \"Bootstrap\"

    \n

    Amelia\uf0c1

    \n

    \"Amelia\"

    \n

    Cerulean\uf0c1

    \n

    \"Cerulean\"

    \n

    Cosmo\uf0c1

    \n

    \"Cosmo\"

    \n

    Cyborg\uf0c1

    \n

    \"Cyborg\"

    \n

    Flatly\uf0c1

    \n

    \"Flatly\"

    \n

    Journal\uf0c1

    \n

    \"Journal\"

    \n

    Readable\uf0c1

    \n

    \"Readable\"

    \n

    Simplex\uf0c1

    \n

    \"Simplex\"

    \n

    Slate\uf0c1

    \n

    \"Slate\"

    \n

    Spacelab\uf0c1

    \n

    \"Spacelab\"

    \n

    United\uf0c1

    \n

    \"United\"

    \n

    Yeti\uf0c1

    \n

    \"Yeti\"

    \n

    Customising a Theme\uf0c1

    \n

    The extra_css and extra_javascript configuration options can be used to\nmake tweaks and customisations to existing themes. To use these, you simply\nneed to include either CSS or JavaScript files within your documentation\ndirectory.

    \n

    For example, to change the colour of the headers in your documentation, create\na file called extra.css and place it next to the documentation Markdown. In\nthat file add the following CSS.

    \n
    h1 {\n  color: red;\n}\n
    \n\n
    \n

    Note

    \n

    If you are deploying your documentation with ReadTheDocs. You will need\nto explicitly list the CSS and JavaScript files you want to include in\nyour config. To do this, add the following to your mkdocs.yml.

    \n
    extra_css: [extra.css]\n
    \n
    \n

    After making these changes, they should be visible when you run\nmkdocs serve - if you already had this running, you should see that the CSS\nchanges were automatically picked up and the documentation will be updated.

    ", + "url": "/user-guide/styling-your-docs/", + "language": "en", + "title": "Styling Your Docs" +} \ No newline at end of file diff --git a/user-guide/writing-your-docs/index.json b/user-guide/writing-your-docs/index.json new file mode 100644 index 00000000..42fe256c --- /dev/null +++ b/user-guide/writing-your-docs/index.json @@ -0,0 +1,6 @@ +{ + "content": "

    Writing your docs\uf0c1

    \n

    How to write and layout your markdown source files.

    \n
    \n

    Configure Pages and Navigation\uf0c1

    \n

    The pages configuration in your\nmkdocs.yml defines which pages are built by MkDocs and how they appear in the\ndocumentation navigation. If not provided, the pages configuration will be\nautomatically created by discovering all the Markdown files in the\ndocumentation directory.

    \n

    A simple pages configuration looks like this:

    \n
    pages:\n- 'index.md'\n- 'about.md'\n
    \n\n

    With this example we will build two pages at the top level and they will\nautomatically have their titles inferred from the filename. Assuming docs_dir\nhas the default value, docs, the source files for this documentation would be\ndocs/index.md and docs/about.md. To provide a custom name for these pages,\nthey can be added before the filename.

    \n
    pages:\n- Home: 'index.md'\n- About: 'about.md'\n
    \n\n

    Multilevel documentation\uf0c1

    \n

    Subsections can be created by listing related pages together under a section\ntitle. For example:

    \n
    pages:\n- Home: 'index.md'\n- User Guide:\n    - 'Writing your docs': 'user-guide/writing-your-docs.md'\n    - 'Styling your docs': 'user-guide/styling-your-docs.md'\n- About:\n    - 'License': 'about/license.md'\n    - 'Release Notes': 'about/release-notes.md'\n
    \n\n

    With the above configuration we have three top level sections: Home, User Guide\nand About. Then under User Guide we have two pages, Writing your docs and\nStyling your docs. Under the About section we also have two pages, License and\nRelease Notes.

    \n

    File layout\uf0c1

    \n

    Your documentation source should be written as regular Markdown files, and\nplaced in a directory somewhere in your project. Normally this directory will be\nnamed docs and will exist at the top level of your project, alongside the\nmkdocs.yml configuration file.

    \n

    The simplest project you can create will look something like this:

    \n
    mkdocs.yml\ndocs/\n    index.md\n
    \n\n

    By convention your project homepage should always be named index. Any of the\nfollowing extensions may be used for your Markdown source files: markdown,\nmdown, mkdn, mkd, md.

    \n

    You can also create multi-page documentation, by creating several markdown\nfiles:

    \n
    mkdocs.yml\ndocs/\n    index.md\n    about.md\n    license.md\n
    \n\n

    The file layout you use determines the URLs that are used for the generated\npages. Given the above layout, pages would be generated for the following URLs:

    \n
    /\n/about/\n/license/\n
    \n\n

    You can also include your Markdown files in nested directories if that better\nsuits your documentation layout.

    \n
    docs/\n    index.md\n    user-guide/getting-started.md\n    user-guide/configuration-options.md\n    license.md\n
    \n\n

    Source files inside nested directories will cause pages to be generated with\nnested URLs, like so:

    \n
    /\n/user-guide/getting-started/\n/user-guide/configuration-options/\n/license/\n
    \n\n

    Linking documents\uf0c1

    \n

    MkDocs allows you to interlink your documentation by using regular Markdown\nhyperlinks.

    \n

    Internal hyperlinks\uf0c1

    \n

    When linking between pages in the documentation you can simply use the regular\nMarkdown hyperlinking syntax, including the relative path to the Markdown\ndocument you wish to link to.

    \n
    Please see the [project license](license.md) for further details.\n
    \n

    When the MkDocs build runs, these hyperlinks will automatically be transformed\ninto a hyperlink to the appropriate HTML page.

    \n

    When working on your documentation you should be able to open the linked\nMarkdown document in a new editor window simply by clicking on the link.

    \n

    If the target documentation file is in another directory you'll need to make\nsure to include any relative directory path in the hyperlink.

    \n
    Please see the [project license](../about/license.md) for further details.\n
    \n

    You can also link to a section within a target documentation page by using an\nanchor link. The generated HTML will correctly transform the path portion of the\nhyperlink, and leave the anchor portion intact.

    \n
    Please see the [project license](about.md#license) for further details.\n
    \n

    Images and media\uf0c1

    \n

    As well as the Markdown source files, you can also include other file types in\nyour documentation, which will be copied across when generating your\ndocumentation site. These might include images and other media.

    \n

    For example, if your project documentation needed to include a GitHub pages\nCNAME\nfile\nand a PNG formatted screenshot image then your file layout might look as\nfollows:

    \n
    mkdocs.yml\ndocs/\n    CNAME\n    index.md\n    about.md\n    license.md\n    img/\n        screenshot.png\n
    \n\n

    To include images in your documentation source files, simply use any of the\nregular Markdown image syntaxes:

    \n
    Cupcake indexer is a snazzy new project for indexing small cakes.\n\n![Screenshot](img/screenshot.png)\n\n*Above: Cupcake indexer in progress*\n
    \n\n

    You image will now be embedded when you build the documentation, and should also\nbe previewed if you're working on the documentation with a Markdown editor.

    \n

    Markdown extensions\uf0c1

    \n

    MkDocs supports the following Markdown extensions.

    \n

    Tables\uf0c1

    \n

    A simple table looks like this:

    \n
    First Header | Second Header | Third Header\n------------ | ------------- | ------------\nContent Cell | Content Cell  | Content Cell\nContent Cell | Content Cell  | Content Cell\n
    \n\n

    If you wish, you can add a leading and tailing pipe to each line of the table:

    \n
    | First Header | Second Header | Third Header |\n| ------------ | ------------- | ------------ |\n| Content Cell | Content Cell  | Content Cell |\n| Content Cell | Content Cell  | Content Cell |\n
    \n\n

    Specify alignment for each column by adding colons to separator lines:

    \n
    First Header | Second Header | Third Header\n:----------- | :-----------: | -----------:\nLeft         | Center        | Right\nLeft         | Center        | Right\n
    \n\n

    Fenced code blocks\uf0c1

    \n

    The first line should contain 3 or more backtick (`) characters, and the\nlast line should contain the same number of backtick characters (`):

    \n
    ```\nFenced code blocks are like Stardard\nMarkdown\u2019s regular code blocks, except that\nthey\u2019re not indented and instead rely on\nstart and end fence lines to delimit the\ncode block.\n```\n
    \n\n

    With this approach, the language can optionally be specified on the first line\nafter the backticks:

    \n
    ```python\ndef fn():\n    pass\n```\n
    ", + "url": "/user-guide/writing-your-docs/", + "language": "en", + "title": "Writing Your Docs" +} \ No newline at end of file