diff --git a/about/release-notes/index.html b/about/release-notes/index.html index 0d2c8d20..dd48c0f6 100644 --- a/about/release-notes/index.html +++ b/about/release-notes/index.html @@ -134,6 +134,7 @@
  • Release Notes
  • Upgrading
  • Maintenance team
    • +
  • Version 0.16.1 (2016-12-22)
  • Version 0.16 (2016-11-04)
  • Version 0.15.3 (2016-02-18)
  • Version 0.15.2 (2016-02-08)
    • @@ -171,6 +172,11 @@ mkdocs, version 0.15.2
  • @d0ugal
  • @waylan
    • +

    Version 0.16.1 (2016-12-22)

    +

    Version 0.16 (2016-11-04)

    Major Additions to Version 0.16.0

    Template variables refactored. (#874)

    diff --git a/index.html b/index.html index 260cb9bf..71bc6330 100644 --- a/index.html +++ b/index.html @@ -172,10 +172,10 @@ the theme.

    Installation

    Install with a Package Manager

    If you have and use a package manager (such as apt-get, dnf, homebrew, -yum, 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.

    +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.

    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.

    @@ -373,7 +373,7 @@ able to host it from pretty much anywhere. Deploying your Docs page.

    +Deploying your Docs page.

    Getting help

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

    @@ -415,6 +415,6 @@ the MkDocs IRC channel #mkdocs on freenode.

    diff --git a/js/base.js b/js/base.js index c8888d53..b8eeb03a 100644 --- a/js/base.js +++ b/js/base.js @@ -31,7 +31,7 @@ $(document).ready(function() { $('table').addClass('table table-striped table-hover'); // Improve the scrollspy behaviour when users click on a TOC item. - $(".nav a").on("click", function() { + $(".bs-sidenav a").on("click", function() { var clicked = this; setTimeout(function() { var active = $('.nav li.active a'); diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json index 19e3e2cf..b1bc60a1 100644 --- a/mkdocs/search_index.json +++ b/mkdocs/search_index.json @@ -1,823 +1,828 @@ { "docs": [ { - "location": "/", - "text": "MkDocs\n\uf0c1\n\n\nProject documentation with\nMarkdown.\n\n\n\n\nOverview\n\uf0c1\n\n\nMkDocs is a \nfast\n, \nsimple\n and \ndownright gorgeous\n 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\n\nHost anywhere\n\uf0c1\n\n\nMkDocs builds completely static HTML sites that you can host on GitHub pages,\nAmazon S3, or \nanywhere\n else you choose.\n\n\nGreat themes available\n\uf0c1\n\n\nThere's a stack of good looking themes available for MkDocs. Choose between\nthe built in themes: \nmkdocs\n and \nreadthedocs\n, select one of the 3rd\nparty themes in the \nMkDocs wiki\n, or \nbuild your own\n.\n\n\nPreview your site as you work\n\uf0c1\n\n\nThe built-in dev-server allows you to preview your documentation as you're\nwriting it. It will even auto-reload and refresh your browser whenever you save\nyour changes.\n\n\nEasy to customize\n\uf0c1\n\n\nGet your project documentation looking just the way you want it by customizing\nthe theme.\n\n\n\n\nInstallation\n\uf0c1\n\n\nInstall with a Package Manager\n\uf0c1\n\n\nIf you have and use a package manager (such as \napt-get\n, \ndnf\n, \nhomebrew\n,\n\nyum\n, etc.) to install packages on your system, then you may want to search for\na \"MkDocs\" package and, if a recent version is available, install it with your\npackage manager (check your system's documentation for details). That's it,\nyou're done! Skip down to \nGetting Started\n.\n\n\nIf your package manager does not have a recent \"MkDocs\" package, you can still\nuse your package manager to install \"Python\" and \"pip\". Then you can use pip to\n\ninstall MkDocs\n.\n\n\nManual Installation\n\uf0c1\n\n\nIn order to manually install MkDocs you'll need \nPython\n installed on your\nsystem, as well as the Python package manager, \npip\n. You can check if you have\nthese already installed from the command line:\n\n\n$ python --version\nPython 2.7.2\n$ pip --version\npip 1.5.2\n\n\n\n\nMkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.\n\n\nInstalling Python\n\uf0c1\n\n\nInstall \nPython\n by downloading an installer appropriate for your system from\n\npython.org\n and running it.\n\n\n\n\nNote\n\n\nIf you are installing Python on Windows, be sure to check the box to have\nPython added to your PATH if the installer offers such an option (it's\nnormally off by default).\n\n\n\n\n\n\nInstalling pip\n\uf0c1\n\n\nIf you're using a recent version of Python, the Python package manager, \npip\n,\nis most likely installed by default. However, you may need to upgrade pip to the\nlasted version:\n\n\npip install --upgrade pip\n\n\n\n\nIf you need to install \npip\n for the first time, download \nget-pip.py\n.\nThen run the following command to install it:\n\n\npython get-pip.py\n\n\n\n\nInstalling MkDocs\n\uf0c1\n\n\nInstall the \nmkdocs\n package using pip:\n\n\npip install mkdocs\n\n\n\n\nYou should now have the \nmkdocs\n command installed on your system. Run \nmkdocs\n--version\n to check that everything worked okay.\n\n\n$ mkdocs --version\nmkdocs, version 0.15.3\n\n\n\n\n\n\nNote\n\n\nIf you are using Windows, some of the above commands may not work\nout-of-the-box.\n\n\nA quick solution may be to preface every Python command with \npython -m\n\nlike this:\n\n\npython -m pip install mkdocs\npython -m mkdocs\n\n\n\nFor a more permanent solution, you may need to edit your \nPATH\n environment\nvariable to include the \nScripts\n directory of your Python installation.\nRecent versions of Python include a script to do this for you. Navigate to\nyour Python installation directory (for example \nC:\\Python34\\\n), open the\n\nTools\n, then \nScripts\n folder, and run the \nwin_add2path.py\n file by double\nclicking on it. Alternatively, you can \ndownload\n the script and run it\n(\npython win_add2path.py\n).\n\n\n\n\n\n\nGetting Started\n\uf0c1\n\n\nGetting started is super easy.\n\n\nmkdocs new my-project\ncd my-project\n\n\n\n\nTake a moment to review the initial project that has been created for you.\n\n\n\n\nThere's a single configuration file named \nmkdocs.yml\n, and a folder named\n\ndocs\n that will contain your documentation source files. Right now the \ndocs\n\nfolder just contains a single documentation page, named \nindex.md\n.\n\n\nMkDocs comes with a built-in dev-server that lets you preview your documentation\nas you work on it. Make sure you're in the same directory as the \nmkdocs.yml\n\nconfiguration file, and then start the server by running the \nmkdocs serve\n\ncommand:\n\n\n$ mkdocs serve\nINFO - Building documentation...\nINFO - Cleaning site directory\n[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000\n[I 160402 15:50:43 handlers:58] Start watching changes\n[I 160402 15:50:43 handlers:60] Start detecting changes\n\n\n\n\nOpen up \nhttp://127.0.0.1:8000/\n in your browser, and you'll see the default\nhome page being displayed:\n\n\n\n\nThe dev-server also supports auto-reloading, and will rebuild your documentation\nwhenever anything in the configuration file, documentation directory, or theme\ndirectory changes.\n\n\nOpen the \ndocs/index.md\n document in your text editor of choice, change the\ninitial heading to \nMkLorum\n, and save your changes. Your browser will\nauto-reload and you should see your updated documentation immediately.\n\n\nNow try editing the configuration file: \nmkdocs.yml\n. Change the\n\nsite_name\n setting to \nMkLorum\n and save the file.\n\n\nsite_name: MkLorum\n\n\n\n\nYour browser should immediately reload, and you'll see your new site name take\neffect.\n\n\n\n\nAdding pages\n\uf0c1\n\n\nNow add a second page to your documentation:\n\n\ncurl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' \n docs/about.md\n\n\n\n\nAs our documentation site will include some navigation headers, you may want to\nedit the configuration file and add some information about the order, title, and\nnesting of each page in the navigation header by adding a \npages\n\nsetting:\n\n\nsite_name: MkLorum\npages:\n - Home: index.md\n - About: about.md\n\n\n\n\nSave your changes and you'll now see a navigation bar with \nHome\n and \nAbout\n\nitems on the left as well as \nSearch\n, \nPrevious\n, and \nNext\n items on the\nright.\n\n\n\n\nTry the menu items and navigate back and forth between pages. Then click on\n\nSearch\n. A search dialog will appear, allowing you to search for any text on\nany page. Notice that the search results include every occurrence of the search\nterm on the site and links directly to the section of the page in which the\nsearch term appears. You get of all that with no effort or configuration on your\npart!\n\n\n\n\nTheming our documentation\n\uf0c1\n\n\nNow change the configuration file to alter how the documentation is displayed by\nchanging the theme. Edit the \nmkdocs.yml\n file and add a \ntheme\n setting:\n\n\nsite_name: MkLorum\npages:\n - Home: index.md\n - About: about.md\ntheme: readthedocs\n\n\n\n\nSave your changes, and you'll see the ReadTheDocs theme being used.\n\n\n\n\nChanging the Favicon Icon\n\uf0c1\n\n\nBy default, MkDocs uses the \nMkDocs favicon\n icon. To use a different icon, create\nan \nimg\n subdirectory in your \ndocs_dir\n and copy your custom \nfavicon.ico\n file\nto that directory. MkDocs will automaticaly detect and use that file as your\nfavicon icon.\n\n\nBuilding the site\n\uf0c1\n\n\nThat's looking good. You're ready to deploy the first pass of your \nMkLorum\n\ndocumentation. First build the documentation:\n\n\nmkdocs build\n\n\n\n\nThis will create a new directory, named \nsite\n. Take a look inside the\ndirectory:\n\n\n$ ls site\nabout fonts index.html license search.html\ncss img js mkdocs sitemap.xml\n\n\n\n\nNotice that your source documentation has been output as two HTML files named\n\nindex.html\n and \nabout/index.html\n. You also have various other media that's\nbeen copied into the \nsite\n directory as part of the documentation theme. You\neven have a \nsitemap.xml\n file and \nmkdocs/search_index.json\n.\n\n\nIf you're using source code control such as \ngit\n you probably don't want to\ncheck your documentation builds into the repository. Add a line containing\n\nsite/\n to your \n.gitignore\n file.\n\n\necho \nsite/\n \n .gitignore\n\n\n\n\nIf you're using another source code control tool you'll want to check it's\ndocumentation on how to ignore specific directories.\n\n\nAfter some time, files may be removed from the documentation but they will still\nreside in the \nsite\n directory. To remove those stale files, just run \nmkdocs\n\nwith the \n--clean\n switch.\n\n\nmkdocs build --clean\n\n\n\n\nOther Commands and Options\n\uf0c1\n\n\nThere are various other commands and options available. For a complete list of\ncommands, use the \n--help\n flag:\n\n\nmkdocs --help\n\n\n\n\nTo view a list of options available on a given command, use the \n--help\n flag\nwith that command. For example, to get a list of all options available for the\n\nbuild\n command run the following:\n\n\nmkdocs build --help\n\n\n\n\nDeploying\n\uf0c1\n\n\nThe documentation site that you just built only uses static files so you'll be\nable to host it from pretty much anywhere. \nGitHub project pages\n and \nAmazon\nS3\n may be good hosting options, depending upon your needs. Upload the contents\nof the entire \nsite\n directory to wherever you're hosting your website from and\nyou're done. For specific instructions on a number of common hosts, see the\n\nDeploying your Docs\n page.\n\n\nGetting help\n\uf0c1\n\n\nTo get help with MkDocs, please use the \ndiscussion group\n, \nGitHub issues\n or\nthe MkDocs IRC channel \n#mkdocs\n on freenode.", + "location": "/", + "text": "MkDocs\n\uf0c1\n\n\nProject documentation with\u00a0Markdown.\n\n\n\n\nOverview\n\uf0c1\n\n\nMkDocs is a \nfast\n, \nsimple\n and \ndownright gorgeous\n 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\n\nHost anywhere\n\uf0c1\n\n\nMkDocs builds completely static HTML sites that you can host on GitHub pages,\nAmazon S3, or \nanywhere\n else you choose.\n\n\nGreat themes available\n\uf0c1\n\n\nThere's a stack of good looking themes available for MkDocs. Choose between\nthe built in themes: \nmkdocs\n and \nreadthedocs\n, select one of the 3rd\nparty themes in the \nMkDocs wiki\n, or \nbuild your own\n.\n\n\nPreview your site as you work\n\uf0c1\n\n\nThe built-in dev-server allows you to preview your documentation as you're\nwriting it. It will even auto-reload and refresh your browser whenever you save\nyour changes.\n\n\nEasy to customize\n\uf0c1\n\n\nGet your project documentation looking just the way you want it by customizing\nthe theme.\n\n\n\n\nInstallation\n\uf0c1\n\n\nInstall with a Package Manager\n\uf0c1\n\n\nIf you have and use a package manager (such as \napt-get\n, \ndnf\n, \nhomebrew\n,\n\nyum\n, \nchocolatey\n, etc.) to install packages on your system, then you may\nwant to search for a \"MkDocs\" package and, if a recent version is available,\ninstall it with your package manager (check your system's documentation for\ndetails). That's it, you're done! Skip down to \nGetting Started\n.\n\n\nIf your package manager does not have a recent \"MkDocs\" package, you can still\nuse your package manager to install \"Python\" and \"pip\". Then you can use pip to\n\ninstall MkDocs\n.\n\n\nManual Installation\n\uf0c1\n\n\nIn order to manually install MkDocs you'll need \nPython\n installed on your\nsystem, as well as the Python package manager, \npip\n. You can check if you have\nthese already installed from the command line:\n\n\n$ python --version\nPython 2.7.2\n$ pip --version\npip 1.5.2\n\n\n\n\nMkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.\n\n\nInstalling Python\n\uf0c1\n\n\nInstall \nPython\n by downloading an installer appropriate for your system from\n\npython.org\n and running it.\n\n\n\n\nNote\n\n\nIf you are installing Python on Windows, be sure to check the box to have\nPython added to your PATH if the installer offers such an option (it's\nnormally off by default).\n\n\n\n\n\n\nInstalling pip\n\uf0c1\n\n\nIf you're using a recent version of Python, the Python package manager, \npip\n,\nis most likely installed by default. However, you may need to upgrade pip to the\nlasted version:\n\n\npip install --upgrade pip\n\n\n\n\nIf you need to install \npip\n for the first time, download \nget-pip.py\n.\nThen run the following command to install it:\n\n\npython get-pip.py\n\n\n\n\nInstalling MkDocs\n\uf0c1\n\n\nInstall the \nmkdocs\n package using pip:\n\n\npip install mkdocs\n\n\n\n\nYou should now have the \nmkdocs\n command installed on your system. Run \nmkdocs\n--version\n to check that everything worked okay.\n\n\n$ mkdocs --version\nmkdocs, version 0.15.3\n\n\n\n\n\n\nNote\n\n\nIf you are using Windows, some of the above commands may not work\nout-of-the-box.\n\n\nA quick solution may be to preface every Python command with \npython -m\n\nlike this:\n\n\npython -m pip install mkdocs\npython -m mkdocs\n\n\n\nFor a more permanent solution, you may need to edit your \nPATH\n environment\nvariable to include the \nScripts\n directory of your Python installation.\nRecent versions of Python include a script to do this for you. Navigate to\nyour Python installation directory (for example \nC:\\Python34\\\n), open the\n\nTools\n, then \nScripts\n folder, and run the \nwin_add2path.py\n file by double\nclicking on it. Alternatively, you can \ndownload\n the script and run it\n(\npython win_add2path.py\n).\n\n\n\n\n\n\nGetting Started\n\uf0c1\n\n\nGetting started is super easy.\n\n\nmkdocs new my-project\ncd my-project\n\n\n\n\nTake a moment to review the initial project that has been created for you.\n\n\n\n\nThere's a single configuration file named \nmkdocs.yml\n, and a folder named\n\ndocs\n that will contain your documentation source files. Right now the \ndocs\n\nfolder just contains a single documentation page, named \nindex.md\n.\n\n\nMkDocs comes with a built-in dev-server that lets you preview your documentation\nas you work on it. Make sure you're in the same directory as the \nmkdocs.yml\n\nconfiguration file, and then start the server by running the \nmkdocs serve\n\ncommand:\n\n\n$ mkdocs serve\nINFO - Building documentation...\nINFO - Cleaning site directory\n[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000\n[I 160402 15:50:43 handlers:58] Start watching changes\n[I 160402 15:50:43 handlers:60] Start detecting changes\n\n\n\n\nOpen up \nhttp://127.0.0.1:8000/\n in your browser, and you'll see the default\nhome page being displayed:\n\n\n\n\nThe dev-server also supports auto-reloading, and will rebuild your documentation\nwhenever anything in the configuration file, documentation directory, or theme\ndirectory changes.\n\n\nOpen the \ndocs/index.md\n document in your text editor of choice, change the\ninitial heading to \nMkLorum\n, and save your changes. Your browser will\nauto-reload and you should see your updated documentation immediately.\n\n\nNow try editing the configuration file: \nmkdocs.yml\n. Change the\n\nsite_name\n setting to \nMkLorum\n and save the file.\n\n\nsite_name: MkLorum\n\n\n\n\nYour browser should immediately reload, and you'll see your new site name take\neffect.\n\n\n\n\nAdding pages\n\uf0c1\n\n\nNow add a second page to your documentation:\n\n\ncurl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md\n\n\n\n\nAs our documentation site will include some navigation headers, you may want to\nedit the configuration file and add some information about the order, title, and\nnesting of each page in the navigation header by adding a \npages\n\nsetting:\n\n\nsite_name: MkLorum\npages:\n - Home: index.md\n - About: about.md\n\n\n\n\nSave your changes and you'll now see a navigation bar with \nHome\n and \nAbout\n\nitems on the left as well as \nSearch\n, \nPrevious\n, and \nNext\n items on the\nright.\n\n\n\n\nTry the menu items and navigate back and forth between pages. Then click on\n\nSearch\n. A search dialog will appear, allowing you to search for any text on\nany page. Notice that the search results include every occurrence of the search\nterm on the site and links directly to the section of the page in which the\nsearch term appears. You get of all that with no effort or configuration on your\npart!\n\n\n\n\nTheming our documentation\n\uf0c1\n\n\nNow change the configuration file to alter how the documentation is displayed by\nchanging the theme. Edit the \nmkdocs.yml\n file and add a \ntheme\n setting:\n\n\nsite_name: MkLorum\npages:\n - Home: index.md\n - About: about.md\ntheme: readthedocs\n\n\n\n\nSave your changes, and you'll see the ReadTheDocs theme being used.\n\n\n\n\nChanging the Favicon Icon\n\uf0c1\n\n\nBy default, MkDocs uses the \nMkDocs favicon\n icon. To use a different icon, create\nan \nimg\n subdirectory in your \ndocs_dir\n and copy your custom \nfavicon.ico\n file\nto that directory. MkDocs will automaticaly detect and use that file as your\nfavicon icon.\n\n\nBuilding the site\n\uf0c1\n\n\nThat's looking good. You're ready to deploy the first pass of your \nMkLorum\n\ndocumentation. First build the documentation:\n\n\nmkdocs build\n\n\n\n\nThis will create a new directory, named \nsite\n. Take a look inside the\ndirectory:\n\n\n$ ls site\nabout fonts index.html license search.html\ncss img js mkdocs sitemap.xml\n\n\n\n\nNotice that your source documentation has been output as two HTML files named\n\nindex.html\n and \nabout/index.html\n. You also have various other media that's\nbeen copied into the \nsite\n directory as part of the documentation theme. You\neven have a \nsitemap.xml\n file and \nmkdocs/search_index.json\n.\n\n\nIf you're using source code control such as \ngit\n you probably don't want to\ncheck your documentation builds into the repository. Add a line containing\n\nsite/\n to your \n.gitignore\n file.\n\n\necho \"site/\" >> .gitignore\n\n\n\n\nIf you're using another source code control tool you'll want to check it's\ndocumentation on how to ignore specific directories.\n\n\nAfter some time, files may be removed from the documentation but they will still\nreside in the \nsite\n directory. To remove those stale files, just run \nmkdocs\n\nwith the \n--clean\n switch.\n\n\nmkdocs build --clean\n\n\n\n\nOther Commands and Options\n\uf0c1\n\n\nThere are various other commands and options available. For a complete list of\ncommands, use the \n--help\n flag:\n\n\nmkdocs --help\n\n\n\n\nTo view a list of options available on a given command, use the \n--help\n flag\nwith that command. For example, to get a list of all options available for the\n\nbuild\n command run the following:\n\n\nmkdocs build --help\n\n\n\n\nDeploying\n\uf0c1\n\n\nThe documentation site that you just built only uses static files so you'll be\nable to host it from pretty much anywhere. \nGitHub project pages\n and \nAmazon\nS3\n may be good hosting options, depending upon your needs. Upload the contents\nof the entire \nsite\n directory to wherever you're hosting your website from and\nyou're done. For specific instructions on a number of common hosts, see the\n\nDeploying your Docs\n page.\n\n\nGetting help\n\uf0c1\n\n\nTo get help with MkDocs, please use the \ndiscussion group\n, \nGitHub issues\n or\nthe MkDocs IRC channel \n#mkdocs\n on freenode.", "title": "Home" - }, + }, { - "location": "/#mkdocs", - "text": "Project documentation with Markdown.", + "location": "/#mkdocs", + "text": "Project documentation with\u00a0Markdown.", "title": "MkDocs" - }, + }, { - "location": "/#overview", - "text": "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.", + "location": "/#overview", + "text": "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.", "title": "Overview" - }, + }, { - "location": "/#host-anywhere", - "text": "MkDocs builds completely static HTML sites that you can host on GitHub pages,\nAmazon S3, or anywhere else you choose.", + "location": "/#host-anywhere", + "text": "MkDocs builds completely static HTML sites that you can host on GitHub pages,\nAmazon S3, or anywhere else you choose.", "title": "Host anywhere" - }, + }, { - "location": "/#great-themes-available", - "text": "There's a stack of good looking themes available for MkDocs. Choose between\nthe built in themes: mkdocs and readthedocs , select one of the 3rd\nparty themes in the MkDocs wiki , or build your own .", + "location": "/#great-themes-available", + "text": "There's a stack of good looking themes available for MkDocs. Choose between\nthe built in themes: mkdocs and readthedocs , select one of the 3rd\nparty themes in the MkDocs wiki , or build your own .", "title": "Great themes available" - }, + }, { - "location": "/#preview-your-site-as-you-work", - "text": "The built-in dev-server allows you to preview your documentation as you're\nwriting it. It will even auto-reload and refresh your browser whenever you save\nyour changes.", + "location": "/#preview-your-site-as-you-work", + "text": "The built-in dev-server allows you to preview your documentation as you're\nwriting it. It will even auto-reload and refresh your browser whenever you save\nyour changes.", "title": "Preview your site as you work" - }, + }, { - "location": "/#easy-to-customize", - "text": "Get your project documentation looking just the way you want it by customizing\nthe theme.", + "location": "/#easy-to-customize", + "text": "Get your project documentation looking just the way you want it by customizing\nthe theme.", "title": "Easy to customize" - }, + }, { - "location": "/#installation", - "text": "", + "location": "/#installation", + "text": "", "title": "Installation" - }, + }, { - "location": "/#install-with-a-package-manager", - "text": "If you have and use a package manager (such as apt-get , dnf , homebrew , yum , etc.) to install packages on your system, then you may want to search for\na \"MkDocs\" package and, if a recent version is available, install it with your\npackage manager (check your system's documentation for details). That's it,\nyou're done! Skip down to Getting Started . If your package manager does not have a recent \"MkDocs\" package, you can still\nuse your package manager to install \"Python\" and \"pip\". Then you can use pip to install MkDocs .", + "location": "/#install-with-a-package-manager", + "text": "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\nwant to search for a \"MkDocs\" package and, if a recent version is available,\ninstall it with your package manager (check your system's documentation for\ndetails). That's it, you're done! Skip down to Getting Started . If your package manager does not have a recent \"MkDocs\" package, you can still\nuse your package manager to install \"Python\" and \"pip\". Then you can use pip to install MkDocs .", "title": "Install with a Package Manager" - }, + }, { - "location": "/#manual-installation", - "text": "In order to manually install MkDocs you'll need Python installed on your\nsystem, as well as the Python package manager, pip . You can check if you have\nthese already installed from the command line: $ python --version\nPython 2.7.2\n$ pip --version\npip 1.5.2 MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.", + "location": "/#manual-installation", + "text": "In order to manually install MkDocs you'll need Python installed on your\nsystem, as well as the Python package manager, pip . You can check if you have\nthese already installed from the command line: $ python --version\nPython 2.7.2\n$ pip --version\npip 1.5.2 MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.", "title": "Manual Installation" - }, + }, { - "location": "/#installing-python", - "text": "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\nPython added to your PATH if the installer offers such an option (it's\nnormally off by default).", + "location": "/#installing-python", + "text": "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\nPython added to your PATH if the installer offers such an option (it's\nnormally off by default).", "title": "Installing Python" - }, + }, { - "location": "/#installing-pip", - "text": "If you're using a recent version of Python, the Python package manager, pip ,\nis most likely installed by default. However, you may need to upgrade pip to the\nlasted version: pip install --upgrade pip If you need to install pip for the first time, download get-pip.py .\nThen run the following command to install it: python get-pip.py", + "location": "/#installing-pip", + "text": "If you're using a recent version of Python, the Python package manager, pip ,\nis most likely installed by default. However, you may need to upgrade pip to the\nlasted version: pip install --upgrade pip If you need to install pip for the first time, download get-pip.py .\nThen run the following command to install it: python get-pip.py", "title": "Installing pip" - }, + }, { - "location": "/#installing-mkdocs", - "text": "Install the mkdocs package using pip: pip install mkdocs You should now have the mkdocs command installed on your system. Run mkdocs\n--version to check that everything worked okay. $ mkdocs --version\nmkdocs, version 0.15.3 Note If you are using Windows, some of the above commands may not work\nout-of-the-box. A quick solution may be to preface every Python command with python -m \nlike this: python -m pip install mkdocs\npython -m mkdocs For a more permanent solution, you may need to edit your PATH environment\nvariable to include the Scripts directory of your Python installation.\nRecent versions of Python include a script to do this for you. Navigate to\nyour Python installation directory (for example C:\\Python34\\ ), open the Tools , then Scripts folder, and run the win_add2path.py file by double\nclicking on it. Alternatively, you can download the script and run it\n( python win_add2path.py ).", + "location": "/#installing-mkdocs", + "text": "Install the mkdocs package using pip: pip install mkdocs You should now have the mkdocs command installed on your system. Run mkdocs\n--version to check that everything worked okay. $ mkdocs --version\nmkdocs, version 0.15.3 Note If you are using Windows, some of the above commands may not work\nout-of-the-box. A quick solution may be to preface every Python command with python -m \nlike this: python -m pip install mkdocs\npython -m mkdocs For a more permanent solution, you may need to edit your PATH environment\nvariable to include the Scripts directory of your Python installation.\nRecent versions of Python include a script to do this for you. Navigate to\nyour Python installation directory (for example C:\\Python34\\ ), open the Tools , then Scripts folder, and run the win_add2path.py file by double\nclicking on it. Alternatively, you can download the script and run it\n( python win_add2path.py ).", "title": "Installing MkDocs" - }, + }, { - "location": "/#getting-started", - "text": "Getting started is super easy. mkdocs new my-project\ncd my-project Take a moment to review the initial project that has been created for you. 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 \nfolder just contains a single documentation page, named index.md . MkDocs comes with a built-in dev-server that lets you preview your documentation\nas you work on it. Make sure you're in the same directory as the mkdocs.yml \nconfiguration file, and then start the server by running the mkdocs serve \ncommand: $ mkdocs serve\nINFO - Building documentation...\nINFO - Cleaning site directory\n[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000\n[I 160402 15:50:43 handlers:58] Start watching changes\n[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\nhome page being displayed: The dev-server also supports auto-reloading, and will rebuild your documentation\nwhenever anything in the configuration file, documentation directory, or theme\ndirectory changes. Open the docs/index.md document in your text editor of choice, change the\ninitial heading to MkLorum , and save your changes. Your browser will\nauto-reload and you should see your updated documentation immediately. Now try editing the configuration file: mkdocs.yml . Change the site_name setting to MkLorum and save the file. site_name: MkLorum Your browser should immediately reload, and you'll see your new site name take\neffect.", + "location": "/#getting-started", + "text": "Getting started is super easy. mkdocs new my-project\ncd my-project Take a moment to review the initial project that has been created for you. 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 \nfolder just contains a single documentation page, named index.md . MkDocs comes with a built-in dev-server that lets you preview your documentation\nas you work on it. Make sure you're in the same directory as the mkdocs.yml \nconfiguration file, and then start the server by running the mkdocs serve \ncommand: $ mkdocs serve\nINFO - Building documentation...\nINFO - Cleaning site directory\n[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000\n[I 160402 15:50:43 handlers:58] Start watching changes\n[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\nhome page being displayed: The dev-server also supports auto-reloading, and will rebuild your documentation\nwhenever anything in the configuration file, documentation directory, or theme\ndirectory changes. Open the docs/index.md document in your text editor of choice, change the\ninitial heading to MkLorum , and save your changes. Your browser will\nauto-reload and you should see your updated documentation immediately. Now try editing the configuration file: mkdocs.yml . Change the site_name setting to MkLorum and save the file. site_name: MkLorum Your browser should immediately reload, and you'll see your new site name take\neffect.", "title": "Getting Started" - }, + }, { - "location": "/#adding-pages", - "text": "Now add a second page to your documentation: curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' docs/about.md As our documentation site will include some navigation headers, you may want to\nedit the configuration file and add some information about the order, title, and\nnesting of each page in the navigation header by adding a pages \nsetting: site_name: MkLorum\npages:\n - Home: index.md\n - About: about.md Save your changes and you'll now see a navigation bar with Home and About \nitems on the left as well as Search , Previous , and Next items on the\nright. 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\nany page. Notice that the search results include every occurrence of the search\nterm on the site and links directly to the section of the page in which the\nsearch term appears. You get of all that with no effort or configuration on your\npart!", + "location": "/#adding-pages", + "text": "Now add a second page to your documentation: curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md As our documentation site will include some navigation headers, you may want to\nedit the configuration file and add some information about the order, title, and\nnesting of each page in the navigation header by adding a pages \nsetting: site_name: MkLorum\npages:\n - Home: index.md\n - About: about.md Save your changes and you'll now see a navigation bar with Home and About \nitems on the left as well as Search , Previous , and Next items on the\nright. 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\nany page. Notice that the search results include every occurrence of the search\nterm on the site and links directly to the section of the page in which the\nsearch term appears. You get of all that with no effort or configuration on your\npart!", "title": "Adding pages" - }, + }, { - "location": "/#theming-our-documentation", - "text": "Now change the configuration file to alter how the documentation is displayed by\nchanging the theme. Edit the mkdocs.yml file and add a theme setting: site_name: MkLorum\npages:\n - Home: index.md\n - About: about.md\ntheme: readthedocs Save your changes, and you'll see the ReadTheDocs theme being used.", + "location": "/#theming-our-documentation", + "text": "Now change the configuration file to alter how the documentation is displayed by\nchanging the theme. Edit the mkdocs.yml file and add a theme setting: site_name: MkLorum\npages:\n - Home: index.md\n - About: about.md\ntheme: readthedocs Save your changes, and you'll see the ReadTheDocs theme being used.", "title": "Theming our documentation" - }, + }, { - "location": "/#changing-the-favicon-icon", - "text": "By default, MkDocs uses the MkDocs favicon icon. To use a different icon, create\nan img subdirectory in your docs_dir and copy your custom favicon.ico file\nto that directory. MkDocs will automaticaly detect and use that file as your\nfavicon icon.", + "location": "/#changing-the-favicon-icon", + "text": "By default, MkDocs uses the MkDocs favicon icon. To use a different icon, create\nan img subdirectory in your docs_dir and copy your custom favicon.ico file\nto that directory. MkDocs will automaticaly detect and use that file as your\nfavicon icon.", "title": "Changing the Favicon Icon" - }, + }, { - "location": "/#building-the-site", - "text": "That's looking good. You're ready to deploy the first pass of your MkLorum \ndocumentation. First build the documentation: mkdocs build This will create a new directory, named site . Take a look inside the\ndirectory: $ ls site\nabout fonts index.html license search.html\ncss 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\nbeen copied into the site directory as part of the documentation theme. You\neven 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\ncheck your documentation builds into the repository. Add a line containing site/ to your .gitignore file. echo site/ .gitignore If you're using another source code control tool you'll want to check it's\ndocumentation on how to ignore specific directories. 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. mkdocs build --clean", + "location": "/#building-the-site", + "text": "That's looking good. You're ready to deploy the first pass of your MkLorum \ndocumentation. First build the documentation: mkdocs build This will create a new directory, named site . Take a look inside the\ndirectory: $ ls site\nabout fonts index.html license search.html\ncss 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\nbeen copied into the site directory as part of the documentation theme. You\neven 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\ncheck your documentation builds into the repository. Add a line containing site/ to your .gitignore file. echo \"site/\" >> .gitignore If you're using another source code control tool you'll want to check it's\ndocumentation on how to ignore specific directories. 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. mkdocs build --clean", "title": "Building the site" - }, + }, { - "location": "/#other-commands-and-options", - "text": "There are various other commands and options available. For a complete list of\ncommands, use the --help flag: mkdocs --help 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 build command run the following: mkdocs build --help", + "location": "/#other-commands-and-options", + "text": "There are various other commands and options available. For a complete list of\ncommands, use the --help flag: mkdocs --help 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 build command run the following: mkdocs build --help", "title": "Other Commands and Options" - }, + }, { - "location": "/#deploying", - "text": "The documentation site that you just built only uses static files so you'll be\nable to host it from pretty much anywhere. GitHub project pages and Amazon\nS3 may be good hosting options, depending upon your needs. Upload the contents\nof the entire site directory to wherever you're hosting your website from and\nyou're done. For specific instructions on a number of common hosts, see the Deploying your Docs page.", + "location": "/#deploying", + "text": "The documentation site that you just built only uses static files so you'll be\nable to host it from pretty much anywhere. GitHub project pages and Amazon\nS3 may be good hosting options, depending upon your needs. Upload the contents\nof the entire site directory to wherever you're hosting your website from and\nyou're done. For specific instructions on a number of common hosts, see the Deploying your Docs page.", "title": "Deploying" - }, + }, { - "location": "/#getting-help", - "text": "To get help with MkDocs, please use the discussion group , GitHub issues or\nthe MkDocs IRC channel #mkdocs on freenode.", + "location": "/#getting-help", + "text": "To get help with MkDocs, please use the discussion group , GitHub issues or\nthe MkDocs IRC channel #mkdocs on freenode.", "title": "Getting help" - }, + }, { - "location": "/user-guide/writing-your-docs/", - "text": "Writing your docs\n\uf0c1\n\n\nHow to write and layout your markdown source files.\n\n\n\n\nConfigure Pages and Navigation\n\uf0c1\n\n\nThe \npages configuration\n in your\n\nmkdocs.yml\n 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\n\ndocumentation directory\n. An\nautomatically created pages configuration will always be sorted\nalphanumerically by file name. You will need to manually define your pages\nconfiguration if you would like your pages sorted differantly.\n\n\nA simple pages configuration looks like this:\n\n\npages:\n- 'index.md'\n- 'about.md'\n\n\n\n\nWith this example we will build two pages at the top level and they will\nautomatically have their titles inferred from the filename. Assuming \ndocs_dir\n\nhas the default value, \ndocs\n, the source files for this documentation would be\n\ndocs/index.md\n and \ndocs/about.md\n. To provide a custom name for these pages,\nthey can be added before the filename.\n\n\npages:\n- Home: 'index.md'\n- About: 'about.md'\n\n\n\n\nMultilevel documentation\n\uf0c1\n\n\nSubsections can be created by listing related pages together under a section\ntitle. For example:\n\n\npages:\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\n\nWith 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\n\nFile layout\n\uf0c1\n\n\nYour documentation source should be written as regular Markdown files, and\nplaced in a directory somewhere in your project. Normally this directory will be\nnamed \ndocs\n and will exist at the top level of your project, alongside the\n\nmkdocs.yml\n configuration file.\n\n\nThe simplest project you can create will look something like this:\n\n\nmkdocs.yml\ndocs/\n index.md\n\n\n\n\nBy convention your project homepage should always be named \nindex\n. Any of the\nfollowing extensions may be used for your Markdown source files: \nmarkdown\n,\n\nmdown\n, \nmkdn\n, \nmkd\n, \nmd\n.\n\n\nYou can also create multi-page documentation, by creating several markdown\nfiles:\n\n\nmkdocs.yml\ndocs/\n index.md\n about.md\n license.md\n\n\n\n\nThe 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\n/\n/about/\n/license/\n\n\n\n\nYou can also include your Markdown files in nested directories if that better\nsuits your documentation layout.\n\n\ndocs/\n index.md\n user-guide/getting-started.md\n user-guide/configuration-options.md\n license.md\n\n\n\n\nSource files inside nested directories will cause pages to be generated with\nnested URLs, like so:\n\n\n/\n/user-guide/getting-started/\n/user-guide/configuration-options/\n/license/\n\n\n\n\nLinking documents\n\uf0c1\n\n\nMkDocs allows you to interlink your documentation by using regular Markdown\nhyperlinks.\n\n\nInternal hyperlinks\n\uf0c1\n\n\nWhen 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\n\nPlease see the [project license](license.md) for further details.\n\n\n\nWhen the MkDocs build runs, these hyperlinks will automatically be transformed\ninto a hyperlink to the appropriate HTML page.\n\n\nWhen 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\n\nIf the target documentation file is in another directory you'll need to make\nsure to include any relative directory path in the hyperlink.\n\n\nPlease see the [project license](../about/license.md) for further details.\n\n\n\nYou 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\n\nPlease see the [project license](about.md#license) for further details.\n\n\n\nImages and media\n\uf0c1\n\n\nAs 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\n\nFor example, if your project documentation needed to include a \nGitHub pages\nCNAME\nfile\n\nand a PNG formatted screenshot image then your file layout might look as\nfollows:\n\n\nmkdocs.yml\ndocs/\n CNAME\n index.md\n about.md\n license.md\n img/\n screenshot.png\n\n\n\n\nTo include images in your documentation source files, simply use any of the\nregular Markdown image syntaxes:\n\n\nCupcake 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\n\nYou 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\n\nMarkdown extensions\n\uf0c1\n\n\nMkDocs supports the following Markdown extensions.\n\n\nTables\n\uf0c1\n\n\nA simple table looks like this:\n\n\nFirst Header | Second Header | Third Header\n------------ | ------------- | ------------\nContent Cell | Content Cell | Content Cell\nContent Cell | Content Cell | Content Cell\n\n\n\n\nIf you wish, you can add a leading and tailing pipe to each line of the table:\n\n\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\n\nSpecify alignment for each column by adding colons to separator lines:\n\n\nFirst Header | Second Header | Third Header\n:----------- |:-------------:| -----------:\nLeft | Center | Right\nLeft | Center | Right\n\n\n\n\nFenced code blocks\n\uf0c1\n\n\nThe first line should contain 3 or more backtick (\n`\n) characters, and the\nlast line should contain the same number of backtick characters (\n`\n):\n\n\n```\nFenced code blocks are like Standard\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\n\nWith this approach, the language can optionally be specified on the first line\nafter the backticks:\n\n\n```python\ndef fn():\n pass\n```", + "location": "/user-guide/writing-your-docs/", + "text": "Writing your docs\n\uf0c1\n\n\nHow to write and layout your markdown source files.\n\n\n\n\nConfigure Pages and Navigation\n\uf0c1\n\n\nThe \npages configuration\n in your\n\nmkdocs.yml\n 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\n\ndocumentation directory\n. An\nautomatically created pages configuration will always be sorted\nalphanumerically by file name. You will need to manually define your pages\nconfiguration if you would like your pages sorted differantly.\n\n\nA simple pages configuration looks like this:\n\n\npages:\n- 'index.md'\n- 'about.md'\n\n\n\n\nWith this example we will build two pages at the top level and they will\nautomatically have their titles inferred from the filename. Assuming \ndocs_dir\n\nhas the default value, \ndocs\n, the source files for this documentation would be\n\ndocs/index.md\n and \ndocs/about.md\n. To provide a custom name for these pages,\nthey can be added before the filename.\n\n\npages:\n- Home: 'index.md'\n- About: 'about.md'\n\n\n\n\nMultilevel documentation\n\uf0c1\n\n\nSubsections can be created by listing related pages together under a section\ntitle. For example:\n\n\npages:\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\n\nWith 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\n\nFile layout\n\uf0c1\n\n\nYour documentation source should be written as regular Markdown files, and\nplaced in a directory somewhere in your project. Normally this directory will be\nnamed \ndocs\n and will exist at the top level of your project, alongside the\n\nmkdocs.yml\n configuration file.\n\n\nThe simplest project you can create will look something like this:\n\n\nmkdocs.yml\ndocs/\n index.md\n\n\n\n\nBy convention your project homepage should always be named \nindex\n. Any of the\nfollowing extensions may be used for your Markdown source files: \nmarkdown\n,\n\nmdown\n, \nmkdn\n, \nmkd\n, \nmd\n.\n\n\nYou can also create multi-page documentation, by creating several markdown\nfiles:\n\n\nmkdocs.yml\ndocs/\n index.md\n about.md\n license.md\n\n\n\n\nThe 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\n/\n/about/\n/license/\n\n\n\n\nYou can also include your Markdown files in nested directories if that better\nsuits your documentation layout.\n\n\ndocs/\n index.md\n user-guide/getting-started.md\n user-guide/configuration-options.md\n license.md\n\n\n\n\nSource files inside nested directories will cause pages to be generated with\nnested URLs, like so:\n\n\n/\n/user-guide/getting-started/\n/user-guide/configuration-options/\n/license/\n\n\n\n\nLinking documents\n\uf0c1\n\n\nMkDocs allows you to interlink your documentation by using regular Markdown\nhyperlinks.\n\n\nInternal hyperlinks\n\uf0c1\n\n\nWhen 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\n\nPlease see the [project license](license.md) for further details.\n\n\n\nWhen the MkDocs build runs, these hyperlinks will automatically be transformed\ninto a hyperlink to the appropriate HTML page.\n\n\nWhen 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\n\nIf the target documentation file is in another directory you'll need to make\nsure to include any relative directory path in the hyperlink.\n\n\nPlease see the [project license](../about/license.md) for further details.\n\n\n\nYou 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\n\nPlease see the [project license](about.md#license) for further details.\n\n\n\nImages and media\n\uf0c1\n\n\nAs 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\n\nFor example, if your project documentation needed to include a \nGitHub pages\nCNAME\nfile\n\nand a PNG formatted screenshot image then your file layout might look as\nfollows:\n\n\nmkdocs.yml\ndocs/\n CNAME\n index.md\n about.md\n license.md\n img/\n screenshot.png\n\n\n\n\nTo include images in your documentation source files, simply use any of the\nregular Markdown image syntaxes:\n\n\nCupcake 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\n\nYou 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\n\nMarkdown extensions\n\uf0c1\n\n\nMkDocs supports the following Markdown extensions.\n\n\nTables\n\uf0c1\n\n\nA simple table looks like this:\n\n\nFirst Header | Second Header | Third Header\n------------ | ------------- | ------------\nContent Cell | Content Cell | Content Cell\nContent Cell | Content Cell | Content Cell\n\n\n\n\nIf you wish, you can add a leading and tailing pipe to each line of the table:\n\n\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\n\nSpecify alignment for each column by adding colons to separator lines:\n\n\nFirst Header | Second Header | Third Header\n:----------- |:-------------:| -----------:\nLeft | Center | Right\nLeft | Center | Right\n\n\n\n\nFenced code blocks\n\uf0c1\n\n\nThe first line should contain 3 or more backtick (\n`\n) characters, and the\nlast line should contain the same number of backtick characters (\n`\n):\n\n\n```\nFenced code blocks are like Standard\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\n\nWith this approach, the language can optionally be specified on the first line\nafter the backticks:\n\n\n```python\ndef fn():\n pass\n```", "title": "Writing Your Docs" - }, + }, { - "location": "/user-guide/writing-your-docs/#writing-your-docs", - "text": "How to write and layout your markdown source files.", + "location": "/user-guide/writing-your-docs/#writing-your-docs", + "text": "How to write and layout your markdown source files.", "title": "Writing your docs" - }, + }, { - "location": "/user-guide/writing-your-docs/#configure-pages-and-navigation", - "text": "The pages configuration in your mkdocs.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 documentation directory . An\nautomatically created pages configuration will always be sorted\nalphanumerically by file name. You will need to manually define your pages\nconfiguration if you would like your pages sorted differantly. A simple pages configuration looks like this: pages:\n- 'index.md'\n- 'about.md' 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 docs/index.md and docs/about.md . To provide a custom name for these pages,\nthey can be added before the filename. pages:\n- Home: 'index.md'\n- About: 'about.md'", + "location": "/user-guide/writing-your-docs/#configure-pages-and-navigation", + "text": "The pages configuration in your mkdocs.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 documentation directory . An\nautomatically created pages configuration will always be sorted\nalphanumerically by file name. You will need to manually define your pages\nconfiguration if you would like your pages sorted differantly. A simple pages configuration looks like this: pages:\n- 'index.md'\n- 'about.md' 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 docs/index.md and docs/about.md . To provide a custom name for these pages,\nthey can be added before the filename. pages:\n- Home: 'index.md'\n- About: 'about.md'", "title": "Configure Pages and Navigation" - }, + }, { - "location": "/user-guide/writing-your-docs/#multilevel-documentation", - "text": "Subsections can be created by listing related pages together under a section\ntitle. For example: 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' 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.", + "location": "/user-guide/writing-your-docs/#multilevel-documentation", + "text": "Subsections can be created by listing related pages together under a section\ntitle. For example: 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' 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.", "title": "Multilevel documentation" - }, + }, { - "location": "/user-guide/writing-your-docs/#file-layout", - "text": "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 mkdocs.yml configuration file. The simplest project you can create will look something like this: mkdocs.yml\ndocs/\n index.md By convention your project homepage should always be named index . Any of the\nfollowing 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\nfiles: mkdocs.yml\ndocs/\n index.md\n about.md\n license.md 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/about/\n/license/ You can also include your Markdown files in nested directories if that better\nsuits your documentation layout. docs/\n index.md\n user-guide/getting-started.md\n user-guide/configuration-options.md\n license.md Source files inside nested directories will cause pages to be generated with\nnested URLs, like so: /\n/user-guide/getting-started/\n/user-guide/configuration-options/\n/license/", + "location": "/user-guide/writing-your-docs/#file-layout", + "text": "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 mkdocs.yml configuration file. The simplest project you can create will look something like this: mkdocs.yml\ndocs/\n index.md By convention your project homepage should always be named index . Any of the\nfollowing 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\nfiles: mkdocs.yml\ndocs/\n index.md\n about.md\n license.md 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/about/\n/license/ You can also include your Markdown files in nested directories if that better\nsuits your documentation layout. docs/\n index.md\n user-guide/getting-started.md\n user-guide/configuration-options.md\n license.md Source files inside nested directories will cause pages to be generated with\nnested URLs, like so: /\n/user-guide/getting-started/\n/user-guide/configuration-options/\n/license/", "title": "File layout" - }, + }, { - "location": "/user-guide/writing-your-docs/#linking-documents", - "text": "MkDocs allows you to interlink your documentation by using regular Markdown\nhyperlinks.", + "location": "/user-guide/writing-your-docs/#linking-documents", + "text": "MkDocs allows you to interlink your documentation by using regular Markdown\nhyperlinks.", "title": "Linking documents" - }, + }, { - "location": "/user-guide/writing-your-docs/#internal-hyperlinks", - "text": "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. Please see the [project license](license.md) for further details. When the MkDocs build runs, these hyperlinks will automatically be transformed\ninto a hyperlink to the appropriate HTML page. 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. If the target documentation file is in another directory you'll need to make\nsure 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\nanchor link. The generated HTML will correctly transform the path portion of the\nhyperlink, and leave the anchor portion intact. Please see the [project license](about.md#license) for further details.", + "location": "/user-guide/writing-your-docs/#internal-hyperlinks", + "text": "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. Please see the [project license](license.md) for further details. When the MkDocs build runs, these hyperlinks will automatically be transformed\ninto a hyperlink to the appropriate HTML page. 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. If the target documentation file is in another directory you'll need to make\nsure 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\nanchor link. The generated HTML will correctly transform the path portion of the\nhyperlink, and leave the anchor portion intact. Please see the [project license](about.md#license) for further details.", "title": "Internal hyperlinks" - }, + }, { - "location": "/user-guide/writing-your-docs/#images-and-media", - "text": "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. 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: mkdocs.yml\ndocs/\n CNAME\n index.md\n about.md\n license.md\n img/\n screenshot.png To include images in your documentation source files, simply use any of the\nregular Markdown image syntaxes: Cupcake indexer is a snazzy new project for indexing small cakes.\n\n![Screenshot](img/screenshot.png)\n\n*Above: Cupcake indexer in progress* 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.", + "location": "/user-guide/writing-your-docs/#images-and-media", + "text": "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. 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: mkdocs.yml\ndocs/\n CNAME\n index.md\n about.md\n license.md\n img/\n screenshot.png To include images in your documentation source files, simply use any of the\nregular Markdown image syntaxes: Cupcake indexer is a snazzy new project for indexing small cakes.\n\n![Screenshot](img/screenshot.png)\n\n*Above: Cupcake indexer in progress* 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.", "title": "Images and media" - }, + }, { - "location": "/user-guide/writing-your-docs/#markdown-extensions", - "text": "MkDocs supports the following Markdown extensions.", + "location": "/user-guide/writing-your-docs/#markdown-extensions", + "text": "MkDocs supports the following Markdown extensions.", "title": "Markdown extensions" - }, + }, { - "location": "/user-guide/writing-your-docs/#tables", - "text": "A simple table looks like this: First Header | Second Header | Third Header\n------------ | ------------- | ------------\nContent Cell | Content Cell | Content Cell\nContent Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: | First Header | Second Header | Third Header |\n| ------------ | ------------- | ------------ |\n| Content Cell | Content Cell | Content Cell |\n| Content Cell | Content Cell | Content Cell | Specify alignment for each column by adding colons to separator lines: First Header | Second Header | Third Header\n:----------- |:-------------:| -----------:\nLeft | Center | Right\nLeft | Center | Right", + "location": "/user-guide/writing-your-docs/#tables", + "text": "A simple table looks like this: First Header | Second Header | Third Header\n------------ | ------------- | ------------\nContent Cell | Content Cell | Content Cell\nContent Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: | First Header | Second Header | Third Header |\n| ------------ | ------------- | ------------ |\n| Content Cell | Content Cell | Content Cell |\n| Content Cell | Content Cell | Content Cell | Specify alignment for each column by adding colons to separator lines: First Header | Second Header | Third Header\n:----------- |:-------------:| -----------:\nLeft | Center | Right\nLeft | Center | Right", "title": "Tables" - }, + }, { - "location": "/user-guide/writing-your-docs/#fenced-code-blocks", - "text": "The first line should contain 3 or more backtick ( ` ) characters, and the\nlast line should contain the same number of backtick characters ( ` ): ```\nFenced code blocks are like Standard\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``` With this approach, the language can optionally be specified on the first line\nafter the backticks: ```python\ndef fn():\n pass\n```", + "location": "/user-guide/writing-your-docs/#fenced-code-blocks", + "text": "The first line should contain 3 or more backtick ( ` ) characters, and the\nlast line should contain the same number of backtick characters ( ` ): ```\nFenced code blocks are like Standard\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``` With this approach, the language can optionally be specified on the first line\nafter the backticks: ```python\ndef fn():\n pass\n```", "title": "Fenced code blocks" - }, + }, { - "location": "/user-guide/styling-your-docs/", - "text": "Styling your docs\n\uf0c1\n\n\nHow to style and theme your documentation.\n\n\n\n\nMkDocs includes a couple \nbuilt-in themes\n as well as various \nthird party\nthemes\n, all of which can easily be customized with \nextra CSS or\nJavaScript\n or overridden from the \ntheme directory\n. You\ncan also create your own \ncustom theme\n from the grown up for your\ndocumentation.\n\n\nTo use a theme that is included in MkDocs, simply add this to your\n\nmkdocs.yml\n config file.\n\n\ntheme: readthedocs\n\n\n\nReplace \nreadthedocs\n with any of the \nbuilt-in themes\n listed below.\n\n\nTo create a new custom theme see the \nCustom Themes\n page, or to\nmore heavily customize an existing theme, see\nthe \nCustomizing a Theme\n section below.\n\n\nBuilt-in themes\n\uf0c1\n\n\nmkdocs\n\uf0c1\n\n\n\n\nreadthedocs\n\uf0c1\n\n\n\n\nThird Party Themes\n\uf0c1\n\n\nA list of third party themes can be found in the MkDocs \ncommunity wiki\n. If you\nhave created your own, please feel free to add it to the list.\n\n\nCustomizing a Theme\n\uf0c1\n\n\nIf you would like to make a few tweaks to an existing theme, there is no need to\ncreate your own theme from scratch. For minor tweaks which only require some CSS\nand/or JavaScript, you can use the \ndocs_dir\n. However, for more complex\ncustomizations, including overriding templates, you will need to use the\n\ntheme_dir\n.\n\n\nUsing the docs_dir\n\uf0c1\n\n\nThe \nextra_css\n and \nextra_javascript\n configuration options can be used to\nmake tweaks and customizations to existing themes. To use these, you simply\nneed to include either CSS or JavaScript files within your \ndocumentation\ndirectory\n.\n\n\nFor example, to change the colour of the headers in your documentation, create\na file called \nextra.css\n and place it next to the documentation Markdown. In\nthat file add the following CSS.\n\n\nh1 {\n color: red;\n}\n\n\n\n\n\n\nNote\n\n\nIf you are deploying your documentation with \nReadTheDocs\n. 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\n\nextra_css: [extra.css]\n\n\n\n\n\nAfter making these changes, they should be visible when you run\n\nmkdocs serve\n - if you already had this running, you should see that the CSS\nchanges were automatically picked up and the documentation will be updated.\n\n\n\n\nNote\n\n\nAny extra CSS or JavaScript files will be added to the generated HTML\ndocument after the page content. If you desire to include a JavaScript\nlibrary, you may have better success including the library by using the\n\ntheme_dir\n.\n\n\n\n\nUsing the theme_dir\n\uf0c1\n\n\nThe \ntheme_dir\n configuration option can be used to point to a directory of\nfiles which override the files in the theme set on the \ntheme\n configuration\noption. Any file in the \ntheme_dir\n with the same name as a file in the \ntheme\n\nwill replace the file of the same name in the \ntheme\n. Any additional files in\nthe \ntheme_dir\n will be added to the \ntheme\n. The contents of the \ntheme_dir\n\nshould mirror the directory structure of the \ntheme\n. You may include templates,\nJavaScript files, CSS files, images, fonts, or any other media included in a\ntheme.\n\n\n\n\nNote\n\n\nFor this to work, the \ntheme\n setting must be set to a known installed theme.\nIf the \ntheme\n setting is instead set to \nnull\n (or not defined), then there\nis no theme to override and the contents of the \ntheme_dir\n must be a\ncomplete, standalone theme. See \nCustom Themes\n for more\ninformation.\n\n\n\n\nFor example, the \nmkdocs\n theme (\nbrowse source\n), contains the following\ndirectory structure (in part):\n\n\n- css\\\n- fonts\\\n- img\\\n - favicon.ico\n - grid.png\n- js\\\n- 404.html\n- base.html\n- content.html\n- nav-sub.html\n- nav.html\n- toc.html\n\n\n\n\nTo override any of the files contained in that theme, create a new directory\nnext to your \ndocs_dir\n:\n\n\nmkdir custom_theme\n\n\n\n\nAnd then point your \nmkdocs.yml\n configuration file at the new directory:\n\n\ntheme_dir: custom_theme\n\n\n\n\nTo override the 404 error page (\"file not found\"), add a new template file named\n\n404.html\n to the \ncustom_theme\n directory. For information on what can be\nincluded in a template, review the documentation for building a \ncustom theme\n.\n\n\nTo override the favicon, you can add a new icon file at\n\ncustom_theme/img/favicon.ico\n.\n\n\nTo include a JavaScript library, copy the library to the \ncustom_theme/js/\n\ndirectory.\n\n\nYour directory structure should now look like this:\n\n\n- docs/\n - index.html\n- custom_theme/\n - img/\n - favicon.ico\n - js/\n - somelib.js\n - 404.html\n- config.yml\n\n\n\n\n\n\nNote\n\n\nAny files included in the \ntheme\n but not included in the \ntheme_dir\n will\nstill be utilized. The \ntheme_dir\n will only override/replace files in the\n\ntheme\n. If you want to remove files, or build a theme from scratch, then\nyou should review the documentation for building a \ncustom theme\n.\n\n\n\n\nOverriding Template Blocks\n\uf0c1\n\n\nThe built-in themes implement many of their parts inside template blocks which\ncan be individually overridden in the \nmain.html\n template. Simply create a\n\nmain.html\n template file in your \ntheme_dir\n and define replacement blocks\nwithin that file. Just make sure that the \nmain.html\n extends \nbase.html\n. For\nexample, to alter the title of the MkDocs theme, your replacement \nmain.html\n\ntemplate would contain the following:\n\n\n{% extends \nbase.html\n %}\n\n{% block title %}\n\ntitle\nCustom title goes here\n/title\n\n{% endblock %}\n\n\n\n\nIn the above example, the title block defined in your custom \nmain.html\n file\nwill be used in place of the default title block defined in the parent theme.\nYou may re-define as many blocks as you desire, as long as those blocks are\ndefined in the parent. For example, you could replace the Google Analytics\nscript with one for a different service or replace the search feature with your\nown. You will need to consult the parent theme you are using to determine what\nblocks are available to override. The MkDocs and ReadTheDocs themes provide the\nfollowing blocks:\n\n\n\n\nsite_meta\n: Contains meta tags in the document head.\n\n\nhtmltitle\n: Contains the page title in the document head.\n\n\nstyles\n: Contains the link tags for stylesheets.\n\n\nlibs\n: Contains the JavaScript libraries (jQuery, etc) included in the page header.\n\n\nscripts\n: Contains JavaScript scripts which should execute after a page loads.\n\n\nanalytics\n: Contains the analytics script.\n\n\nextrahead\n: An empty block in the \nhead\n to insert custom tags/scripts/etc.\n\n\nsite_name\n: Contains the site name in the navigation bar.\n\n\nsite_nav\n: Contains the site navigation in the navigation bar.\n\n\nsearch_box\n: Contains the search box in the navigation bar.\n\n\nnext_prev\n: Contains the next and previous buttons in the navigation bar.\n\n\nrepo\n: Contains the repository link in the navigation bar.\n\n\ncontent\n: Contains the page content and table of contents for the page.\n\n\nfooter\n: Contains the page footer.\n\n\n\n\nYou may need to view the source template files to ensure your modifications will\nwork with the structure of the site. See \nTemplate Variables\n for a list of\nvariables you can use within your custom blocks. For a more complete\nexplaination of blocks, consult the \nJinja documentation\n.\n\n\nCombining the theme_dir and Template Blocks\n\uf0c1\n\n\nAdding a JavaScript library to the \ntheme_dir\n will make it available, but\nwon't include it in the pages generated by MkDocs. Therefore, a link needs to\nbe added to the library from the HTML.\n\n\nStarting the with directory structure above (truncated):\n\n\n- docs/\n- custom_theme/\n - js/\n - somelib.js\n- config.yml\n\n\n\n\nA link to the \ncustom_theme/js/somelib.js\n file needs to be added to the\ntemplate. As \nsomelib.js\n is a JavaScript library, it would logically go in the\n\nlibs\n block. However, a new \nlibs\n block that only includes the new script will\nreplace the block defined in the parent template and any links to libraries in\nthe parent template will be removed. To avoid breaking the template, a\n\nsuper block\n can be used with a call to \nsuper\n from within the block:\n\n\n{% extends \nbase.html\n %}\n\n{% block libs %}\n {{ super() }}\n \nscript src=\n{{ base_url }}/js/somelib.js\n/script\n\n{% endblock %}\n\n\n\n\nNote that the \nbase_url\n template variable was used to ensure that the link is\nalways relative to the current page.\n\n\nNow the generated pages will include links to the template provided libraries as\nwell as the library included in the \ntheme_dir\n. The same would be required for\nany additional CSS files included in the \ntheme_dir\n.", + "location": "/user-guide/styling-your-docs/", + "text": "Styling your docs\n\uf0c1\n\n\nHow to style and theme your documentation.\n\n\n\n\nMkDocs includes a couple \nbuilt-in themes\n as well as various \nthird party\nthemes\n, all of which can easily be customized with \nextra CSS or\nJavaScript\n or overridden from the \ntheme directory\n. You\ncan also create your own \ncustom theme\n from the grown up for your\ndocumentation.\n\n\nTo use a theme that is included in MkDocs, simply add this to your\n\nmkdocs.yml\n config file.\n\n\ntheme: readthedocs\n\n\n\nReplace \nreadthedocs\n with any of the \nbuilt-in themes\n listed below.\n\n\nTo create a new custom theme see the \nCustom Themes\n page, or to\nmore heavily customize an existing theme, see\nthe \nCustomizing a Theme\n section below.\n\n\nBuilt-in themes\n\uf0c1\n\n\nmkdocs\n\uf0c1\n\n\n\n\nreadthedocs\n\uf0c1\n\n\n\n\nThird Party Themes\n\uf0c1\n\n\nA list of third party themes can be found in the MkDocs \ncommunity wiki\n. If you\nhave created your own, please feel free to add it to the list.\n\n\nCustomizing a Theme\n\uf0c1\n\n\nIf you would like to make a few tweaks to an existing theme, there is no need to\ncreate your own theme from scratch. For minor tweaks which only require some CSS\nand/or JavaScript, you can use the \ndocs_dir\n. However, for more complex\ncustomizations, including overriding templates, you will need to use the\n\ntheme_dir\n.\n\n\nUsing the docs_dir\n\uf0c1\n\n\nThe \nextra_css\n and \nextra_javascript\n configuration options can be used to\nmake tweaks and customizations to existing themes. To use these, you simply\nneed to include either CSS or JavaScript files within your \ndocumentation\ndirectory\n.\n\n\nFor example, to change the colour of the headers in your documentation, create\na file called \nextra.css\n and place it next to the documentation Markdown. In\nthat file add the following CSS.\n\n\nh1 {\n color: red;\n}\n\n\n\n\n\n\nNote\n\n\nIf you are deploying your documentation with \nReadTheDocs\n. 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\n\nextra_css: [extra.css]\n\n\n\n\n\nAfter making these changes, they should be visible when you run\n\nmkdocs serve\n - if you already had this running, you should see that the CSS\nchanges were automatically picked up and the documentation will be updated.\n\n\n\n\nNote\n\n\nAny extra CSS or JavaScript files will be added to the generated HTML\ndocument after the page content. If you desire to include a JavaScript\nlibrary, you may have better success including the library by using the\n\ntheme_dir\n.\n\n\n\n\nUsing the theme_dir\n\uf0c1\n\n\nThe \ntheme_dir\n configuration option can be used to point to a directory of\nfiles which override the files in the theme set on the \ntheme\n configuration\noption. Any file in the \ntheme_dir\n with the same name as a file in the \ntheme\n\nwill replace the file of the same name in the \ntheme\n. Any additional files in\nthe \ntheme_dir\n will be added to the \ntheme\n. The contents of the \ntheme_dir\n\nshould mirror the directory structure of the \ntheme\n. You may include templates,\nJavaScript files, CSS files, images, fonts, or any other media included in a\ntheme.\n\n\n\n\nNote\n\n\nFor this to work, the \ntheme\n setting must be set to a known installed theme.\nIf the \ntheme\n setting is instead set to \nnull\n (or not defined), then there\nis no theme to override and the contents of the \ntheme_dir\n must be a\ncomplete, standalone theme. See \nCustom Themes\n for more\ninformation.\n\n\n\n\nFor example, the \nmkdocs\n theme (\nbrowse source\n), contains the following\ndirectory structure (in part):\n\n\n- css\\\n- fonts\\\n- img\\\n - favicon.ico\n - grid.png\n- js\\\n- 404.html\n- base.html\n- content.html\n- nav-sub.html\n- nav.html\n- toc.html\n\n\n\n\nTo override any of the files contained in that theme, create a new directory\nnext to your \ndocs_dir\n:\n\n\nmkdir custom_theme\n\n\n\n\nAnd then point your \nmkdocs.yml\n configuration file at the new directory:\n\n\ntheme_dir: custom_theme\n\n\n\n\nTo override the 404 error page (\"file not found\"), add a new template file named\n\n404.html\n to the \ncustom_theme\n directory. For information on what can be\nincluded in a template, review the documentation for building a \ncustom theme\n.\n\n\nTo override the favicon, you can add a new icon file at\n\ncustom_theme/img/favicon.ico\n.\n\n\nTo include a JavaScript library, copy the library to the \ncustom_theme/js/\n\ndirectory.\n\n\nYour directory structure should now look like this:\n\n\n- docs/\n - index.html\n- custom_theme/\n - img/\n - favicon.ico\n - js/\n - somelib.js\n - 404.html\n- config.yml\n\n\n\n\n\n\nNote\n\n\nAny files included in the \ntheme\n but not included in the \ntheme_dir\n will\nstill be utilized. The \ntheme_dir\n will only override/replace files in the\n\ntheme\n. If you want to remove files, or build a theme from scratch, then\nyou should review the documentation for building a \ncustom theme\n.\n\n\n\n\nOverriding Template Blocks\n\uf0c1\n\n\nThe built-in themes implement many of their parts inside template blocks which\ncan be individually overridden in the \nmain.html\n template. Simply create a\n\nmain.html\n template file in your \ntheme_dir\n and define replacement blocks\nwithin that file. Just make sure that the \nmain.html\n extends \nbase.html\n. For\nexample, to alter the title of the MkDocs theme, your replacement \nmain.html\n\ntemplate would contain the following:\n\n\n{% extends \"base.html\" %}\n\n{% block title %}\nCustom title goes here\n{% endblock %}\n\n\n\n\nIn the above example, the title block defined in your custom \nmain.html\n file\nwill be used in place of the default title block defined in the parent theme.\nYou may re-define as many blocks as you desire, as long as those blocks are\ndefined in the parent. For example, you could replace the Google Analytics\nscript with one for a different service or replace the search feature with your\nown. You will need to consult the parent theme you are using to determine what\nblocks are available to override. The MkDocs and ReadTheDocs themes provide the\nfollowing blocks:\n\n\n\n\nsite_meta\n: Contains meta tags in the document head.\n\n\nhtmltitle\n: Contains the page title in the document head.\n\n\nstyles\n: Contains the link tags for stylesheets.\n\n\nlibs\n: Contains the JavaScript libraries (jQuery, etc) included in the page header.\n\n\nscripts\n: Contains JavaScript scripts which should execute after a page loads.\n\n\nanalytics\n: Contains the analytics script.\n\n\nextrahead\n: An empty block in the \n\n to insert custom tags/scripts/etc.\n\n\nsite_name\n: Contains the site name in the navigation bar.\n\n\nsite_nav\n: Contains the site navigation in the navigation bar.\n\n\nsearch_box\n: Contains the search box in the navigation bar.\n\n\nnext_prev\n: Contains the next and previous buttons in the navigation bar.\n\n\nrepo\n: Contains the repository link in the navigation bar.\n\n\ncontent\n: Contains the page content and table of contents for the page.\n\n\nfooter\n: Contains the page footer.\n\n\n\n\nYou may need to view the source template files to ensure your modifications will\nwork with the structure of the site. See \nTemplate Variables\n for a list of\nvariables you can use within your custom blocks. For a more complete\nexplaination of blocks, consult the \nJinja documentation\n.\n\n\nCombining the theme_dir and Template Blocks\n\uf0c1\n\n\nAdding a JavaScript library to the \ntheme_dir\n will make it available, but\nwon't include it in the pages generated by MkDocs. Therefore, a link needs to\nbe added to the library from the HTML.\n\n\nStarting the with directory structure above (truncated):\n\n\n- docs/\n- custom_theme/\n - js/\n - somelib.js\n- config.yml\n\n\n\n\nA link to the \ncustom_theme/js/somelib.js\n file needs to be added to the\ntemplate. As \nsomelib.js\n is a JavaScript library, it would logically go in the\n\nlibs\n block. However, a new \nlibs\n block that only includes the new script will\nreplace the block defined in the parent template and any links to libraries in\nthe parent template will be removed. To avoid breaking the template, a\n\nsuper block\n can be used with a call to \nsuper\n from within the block:\n\n\n{% extends \"base.html\" %}\n\n{% block libs %}\n {{ super() }}\n \n{% endblock %}\n\n\n\n\nNote that the \nbase_url\n template variable was used to ensure that the link is\nalways relative to the current page.\n\n\nNow the generated pages will include links to the template provided libraries as\nwell as the library included in the \ntheme_dir\n. The same would be required for\nany additional CSS files included in the \ntheme_dir\n.", "title": "Styling Your Docs" - }, + }, { - "location": "/user-guide/styling-your-docs/#styling-your-docs", - "text": "How to style and theme your documentation. MkDocs includes a couple built-in themes as well as various third party\nthemes , all of which can easily be customized with extra CSS or\nJavaScript or overridden from the theme directory . You\ncan also create your own custom theme from the grown up for your\ndocumentation. To use a theme that is included in MkDocs, simply add this to your mkdocs.yml config file. theme: readthedocs Replace readthedocs with any of the built-in themes listed below. To create a new custom theme see the Custom Themes page, or to\nmore heavily customize an existing theme, see\nthe Customizing a Theme section below.", + "location": "/user-guide/styling-your-docs/#styling-your-docs", + "text": "How to style and theme your documentation. MkDocs includes a couple built-in themes as well as various third party\nthemes , all of which can easily be customized with extra CSS or\nJavaScript or overridden from the theme directory . You\ncan also create your own custom theme from the grown up for your\ndocumentation. To use a theme that is included in MkDocs, simply add this to your mkdocs.yml config file. theme: readthedocs Replace readthedocs with any of the built-in themes listed below. To create a new custom theme see the Custom Themes page, or to\nmore heavily customize an existing theme, see\nthe Customizing a Theme section below.", "title": "Styling your docs" - }, + }, { - "location": "/user-guide/styling-your-docs/#built-in-themes", - "text": "", + "location": "/user-guide/styling-your-docs/#built-in-themes", + "text": "", "title": "Built-in themes" - }, + }, { - "location": "/user-guide/styling-your-docs/#mkdocs", - "text": "", + "location": "/user-guide/styling-your-docs/#mkdocs", + "text": "", "title": "mkdocs" - }, + }, { - "location": "/user-guide/styling-your-docs/#readthedocs", - "text": "", + "location": "/user-guide/styling-your-docs/#readthedocs", + "text": "", "title": "readthedocs" - }, + }, { - "location": "/user-guide/styling-your-docs/#third-party-themes", - "text": "A list of third party themes can be found in the MkDocs community wiki . If you\nhave created your own, please feel free to add it to the list.", + "location": "/user-guide/styling-your-docs/#third-party-themes", + "text": "A list of third party themes can be found in the MkDocs community wiki . If you\nhave created your own, please feel free to add it to the list.", "title": "Third Party Themes" - }, + }, { - "location": "/user-guide/styling-your-docs/#customizing-a-theme", - "text": "If you would like to make a few tweaks to an existing theme, there is no need to\ncreate your own theme from scratch. For minor tweaks which only require some CSS\nand/or JavaScript, you can use the docs_dir . However, for more complex\ncustomizations, including overriding templates, you will need to use the theme_dir .", + "location": "/user-guide/styling-your-docs/#customizing-a-theme", + "text": "If you would like to make a few tweaks to an existing theme, there is no need to\ncreate your own theme from scratch. For minor tweaks which only require some CSS\nand/or JavaScript, you can use the docs_dir . However, for more complex\ncustomizations, including overriding templates, you will need to use the theme_dir .", "title": "Customizing a Theme" - }, + }, { - "location": "/user-guide/styling-your-docs/#using-the-docs_dir", - "text": "The extra_css and extra_javascript configuration options can be used to\nmake tweaks and customizations to existing themes. To use these, you simply\nneed to include either CSS or JavaScript files within your documentation\ndirectory . 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. h1 {\n color: red;\n} Note 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. 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\nchanges were automatically picked up and the documentation will be updated. Note Any extra CSS or JavaScript files will be added to the generated HTML\ndocument after the page content. If you desire to include a JavaScript\nlibrary, you may have better success including the library by using the theme_dir .", + "location": "/user-guide/styling-your-docs/#using-the-docs_dir", + "text": "The extra_css and extra_javascript configuration options can be used to\nmake tweaks and customizations to existing themes. To use these, you simply\nneed to include either CSS or JavaScript files within your documentation\ndirectory . 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. h1 {\n color: red;\n} Note 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. 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\nchanges were automatically picked up and the documentation will be updated. Note Any extra CSS or JavaScript files will be added to the generated HTML\ndocument after the page content. If you desire to include a JavaScript\nlibrary, you may have better success including the library by using the theme_dir .", "title": "Using the docs_dir" - }, + }, { - "location": "/user-guide/styling-your-docs/#using-the-theme_dir", - "text": "The theme_dir configuration option can be used to point to a directory of\nfiles which override the files in the theme set on the theme configuration\noption. Any file in the theme_dir with the same name as a file in the theme \nwill replace the file of the same name in the theme . Any additional files in\nthe theme_dir will be added to the theme . The contents of the theme_dir \nshould mirror the directory structure of the theme . You may include templates,\nJavaScript files, CSS files, images, fonts, or any other media included in a\ntheme. Note For this to work, the theme setting must be set to a known installed theme.\nIf the theme setting is instead set to null (or not defined), then there\nis no theme to override and the contents of the theme_dir must be a\ncomplete, standalone theme. See Custom Themes for more\ninformation. For example, the mkdocs theme ( browse source ), contains the following\ndirectory structure (in part): - css\\\n- fonts\\\n- img\\\n - favicon.ico\n - grid.png\n- js\\\n- 404.html\n- base.html\n- content.html\n- nav-sub.html\n- nav.html\n- toc.html To override any of the files contained in that theme, create a new directory\nnext to your docs_dir : mkdir custom_theme And then point your mkdocs.yml configuration file at the new directory: 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\nincluded 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/ \ndirectory. Your directory structure should now look like this: - docs/\n - index.html\n- custom_theme/\n - img/\n - favicon.ico\n - js/\n - somelib.js\n - 404.html\n- config.yml Note Any files included in the theme but not included in the theme_dir will\nstill 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\nyou should review the documentation for building a custom theme .", + "location": "/user-guide/styling-your-docs/#using-the-theme_dir", + "text": "The theme_dir configuration option can be used to point to a directory of\nfiles which override the files in the theme set on the theme configuration\noption. Any file in the theme_dir with the same name as a file in the theme \nwill replace the file of the same name in the theme . Any additional files in\nthe theme_dir will be added to the theme . The contents of the theme_dir \nshould mirror the directory structure of the theme . You may include templates,\nJavaScript files, CSS files, images, fonts, or any other media included in a\ntheme. Note For this to work, the theme setting must be set to a known installed theme.\nIf the theme setting is instead set to null (or not defined), then there\nis no theme to override and the contents of the theme_dir must be a\ncomplete, standalone theme. See Custom Themes for more\ninformation. For example, the mkdocs theme ( browse source ), contains the following\ndirectory structure (in part): - css\\\n- fonts\\\n- img\\\n - favicon.ico\n - grid.png\n- js\\\n- 404.html\n- base.html\n- content.html\n- nav-sub.html\n- nav.html\n- toc.html To override any of the files contained in that theme, create a new directory\nnext to your docs_dir : mkdir custom_theme And then point your mkdocs.yml configuration file at the new directory: 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\nincluded 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/ \ndirectory. Your directory structure should now look like this: - docs/\n - index.html\n- custom_theme/\n - img/\n - favicon.ico\n - js/\n - somelib.js\n - 404.html\n- config.yml Note Any files included in the theme but not included in the theme_dir will\nstill 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\nyou should review the documentation for building a custom theme .", "title": "Using the theme_dir" - }, + }, { - "location": "/user-guide/styling-your-docs/#overriding-template-blocks", - "text": "The built-in themes implement many of their parts inside template blocks which\ncan be individually overridden in the main.html template. Simply create a main.html template file in your theme_dir and define replacement blocks\nwithin that file. Just make sure that the main.html extends base.html . For\nexample, to alter the title of the MkDocs theme, your replacement main.html \ntemplate would contain the following: {% extends base.html %}\n\n{% block title %} title Custom title goes here /title \n{% endblock %} In the above example, the title block defined in your custom main.html file\nwill be used in place of the default title block defined in the parent theme.\nYou may re-define as many blocks as you desire, as long as those blocks are\ndefined in the parent. For example, you could replace the Google Analytics\nscript with one for a different service or replace the search feature with your\nown. You will need to consult the parent theme you are using to determine what\nblocks are available to override. The MkDocs and ReadTheDocs themes provide the\nfollowing 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\nwork with the structure of the site. See Template Variables for a list of\nvariables you can use within your custom blocks. For a more complete\nexplaination of blocks, consult the Jinja documentation .", + "location": "/user-guide/styling-your-docs/#overriding-template-blocks", + "text": "The built-in themes implement many of their parts inside template blocks which\ncan be individually overridden in the main.html template. Simply create a main.html template file in your theme_dir and define replacement blocks\nwithin that file. Just make sure that the main.html extends base.html . For\nexample, to alter the title of the MkDocs theme, your replacement main.html \ntemplate would contain the following: {% extends \"base.html\" %}\n\n{% block title %}\nCustom title goes here\n{% endblock %} In the above example, the title block defined in your custom main.html file\nwill be used in place of the default title block defined in the parent theme.\nYou may re-define as many blocks as you desire, as long as those blocks are\ndefined in the parent. For example, you could replace the Google Analytics\nscript with one for a different service or replace the search feature with your\nown. You will need to consult the parent theme you are using to determine what\nblocks are available to override. The MkDocs and ReadTheDocs themes provide the\nfollowing 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 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\nwork with the structure of the site. See Template Variables for a list of\nvariables you can use within your custom blocks. For a more complete\nexplaination of blocks, consult the Jinja documentation .", "title": "Overriding Template Blocks" - }, + }, { - "location": "/user-guide/styling-your-docs/#combining-the-theme_dir-and-template-blocks", - "text": "Adding a JavaScript library to the theme_dir will make it available, but\nwon't include it in the pages generated by MkDocs. Therefore, a link needs to\nbe added to the library from the HTML. Starting the with directory structure above (truncated): - docs/\n- custom_theme/\n - js/\n - somelib.js\n- config.yml A link to the custom_theme/js/somelib.js file needs to be added to the\ntemplate. 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\nreplace the block defined in the parent template and any links to libraries in\nthe 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: {% extends base.html %}\n\n{% block libs %}\n {{ super() }}\n script src= {{ base_url }}/js/somelib.js /script \n{% endblock %} Note that the base_url template variable was used to ensure that the link is\nalways relative to the current page. Now the generated pages will include links to the template provided libraries as\nwell as the library included in the theme_dir . The same would be required for\nany additional CSS files included in the theme_dir .", + "location": "/user-guide/styling-your-docs/#combining-the-theme_dir-and-template-blocks", + "text": "Adding a JavaScript library to the theme_dir will make it available, but\nwon't include it in the pages generated by MkDocs. Therefore, a link needs to\nbe added to the library from the HTML. Starting the with directory structure above (truncated): - docs/\n- custom_theme/\n - js/\n - somelib.js\n- config.yml A link to the custom_theme/js/somelib.js file needs to be added to the\ntemplate. 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\nreplace the block defined in the parent template and any links to libraries in\nthe 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: {% extends \"base.html\" %}\n\n{% block libs %}\n {{ super() }}\n \n{% endblock %} Note that the base_url template variable was used to ensure that the link is\nalways relative to the current page. Now the generated pages will include links to the template provided libraries as\nwell as the library included in the theme_dir . The same would be required for\nany additional CSS files included in the theme_dir .", "title": "Combining the theme_dir and Template Blocks" - }, + }, { - "location": "/user-guide/configuration/", - "text": "Configuration\n\uf0c1\n\n\nGuide to all available configuration settings.\n\n\n\n\nIntroduction\n\uf0c1\n\n\nProject settings are always configured by using a YAML configuration file in the\nproject directory named \nmkdocs.yml\n.\n\n\nAs a minimum this configuration file must contain the \nsite_name\n setting. All\nother settings are optional.\n\n\nProject information\n\uf0c1\n\n\nsite_name\n\uf0c1\n\n\nThis is a \nrequired setting\n, and should be a string that is used as the main\ntitle for the project documentation. For example:\n\n\nsite_name: Marshmallow Generator\n\n\n\n\nWhen rendering the theme this setting will be passed as the \nsite_name\n context\nvariable.\n\n\nsite_url\n\uf0c1\n\n\nSet the canonical URL of the site. This will add a link tag with the canonical\nURL to the generated HTML header.\n\n\ndefault\n: \nnull\n\n\nrepo_url\n\uf0c1\n\n\nWhen set, provides a link to your GitHub or Bitbucket repository on each page.\n\n\nrepo_url: https://github.com/example/repository/\n\n\n\n\ndefault\n: \nnull\n\n\nrepo_name\n\uf0c1\n\n\nWhen set, provides a link to your GitHub or Bitbucket repository on each page.\n\n\ndefault\n: \n'GitHub'\n or \n'Bitbucket'\n if the \nrepo_url\n matches those\ndomains, otherwise \nnull\n\n\nedit_uri\n\uf0c1\n\n\nPath from the base \nrepo_url\n to the docs directory when directly viewing a\npage, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,\netc), the branch, and the docs directory itself. Mkdocs concatenates \nrepo_url\n\nand \nedit_uri\n, and appends the input path of the page.\n\n\nWhen set, provides a link directly to the page in your source repository. This\nmakes it easier to find and edit the source for the page. If \nrepo_url\n is not\nset, this option is ignored.\n\n\nFor example, for a GitHub-hosted repository, the \nedit_uri\n would be as follows.\n(Note the \nedit\n path and \nmaster\n branch...)\n\n\nedit_uri: edit/master/docs/\n\n\n\n\nFor a Bitbucket-hosted repository, the equivalent \nedit_uri\n would be as\nfollows. (Note the \nsrc\n path and \ndefault\n branch...)\n\n\nedit_uri: src/default/docs/\n\n\n\n\nFor other repository hosts, \nedit_uri\n works the same way. Simply specify the\nrelative path to the docs directory.\n\n\ndefault\n: \nedit/master/docs/\n or \nsrc/default/docs/\n for GitHub or Bitbucket\nrepos, respectively, if \nrepo_url\n matches those domains, otherwise \nnull\n\n\n\n\nNote:\n\n\nOn GitHub, the \nedit\n path opens the page in the online GitHub editor. This\nfunctionality requires that the user have and be logged in to a GitHub\naccount. Otherwise, the user will be redirected to a login/signup page.\nAlternatively, use the \nblob\n path to open a read-only view, which supports\nanonymous access. E.g. \nblob/master/docs/\n\n\n\n\nsite_description\n\uf0c1\n\n\nSet the site description. This will add a meta tag to the generated HTML header.\n\n\ndefault\n: \nnull\n\n\nsite_author\n\uf0c1\n\n\nSet the name of the author. This will add a meta tag to the generated HTML\nheader.\n\n\ndefault\n: \nnull\n\n\ncopyright\n\uf0c1\n\n\nSet the copyright information to be included in the documentation by the theme.\n\n\ndefault\n: \nnull\n\n\ngoogle_analytics\n\uf0c1\n\n\nSet the Google analytics tracking configuration.\n\n\ngoogle_analytics: ['UA-36723568-3', 'mkdocs.org']\n\n\n\n\ndefault\n: \nnull\n\n\nremote_branch\n\uf0c1\n\n\nSet the remote branch to commit to when using \ngh-deploy\n to deploy to Github\nPages. This option can be overridden by a command line option in \ngh-deploy\n.\n\n\ndefault\n: \ngh-pages\n\n\nremote_name\n\uf0c1\n\n\nSet the remote name to push to when using \ngh-deploy\n to deploy to Github Pages.\nThis option can be overridden by a command line option in \ngh-deploy\n.\n\n\ndefault\n: \ngh-pages\n\n\nDocumentation layout\n\uf0c1\n\n\npages\n\uf0c1\n\n\nThis 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 \nindex.md\n, \nuser-guide.md\n and\n\nabout.md\n, respectively.\n\n\npages:\n - 'Introduction': 'index.md'\n - 'User Guide': 'user-guide.md'\n - 'About': 'about.md'\n\n\n\n\nSee the section on \nconfiguring pages and navigation\n for a more detailed\nbreakdown, including how to create sub-sections.\n\n\ndefault\n: By default \npages\n will contain an alphanumerically sorted, nested\nlist of all the Markdown files found within the \ndocs_dir\n and its\nsub-directories. If none are found it will be \n[]\n (an empty list).\n\n\nBuild directories\n\uf0c1\n\n\ntheme\n\uf0c1\n\n\nSets the theme of your documentation site, for a list of available themes visit\n\nstyling your docs\n.\n\n\ndefault\n: \n'mkdocs'\n\n\ntheme_dir\n\uf0c1\n\n\nLets 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\n\nSee \nstyling your docs\n for details if you would like to tweak an\nexisting theme.\n\n\nSee \ncustom themes\n if you would like to build your own theme from the ground\nup.\n\n\ndefault\n: \nnull\n\n\ndocs_dir\n\uf0c1\n\n\nLets 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\n\ndefault\n: \n'docs'\n\n\nsite_dir\n\uf0c1\n\n\nLets 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\n\ndefault\n: \n'site'\n\n\n\n\nNote:\n\n\nIf you are using source code control you will normally want to ensure that\nyour \nbuild output\n files are not committed into the repository, and only\nkeep the \nsource\n files under version control. For example, if using \ngit\n\nyou might add the following line to your \n.gitignore\n file:\n\n\nsite/\n\n\n\nIf you're using another source code control tool, you'll want to check its\ndocumentation on how to ignore specific directories.\n\n\n\n\nextra_css\n\uf0c1\n\n\nSet a list of CSS files in your \ndocs_dir\n to be included by the theme. For\nexample, the following example will include the the extra.css file within the\ncss subdirectory in your \ndocs_dir\n.\n\n\nextra_css:\n - css/extra.css\n - css/second_extra.css\n\n\n\n\ndefault\n: \n[]\n (an empty list).\n\n\nextra_javascript\n\uf0c1\n\n\nSet a list of JavaScript files in your \ndocs_dir\n to be included by the theme.\nSee the example in \nextra_css\n for usage.\n\n\ndefault\n: \n[]\n (an empty list).\n\n\nextra_templates\n\uf0c1\n\n\nSet a list of templates in your \ndocs_dir\n to be built by MkDocs. To see more\nabout writing templates for MkDocs read the documentation about \ncustom themes\n\nand specifically the section about the \nvariables that are available\n to\ntemplates. See the example in \nextra_css\n for usage.\n\n\ndefault\n: \n[]\n (an empty list).\n\n\nextra\n\uf0c1\n\n\nA 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\n\nFor example, if you are using a theme that supports displaying the project\nversion, you can pass it to the theme like this:\n\n\nextra:\n version: 1.0\n\n\n\n\ndefault\n: By default \nextra\n will be an empty key value mapping.\n\n\nPreview controls\n\uf0c1\n\n\nuse_directory_urls\n\uf0c1\n\n\nThis setting controls the style used for linking to pages within the\ndocumentation.\n\n\nThe following table demonstrates how the URLs used on the site differ when\nsetting \nuse_directory_urls\n to \ntrue\n or \nfalse\n.\n\n\n\n\n\n\n\n\nSource file\n\n\nGenerated HTML\n\n\nuse_directory_urls=true\n\n\nuse_directory_urls=false\n\n\n\n\n\n\n\n\n\n\nindex.md\n\n\nindex.html\n\n\n/\n\n\n/index.html\n\n\n\n\n\n\napi-guide.md\n\n\napi-guide/index.html\n\n\n/api-guide/\n\n\n/api-guide/index.html\n\n\n\n\n\n\nabout.md\n\n\nabout/index.html\n\n\n/about/\n\n\n/about/index.html\n\n\n\n\n\n\n\n\nThe default style of \nuse_directory_urls=true\n creates more user friendly URLs,\nand is usually what you'll want to use.\n\n\nThe 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 \nfile\n rather than the target\n\ndirectory\n.\n\n\ndefault\n: \ntrue\n\n\nstrict\n\uf0c1\n\n\nDetermines 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\n\ndefault\n: \nfalse\n\n\ndev_addr\n\uf0c1\n\n\nDetermines the address used when running \nmkdocs serve\n. Setting this allows you\nto use another port, or allows you to make the service accessible over your\nlocal network by using the \n0.0.0.0\n address.\n\n\nAs with all settings, you can set this from the command line, which can be\nuseful, for example:\n\n\nmkdocs serve --dev-addr=0.0.0.0:80 # Run on port 80, on the local network.\n\n\n\n\ndefault\n: \n'127.0.0.1:8000'\n\n\nFormatting options\n\uf0c1\n\n\nmarkdown_extensions\n\uf0c1\n\n\nMkDocs uses the \nPython Markdown\n library to translate Markdown files\ninto HTML. Python Markdown supports a variety of \nextensions\n\nthat customize how pages are formatted. This setting lets you enable a list of\nextensions beyond the ones that MkDocs uses by default (\nmeta\n, \ntoc\n, \ntables\n,\nand \nfenced_code\n).\n\n\nFor example, to enable the \nSmartyPants typography extension\n, use:\n\n\nmarkdown_extensions:\n - smarty\n\n\n\n\nSome 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(\noption_name: option value\n) of any options that a given extension supports.\nSee the documentation for the extension you are using to determine what options\nthey support.\n\n\nFor example, to enable permalinks in the (included) \ntoc\n extension, use:\n\n\nmarkdown_extensions:\n - toc:\n permalink: True\n\n\n\n\nNote that a colon (\n:\n) must follow the extension name (\ntoc\n) 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\n\nmarkdown_extensions:\n - toc:\n permalink: True\n separator: \n_\n\n\n\n\n\nAdd 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\n\nmarkdown_extensions:\n - smarty\n - toc:\n permalink: True\n - sane_lists\n\n\n\n\n\n\nSee Also:\n\n\nThe Python-Markdown documentation provides a \nlist of extensions\n\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\n\nYou may also install and use various \nthird party extensions\n. Consult\nthe documentation provided by those extensions for installation instructions\nand available configuration options.\n\n\n\n\ndefault\n: \n[]", + "location": "/user-guide/configuration/", + "text": "Configuration\n\uf0c1\n\n\nGuide to all available configuration settings.\n\n\n\n\nIntroduction\n\uf0c1\n\n\nProject settings are always configured by using a YAML configuration file in the\nproject directory named \nmkdocs.yml\n.\n\n\nAs a minimum this configuration file must contain the \nsite_name\n setting. All\nother settings are optional.\n\n\nProject information\n\uf0c1\n\n\nsite_name\n\uf0c1\n\n\nThis is a \nrequired setting\n, and should be a string that is used as the main\ntitle for the project documentation. For example:\n\n\nsite_name: Marshmallow Generator\n\n\n\n\nWhen rendering the theme this setting will be passed as the \nsite_name\n context\nvariable.\n\n\nsite_url\n\uf0c1\n\n\nSet the canonical URL of the site. This will add a link tag with the canonical\nURL to the generated HTML header.\n\n\ndefault\n: \nnull\n\n\nrepo_url\n\uf0c1\n\n\nWhen set, provides a link to your GitHub or Bitbucket repository on each page.\n\n\nrepo_url: https://github.com/example/repository/\n\n\n\n\ndefault\n: \nnull\n\n\nrepo_name\n\uf0c1\n\n\nWhen set, provides a link to your GitHub or Bitbucket repository on each page.\n\n\ndefault\n: \n'GitHub'\n or \n'Bitbucket'\n if the \nrepo_url\n matches those\ndomains, otherwise \nnull\n\n\nedit_uri\n\uf0c1\n\n\nPath from the base \nrepo_url\n to the docs directory when directly viewing a\npage, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,\netc), the branch, and the docs directory itself. Mkdocs concatenates \nrepo_url\n\nand \nedit_uri\n, and appends the input path of the page.\n\n\nWhen set, provides a link directly to the page in your source repository. This\nmakes it easier to find and edit the source for the page. If \nrepo_url\n is not\nset, this option is ignored.\n\n\nFor example, for a GitHub-hosted repository, the \nedit_uri\n would be as follows.\n(Note the \nedit\n path and \nmaster\n branch...)\n\n\nedit_uri: edit/master/docs/\n\n\n\n\nFor a Bitbucket-hosted repository, the equivalent \nedit_uri\n would be as\nfollows. (Note the \nsrc\n path and \ndefault\n branch...)\n\n\nedit_uri: src/default/docs/\n\n\n\n\nFor other repository hosts, \nedit_uri\n works the same way. Simply specify the\nrelative path to the docs directory.\n\n\ndefault\n: \nedit/master/docs/\n or \nsrc/default/docs/\n for GitHub or Bitbucket\nrepos, respectively, if \nrepo_url\n matches those domains, otherwise \nnull\n\n\n\n\nNote:\n\n\nOn GitHub, the \nedit\n path opens the page in the online GitHub editor. This\nfunctionality requires that the user have and be logged in to a GitHub\naccount. Otherwise, the user will be redirected to a login/signup page.\nAlternatively, use the \nblob\n path to open a read-only view, which supports\nanonymous access. E.g. \nblob/master/docs/\n\n\n\n\nsite_description\n\uf0c1\n\n\nSet the site description. This will add a meta tag to the generated HTML header.\n\n\ndefault\n: \nnull\n\n\nsite_author\n\uf0c1\n\n\nSet the name of the author. This will add a meta tag to the generated HTML\nheader.\n\n\ndefault\n: \nnull\n\n\ncopyright\n\uf0c1\n\n\nSet the copyright information to be included in the documentation by the theme.\n\n\ndefault\n: \nnull\n\n\ngoogle_analytics\n\uf0c1\n\n\nSet the Google analytics tracking configuration.\n\n\ngoogle_analytics: ['UA-36723568-3', 'mkdocs.org']\n\n\n\n\ndefault\n: \nnull\n\n\nremote_branch\n\uf0c1\n\n\nSet the remote branch to commit to when using \ngh-deploy\n to deploy to Github\nPages. This option can be overridden by a command line option in \ngh-deploy\n.\n\n\ndefault\n: \ngh-pages\n\n\nremote_name\n\uf0c1\n\n\nSet the remote name to push to when using \ngh-deploy\n to deploy to Github Pages.\nThis option can be overridden by a command line option in \ngh-deploy\n.\n\n\ndefault\n: \norigin\n\n\nDocumentation layout\n\uf0c1\n\n\npages\n\uf0c1\n\n\nThis 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 \nindex.md\n, \nuser-guide.md\n and\n\nabout.md\n, respectively.\n\n\npages:\n - 'Introduction': 'index.md'\n - 'User Guide': 'user-guide.md'\n - 'About': 'about.md'\n\n\n\n\nSee the section on \nconfiguring pages and navigation\n for a more detailed\nbreakdown, including how to create sub-sections.\n\n\ndefault\n: By default \npages\n will contain an alphanumerically sorted, nested\nlist of all the Markdown files found within the \ndocs_dir\n and its\nsub-directories. If none are found it will be \n[]\n (an empty list).\n\n\nBuild directories\n\uf0c1\n\n\ntheme\n\uf0c1\n\n\nSets the theme of your documentation site, for a list of available themes visit\n\nstyling your docs\n.\n\n\ndefault\n: \n'mkdocs'\n\n\ntheme_dir\n\uf0c1\n\n\nLets 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\n\nSee \nstyling your docs\n for details if you would like to tweak an\nexisting theme.\n\n\nSee \ncustom themes\n if you would like to build your own theme from the ground\nup.\n\n\ndefault\n: \nnull\n\n\ndocs_dir\n\uf0c1\n\n\nLets 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\n\ndefault\n: \n'docs'\n\n\nsite_dir\n\uf0c1\n\n\nLets 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\n\ndefault\n: \n'site'\n\n\n\n\nNote:\n\n\nIf you are using source code control you will normally want to ensure that\nyour \nbuild output\n files are not committed into the repository, and only\nkeep the \nsource\n files under version control. For example, if using \ngit\n\nyou might add the following line to your \n.gitignore\n file:\n\n\nsite/\n\n\n\nIf you're using another source code control tool, you'll want to check its\ndocumentation on how to ignore specific directories.\n\n\n\n\nextra_css\n\uf0c1\n\n\nSet a list of CSS files in your \ndocs_dir\n to be included by the theme. For\nexample, the following example will include the the extra.css file within the\ncss subdirectory in your \ndocs_dir\n.\n\n\nextra_css:\n - css/extra.css\n - css/second_extra.css\n\n\n\n\ndefault\n: \n[]\n (an empty list).\n\n\nextra_javascript\n\uf0c1\n\n\nSet a list of JavaScript files in your \ndocs_dir\n to be included by the theme.\nSee the example in \nextra_css\n for usage.\n\n\ndefault\n: \n[]\n (an empty list).\n\n\nextra_templates\n\uf0c1\n\n\nSet a list of templates in your \ndocs_dir\n to be built by MkDocs. To see more\nabout writing templates for MkDocs read the documentation about \ncustom themes\n\nand specifically the section about the \nvariables that are available\n to\ntemplates. See the example in \nextra_css\n for usage.\n\n\ndefault\n: \n[]\n (an empty list).\n\n\nextra\n\uf0c1\n\n\nA 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\n\nFor example, if you are using a theme that supports displaying the project\nversion, you can pass it to the theme like this:\n\n\nextra:\n version: 1.0\n\n\n\n\ndefault\n: By default \nextra\n will be an empty key value mapping.\n\n\nPreview controls\n\uf0c1\n\n\nuse_directory_urls\n\uf0c1\n\n\nThis setting controls the style used for linking to pages within the\ndocumentation.\n\n\nThe following table demonstrates how the URLs used on the site differ when\nsetting \nuse_directory_urls\n to \ntrue\n or \nfalse\n.\n\n\n\n\n\n\n\n\nSource file\n\n\nGenerated HTML\n\n\nuse_directory_urls=true\n\n\nuse_directory_urls=false\n\n\n\n\n\n\n\n\n\n\nindex.md\n\n\nindex.html\n\n\n/\n\n\n/index.html\n\n\n\n\n\n\napi-guide.md\n\n\napi-guide/index.html\n\n\n/api-guide/\n\n\n/api-guide/index.html\n\n\n\n\n\n\nabout.md\n\n\nabout/index.html\n\n\n/about/\n\n\n/about/index.html\n\n\n\n\n\n\n\n\nThe default style of \nuse_directory_urls=true\n creates more user friendly URLs,\nand is usually what you'll want to use.\n\n\nThe 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 \nfile\n rather than the target\n\ndirectory\n.\n\n\ndefault\n: \ntrue\n\n\nstrict\n\uf0c1\n\n\nDetermines 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\n\ndefault\n: \nfalse\n\n\ndev_addr\n\uf0c1\n\n\nDetermines the address used when running \nmkdocs serve\n. Setting this allows you\nto use another port, or allows you to make the service accessible over your\nlocal network by using the \n0.0.0.0\n address.\n\n\nAs with all settings, you can set this from the command line, which can be\nuseful, for example:\n\n\nmkdocs serve --dev-addr=0.0.0.0:80 # Run on port 80, on the local network.\n\n\n\n\ndefault\n: \n'127.0.0.1:8000'\n\n\nFormatting options\n\uf0c1\n\n\nmarkdown_extensions\n\uf0c1\n\n\nMkDocs uses the \nPython Markdown\n library to translate Markdown files\ninto HTML. Python Markdown supports a variety of \nextensions\n\nthat customize how pages are formatted. This setting lets you enable a list of\nextensions beyond the ones that MkDocs uses by default (\nmeta\n, \ntoc\n, \ntables\n,\nand \nfenced_code\n).\n\n\nFor example, to enable the \nSmartyPants typography extension\n, use:\n\n\nmarkdown_extensions:\n - smarty\n\n\n\n\nSome 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(\noption_name: option value\n) of any options that a given extension supports.\nSee the documentation for the extension you are using to determine what options\nthey support.\n\n\nFor example, to enable permalinks in the (included) \ntoc\n extension, use:\n\n\nmarkdown_extensions:\n - toc:\n permalink: True\n\n\n\n\nNote that a colon (\n:\n) must follow the extension name (\ntoc\n) 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\n\nmarkdown_extensions:\n - toc:\n permalink: True\n separator: \"_\"\n\n\n\n\nAdd 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\n\nmarkdown_extensions:\n - smarty\n - toc:\n permalink: True\n - sane_lists\n\n\n\n\n\n\nSee Also:\n\n\nThe Python-Markdown documentation provides a \nlist of extensions\n\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\n\nYou may also install and use various \nthird party extensions\n. Consult\nthe documentation provided by those extensions for installation instructions\nand available configuration options.\n\n\n\n\ndefault\n: \n[]", "title": "Configuration" - }, + }, { - "location": "/user-guide/configuration/#configuration", - "text": "Guide to all available configuration settings.", + "location": "/user-guide/configuration/#configuration", + "text": "Guide to all available configuration settings.", "title": "Configuration" - }, + }, { - "location": "/user-guide/configuration/#introduction", - "text": "Project settings are always configured by using a YAML configuration file in the\nproject directory named mkdocs.yml . As a minimum this configuration file must contain the site_name setting. All\nother settings are optional.", + "location": "/user-guide/configuration/#introduction", + "text": "Project settings are always configured by using a YAML configuration file in the\nproject directory named mkdocs.yml . As a minimum this configuration file must contain the site_name setting. All\nother settings are optional.", "title": "Introduction" - }, + }, { - "location": "/user-guide/configuration/#project-information", - "text": "", + "location": "/user-guide/configuration/#project-information", + "text": "", "title": "Project information" - }, + }, { - "location": "/user-guide/configuration/#site_name", - "text": "This is a required setting , and should be a string that is used as the main\ntitle for the project documentation. For example: site_name: Marshmallow Generator When rendering the theme this setting will be passed as the site_name context\nvariable.", + "location": "/user-guide/configuration/#site_name", + "text": "This is a required setting , and should be a string that is used as the main\ntitle for the project documentation. For example: site_name: Marshmallow Generator When rendering the theme this setting will be passed as the site_name context\nvariable.", "title": "site_name" - }, + }, { - "location": "/user-guide/configuration/#site_url", - "text": "Set the canonical URL of the site. This will add a link tag with the canonical\nURL to the generated HTML header. default : null", + "location": "/user-guide/configuration/#site_url", + "text": "Set the canonical URL of the site. This will add a link tag with the canonical\nURL to the generated HTML header. default : null", "title": "site_url" - }, + }, { - "location": "/user-guide/configuration/#repo_url", - "text": "When set, provides a link to your GitHub or Bitbucket repository on each page. repo_url: https://github.com/example/repository/ default : null", + "location": "/user-guide/configuration/#repo_url", + "text": "When set, provides a link to your GitHub or Bitbucket repository on each page. repo_url: https://github.com/example/repository/ default : null", "title": "repo_url" - }, + }, { - "location": "/user-guide/configuration/#repo_name", - "text": "When set, provides a link to your GitHub or Bitbucket repository on each page. default : 'GitHub' or 'Bitbucket' if the repo_url matches those\ndomains, otherwise null", + "location": "/user-guide/configuration/#repo_name", + "text": "When set, provides a link to your GitHub or Bitbucket repository on each page. default : 'GitHub' or 'Bitbucket' if the repo_url matches those\ndomains, otherwise null", "title": "repo_name" - }, + }, { - "location": "/user-guide/configuration/#edit_uri", - "text": "Path from the base repo_url to the docs directory when directly viewing a\npage, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,\netc), the branch, and the docs directory itself. Mkdocs concatenates repo_url \nand edit_uri , and appends the input path of the page. When set, provides a link directly to the page in your source repository. This\nmakes it easier to find and edit the source for the page. If repo_url is not\nset, this option is ignored. For example, for a GitHub-hosted repository, the edit_uri would be as follows.\n(Note the edit path and master branch...) edit_uri: edit/master/docs/ For a Bitbucket-hosted repository, the equivalent edit_uri would be as\nfollows. (Note the src path and default branch...) edit_uri: src/default/docs/ For other repository hosts, edit_uri works the same way. Simply specify the\nrelative path to the docs directory. default : edit/master/docs/ or src/default/docs/ for GitHub or Bitbucket\nrepos, respectively, if repo_url matches those domains, otherwise null Note: On GitHub, the edit path opens the page in the online GitHub editor. This\nfunctionality requires that the user have and be logged in to a GitHub\naccount. Otherwise, the user will be redirected to a login/signup page.\nAlternatively, use the blob path to open a read-only view, which supports\nanonymous access. E.g. blob/master/docs/", + "location": "/user-guide/configuration/#edit_uri", + "text": "Path from the base repo_url to the docs directory when directly viewing a\npage, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,\netc), the branch, and the docs directory itself. Mkdocs concatenates repo_url \nand edit_uri , and appends the input path of the page. When set, provides a link directly to the page in your source repository. This\nmakes it easier to find and edit the source for the page. If repo_url is not\nset, this option is ignored. For example, for a GitHub-hosted repository, the edit_uri would be as follows.\n(Note the edit path and master branch...) edit_uri: edit/master/docs/ For a Bitbucket-hosted repository, the equivalent edit_uri would be as\nfollows. (Note the src path and default branch...) edit_uri: src/default/docs/ For other repository hosts, edit_uri works the same way. Simply specify the\nrelative path to the docs directory. default : edit/master/docs/ or src/default/docs/ for GitHub or Bitbucket\nrepos, respectively, if repo_url matches those domains, otherwise null Note: On GitHub, the edit path opens the page in the online GitHub editor. This\nfunctionality requires that the user have and be logged in to a GitHub\naccount. Otherwise, the user will be redirected to a login/signup page.\nAlternatively, use the blob path to open a read-only view, which supports\nanonymous access. E.g. blob/master/docs/", "title": "edit_uri" - }, + }, { - "location": "/user-guide/configuration/#site_description", - "text": "Set the site description. This will add a meta tag to the generated HTML header. default : null", + "location": "/user-guide/configuration/#site_description", + "text": "Set the site description. This will add a meta tag to the generated HTML header. default : null", "title": "site_description" - }, + }, { - "location": "/user-guide/configuration/#site_author", - "text": "Set the name of the author. This will add a meta tag to the generated HTML\nheader. default : null", + "location": "/user-guide/configuration/#site_author", + "text": "Set the name of the author. This will add a meta tag to the generated HTML\nheader. default : null", "title": "site_author" - }, + }, { - "location": "/user-guide/configuration/#copyright", - "text": "Set the copyright information to be included in the documentation by the theme. default : null", + "location": "/user-guide/configuration/#copyright", + "text": "Set the copyright information to be included in the documentation by the theme. default : null", "title": "copyright" - }, + }, { - "location": "/user-guide/configuration/#google_analytics", - "text": "Set the Google analytics tracking configuration. google_analytics: ['UA-36723568-3', 'mkdocs.org'] default : null", + "location": "/user-guide/configuration/#google_analytics", + "text": "Set the Google analytics tracking configuration. google_analytics: ['UA-36723568-3', 'mkdocs.org'] default : null", "title": "google_analytics" - }, + }, { - "location": "/user-guide/configuration/#remote_branch", - "text": "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 . default : gh-pages", + "location": "/user-guide/configuration/#remote_branch", + "text": "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 . default : gh-pages", "title": "remote_branch" - }, + }, { - "location": "/user-guide/configuration/#remote_name", - "text": "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 . default : gh-pages", + "location": "/user-guide/configuration/#remote_name", + "text": "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 . default : origin", "title": "remote_name" - }, + }, { - "location": "/user-guide/configuration/#documentation-layout", - "text": "", + "location": "/user-guide/configuration/#documentation-layout", + "text": "", "title": "Documentation layout" - }, + }, { - "location": "/user-guide/configuration/#pages", - "text": "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 about.md , respectively. pages:\n - 'Introduction': 'index.md'\n - 'User Guide': 'user-guide.md'\n - 'About': 'about.md' See the section on configuring pages and navigation for a more detailed\nbreakdown, including how to create sub-sections. default : By default pages will contain an alphanumerically sorted, nested\nlist of all the Markdown files found within the docs_dir and its\nsub-directories. If none are found it will be [] (an empty list).", + "location": "/user-guide/configuration/#pages", + "text": "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 about.md , respectively. pages:\n - 'Introduction': 'index.md'\n - 'User Guide': 'user-guide.md'\n - 'About': 'about.md' See the section on configuring pages and navigation for a more detailed\nbreakdown, including how to create sub-sections. default : By default pages will contain an alphanumerically sorted, nested\nlist of all the Markdown files found within the docs_dir and its\nsub-directories. If none are found it will be [] (an empty list).", "title": "pages" - }, + }, { - "location": "/user-guide/configuration/#build-directories", - "text": "", + "location": "/user-guide/configuration/#build-directories", + "text": "", "title": "Build directories" - }, + }, { - "location": "/user-guide/configuration/#theme", - "text": "Sets the theme of your documentation site, for a list of available themes visit styling your docs . default : 'mkdocs'", + "location": "/user-guide/configuration/#theme", + "text": "Sets the theme of your documentation site, for a list of available themes visit styling your docs . default : 'mkdocs'", "title": "theme" - }, + }, { - "location": "/user-guide/configuration/#theme_dir", - "text": "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. See styling your docs for details if you would like to tweak an\nexisting theme. See custom themes if you would like to build your own theme from the ground\nup. default : null", + "location": "/user-guide/configuration/#theme_dir", + "text": "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. See styling your docs for details if you would like to tweak an\nexisting theme. See custom themes if you would like to build your own theme from the ground\nup. default : null", "title": "theme_dir" - }, + }, { - "location": "/user-guide/configuration/#docs_dir", - "text": "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. default : 'docs'", + "location": "/user-guide/configuration/#docs_dir", + "text": "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. default : 'docs'", "title": "docs_dir" - }, + }, { - "location": "/user-guide/configuration/#site_dir", - "text": "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. default : 'site' Note: 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: site/ If you're using another source code control tool, you'll want to check its\ndocumentation on how to ignore specific directories.", + "location": "/user-guide/configuration/#site_dir", + "text": "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. default : 'site' Note: 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: site/ If you're using another source code control tool, you'll want to check its\ndocumentation on how to ignore specific directories.", "title": "site_dir" - }, + }, { - "location": "/user-guide/configuration/#extra_css", - "text": "Set a list of CSS files in your docs_dir to be included by the theme. For\nexample, the following example will include the the extra.css file within the\ncss subdirectory in your docs_dir . extra_css:\n - css/extra.css\n - css/second_extra.css default : [] (an empty list).", + "location": "/user-guide/configuration/#extra_css", + "text": "Set a list of CSS files in your docs_dir to be included by the theme. For\nexample, the following example will include the the extra.css file within the\ncss subdirectory in your docs_dir . extra_css:\n - css/extra.css\n - css/second_extra.css default : [] (an empty list).", "title": "extra_css" - }, + }, { - "location": "/user-guide/configuration/#extra_javascript", - "text": "Set a list of JavaScript files in your docs_dir to be included by the theme.\nSee the example in extra_css for usage. default : [] (an empty list).", + "location": "/user-guide/configuration/#extra_javascript", + "text": "Set a list of JavaScript files in your docs_dir to be included by the theme.\nSee the example in extra_css for usage. default : [] (an empty list).", "title": "extra_javascript" - }, + }, { - "location": "/user-guide/configuration/#extra_templates", - "text": "Set a list of templates in your docs_dir to be built by MkDocs. To see more\nabout writing templates for MkDocs read the documentation about custom themes \nand specifically the section about the variables that are available to\ntemplates. See the example in extra_css for usage. default : [] (an empty list).", + "location": "/user-guide/configuration/#extra_templates", + "text": "Set a list of templates in your docs_dir to be built by MkDocs. To see more\nabout writing templates for MkDocs read the documentation about custom themes \nand specifically the section about the variables that are available to\ntemplates. See the example in extra_css for usage. default : [] (an empty list).", "title": "extra_templates" - }, + }, { - "location": "/user-guide/configuration/#extra", - "text": "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. For example, if you are using a theme that supports displaying the project\nversion, you can pass it to the theme like this: extra:\n version: 1.0 default : By default extra will be an empty key value mapping.", + "location": "/user-guide/configuration/#extra", + "text": "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. For example, if you are using a theme that supports displaying the project\nversion, you can pass it to the theme like this: extra:\n version: 1.0 default : By default extra will be an empty key value mapping.", "title": "extra" - }, + }, { - "location": "/user-guide/configuration/#preview-controls", - "text": "", + "location": "/user-guide/configuration/#preview-controls", + "text": "", "title": "Preview controls" - }, + }, { - "location": "/user-guide/configuration/#use_directory_urls", - "text": "This setting controls the style used for linking to pages within the\ndocumentation. The following table demonstrates how the URLs used on the site differ when\nsetting 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,\nand is usually what you'll want to use. 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 directory . default : true", + "location": "/user-guide/configuration/#use_directory_urls", + "text": "This setting controls the style used for linking to pages within the\ndocumentation. The following table demonstrates how the URLs used on the site differ when\nsetting 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,\nand is usually what you'll want to use. 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 directory . default : true", "title": "use_directory_urls" - }, + }, { - "location": "/user-guide/configuration/#strict", - "text": "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. default : false", + "location": "/user-guide/configuration/#strict", + "text": "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. default : false", "title": "strict" - }, + }, { - "location": "/user-guide/configuration/#dev_addr", - "text": "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. As with all settings, you can set this from the command line, which can be\nuseful, for example: mkdocs serve --dev-addr=0.0.0.0:80 # Run on port 80, on the local network. default : '127.0.0.1:8000'", + "location": "/user-guide/configuration/#dev_addr", + "text": "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. As with all settings, you can set this from the command line, which can be\nuseful, for example: mkdocs serve --dev-addr=0.0.0.0:80 # Run on port 80, on the local network. default : '127.0.0.1:8000'", "title": "dev_addr" - }, + }, { - "location": "/user-guide/configuration/#formatting-options", - "text": "", + "location": "/user-guide/configuration/#formatting-options", + "text": "", "title": "Formatting options" - }, + }, { - "location": "/user-guide/configuration/#markdown_extensions", - "text": "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 ). For example, to enable the SmartyPants typography extension , use: markdown_extensions:\n - smarty 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. For example, to enable permalinks in the (included) toc extension, use: markdown_extensions:\n - toc:\n permalink: True 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: markdown_extensions:\n - toc:\n permalink: True\n separator: _ 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: markdown_extensions:\n - smarty\n - toc:\n permalink: True\n - sane_lists See Also: 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. You may also install and use various third party extensions . Consult\nthe documentation provided by those extensions for installation instructions\nand available configuration options. default : []", + "location": "/user-guide/configuration/#markdown_extensions", + "text": "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 ). For example, to enable the SmartyPants typography extension , use: markdown_extensions:\n - smarty 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. For example, to enable permalinks in the (included) toc extension, use: markdown_extensions:\n - toc:\n permalink: True 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: markdown_extensions:\n - toc:\n permalink: True\n separator: \"_\" 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: markdown_extensions:\n - smarty\n - toc:\n permalink: True\n - sane_lists See Also: 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. You may also install and use various third party extensions . Consult\nthe documentation provided by those extensions for installation instructions\nand available configuration options. default : []", "title": "markdown_extensions" - }, + }, { - "location": "/user-guide/deploying-your-docs/", - "text": "Deploying your docs\n\uf0c1\n\n\nA basic guide to deploying your docs to various hosting providers\n\n\n\n\nGitHub Pages\n\uf0c1\n\n\nIf you host the source code for a project on \nGitHub\n, you can easily use\n\nGitHub Pages\n to host the documentation for your project. After you \ncheckout\n\nthe primary working branch (usually \nmaster\n) of the git repository where you\nmaintain the source documentation for your project, run the following command:\n\n\nmkdocs gh-deploy\n\n\n\n\nThat's it! Behind the scenes, MkDocs will build your docs and use the \nghp-import\n\ntool to commit them to the gh-pages branch and push the gh-pages branch to\nGitHub.\n\n\nUse \nmkdocs gh-deploy --help\n to get a full list of options available for the\n\ngh-deploy\n command.\n\n\nBe 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 \nbuild\n or \nserve\n commands and reviewing the built\nfiles locally.\n\n\n\n\nWarning\n\n\nYou should never edit files in your gh-pages branch by hand if you're using\nthe \ngh-deploy\n command because you will lose your work.\n\n\n\n\nRead the Docs\n\uf0c1\n\n\nRead the Docs\n 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\n\ninstructions\n 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\n\n\nNote\n\n\nTo benefit from all of the \nfeatures\n offered by Read the Docs, you will need\nto use the \nRead the Docs theme\n 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\n\n\nPyPI\n\uf0c1\n\n\nIf you maintain a \nPython\n project which is hosted on the \nPython Package\nIndex\n (PyPI), you can use the hosting provided at \npythonhosted.org\n to\nhost documentation for your project. Run the following commands from your\nproject's root directory to upload your documentation:\n\n\nmkdocs build\npython setup.py upload_docs --upload-dir=site\n\n\n\n\nYour documentation will be hosted at \nhttps://pythonhosted.org/\nprojectname\n/\n\nwhere \nprojectname\n is the name you used to register your project with PyPI.\n\n\nThere are a few prerequisites for the above to work:\n\n\n\n\nYou must be using \nSetuptools\n in your \nsetup.py\n script (\nDistutils\n does\n not offer an \nupload_docs\n command).\n\n\nYour project must already be registered with PyPI (use \npython setup.py\n register\n).\n\n\nYour \nmkdocs.yml\n config file and your \"docs\" directory (value assigned to\n the \ndocs_dir\n configuration option) are presumed to be in the root directory\n of your project alongside your \nsetup.py\n script.\n\n\nIt is assumed that the default value (\n\"site\"\n) is assigned to the \nsite_dir\n\n configuration option in your \nmkdocs.yaml\n config file. If you have set a\n different value, assign that value to the \n--upload-dir\n option.\n\n\n\n\nOther Providers\n\uf0c1\n\n\nAny 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\n\nWhen you build your site (using the \nmkdocs build\n command), all of the files\nare written to the directory assigned to the \nsite_dir\n configuration option\n(defaults to \n\"site\"\n) in your \nmkdocs.yaml\n 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 \nftp\n, \nssh\n or \nscp\n client to transfer\nthe files.\n\n\nFor example, a typical set of commands from the command line might look\nsomething like this:\n\n\nmkdocs build\nscp -r ./site user@host:/path/to/server/root\n\n\n\n\nOf course, you will need to replace \nuser\n with the username you have with your\nhosting provider and \nhost\n with the appropriate domain name. Additionally, you\nwill need to adjust the \n/path/to/server/root\n to match the configuration of\nyour hosts' file system.\n\n\nSee your host's documentation for specifics. You will likely want to search\ntheir documentation for \"ftp\" or \"uploading site\".\n\n\n404 Pages\n\uf0c1\n\n\nWhen MkDocs builds the documentation it will include a 404.html file in the\n\nbuild directory\n. This file will be automatically used when\ndeploying to \nGitHub\n but only on a custom domain. Other web\nservers may be configured to use it but the feature won't always be available.\nSee the documentation for your server of choice for more information.", + "location": "/user-guide/deploying-your-docs/", + "text": "Deploying your docs\n\uf0c1\n\n\nA basic guide to deploying your docs to various hosting providers\n\n\n\n\nGitHub Pages\n\uf0c1\n\n\nIf you host the source code for a project on \nGitHub\n, you can easily use\n\nGitHub Pages\n to host the documentation for your project. After you \ncheckout\n\nthe primary working branch (usually \nmaster\n) of the git repository where you\nmaintain the source documentation for your project, run the following command:\n\n\nmkdocs gh-deploy\n\n\n\n\nThat's it! Behind the scenes, MkDocs will build your docs and use the \nghp-import\n\ntool to commit them to the gh-pages branch and push the gh-pages branch to\nGitHub.\n\n\nUse \nmkdocs gh-deploy --help\n to get a full list of options available for the\n\ngh-deploy\n command.\n\n\nBe 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 \nbuild\n or \nserve\n commands and reviewing the built\nfiles locally.\n\n\n\n\nWarning\n\n\nYou should never edit files in your gh-pages branch by hand if you're using\nthe \ngh-deploy\n command because you will lose your work.\n\n\n\n\nRead the Docs\n\uf0c1\n\n\nRead the Docs\n 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\n\ninstructions\n 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\n\n\nNote\n\n\nTo benefit from all of the \nfeatures\n offered by Read the Docs, you will need\nto use the \nRead the Docs theme\n 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\n\n\nPyPI\n\uf0c1\n\n\nIf you maintain a \nPython\n project which is hosted on the \nPython Package\nIndex\n (PyPI), you can use the hosting provided at \npythonhosted.org\n to\nhost documentation for your project. Run the following commands from your\nproject's root directory to upload your documentation:\n\n\nmkdocs build\npython setup.py upload_docs --upload-dir=site\n\n\n\n\nYour documentation will be hosted at \nhttps://pythonhosted.org//\n\nwhere \n\n is the name you used to register your project with PyPI.\n\n\nThere are a few prerequisites for the above to work:\n\n\n\n\nYou must be using \nSetuptools\n in your \nsetup.py\n script (\nDistutils\n does\n not offer an \nupload_docs\n command).\n\n\nYour project must already be registered with PyPI (use \npython setup.py\n register\n).\n\n\nYour \nmkdocs.yml\n config file and your \"docs\" directory (value assigned to\n the \ndocs_dir\n configuration option) are presumed to be in the root directory\n of your project alongside your \nsetup.py\n script.\n\n\nIt is assumed that the default value (\n\"site\"\n) is assigned to the \nsite_dir\n\n configuration option in your \nmkdocs.yaml\n config file. If you have set a\n different value, assign that value to the \n--upload-dir\n option.\n\n\n\n\nOther Providers\n\uf0c1\n\n\nAny 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\n\nWhen you build your site (using the \nmkdocs build\n command), all of the files\nare written to the directory assigned to the \nsite_dir\n configuration option\n(defaults to \n\"site\"\n) in your \nmkdocs.yaml\n 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 \nftp\n, \nssh\n or \nscp\n client to transfer\nthe files.\n\n\nFor example, a typical set of commands from the command line might look\nsomething like this:\n\n\nmkdocs build\nscp -r ./site user@host:/path/to/server/root\n\n\n\n\nOf course, you will need to replace \nuser\n with the username you have with your\nhosting provider and \nhost\n with the appropriate domain name. Additionally, you\nwill need to adjust the \n/path/to/server/root\n to match the configuration of\nyour hosts' file system.\n\n\nSee your host's documentation for specifics. You will likely want to search\ntheir documentation for \"ftp\" or \"uploading site\".\n\n\n404 Pages\n\uf0c1\n\n\nWhen MkDocs builds the documentation it will include a 404.html file in the\n\nbuild directory\n. This file will be automatically used when\ndeploying to \nGitHub\n but only on a custom domain. Other web\nservers may be configured to use it but the feature won't always be available.\nSee the documentation for your server of choice for more information.", "title": "Deploying Your Docs" - }, + }, { - "location": "/user-guide/deploying-your-docs/#deploying-your-docs", - "text": "A basic guide to deploying your docs to various hosting providers", + "location": "/user-guide/deploying-your-docs/#deploying-your-docs", + "text": "A basic guide to deploying your docs to various hosting providers", "title": "Deploying your docs" - }, + }, { - "location": "/user-guide/deploying-your-docs/#github-pages", - "text": "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 \nthe primary working branch (usually master ) of the git repository where you\nmaintain the source documentation for your project, run the following command: mkdocs gh-deploy 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. 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\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. Warning 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.", + "location": "/user-guide/deploying-your-docs/#github-pages", + "text": "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 \nthe primary working branch (usually master ) of the git repository where you\nmaintain the source documentation for your project, run the following command: mkdocs gh-deploy 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. 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\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. Warning 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.", "title": "GitHub Pages" - }, + }, { - "location": "/user-guide/deploying-your-docs/#read-the-docs", - "text": "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 instructions 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. Note 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.", + "location": "/user-guide/deploying-your-docs/#read-the-docs", + "text": "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 instructions 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. Note 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.", "title": "Read the Docs" - }, + }, { - "location": "/user-guide/deploying-your-docs/#pypi", - "text": "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: mkdocs build\npython setup.py upload_docs --upload-dir=site Your documentation will be hosted at https://pythonhosted.org/ projectname / \nwhere projectname is the name you used to register your project with PyPI. There are a few prerequisites for the above to work: You must be using Setuptools in your setup.py script ( Distutils does\n not offer an upload_docs command). Your project must already be registered with PyPI (use python setup.py\n register ). 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. 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.", + "location": "/user-guide/deploying-your-docs/#pypi", + "text": "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: mkdocs build\npython setup.py upload_docs --upload-dir=site Your documentation will be hosted at https://pythonhosted.org// \nwhere is the name you used to register your project with PyPI. There are a few prerequisites for the above to work: You must be using Setuptools in your setup.py script ( Distutils does\n not offer an upload_docs command). Your project must already be registered with PyPI (use python setup.py\n register ). 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. 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.", "title": "PyPI" - }, + }, { - "location": "/user-guide/deploying-your-docs/#other-providers", - "text": "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. 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. For example, a typical set of commands from the command line might look\nsomething like this: mkdocs build\nscp -r ./site user@host:/path/to/server/root 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. See your host's documentation for specifics. You will likely want to search\ntheir documentation for \"ftp\" or \"uploading site\".", + "location": "/user-guide/deploying-your-docs/#other-providers", + "text": "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. 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. For example, a typical set of commands from the command line might look\nsomething like this: mkdocs build\nscp -r ./site user@host:/path/to/server/root 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. See your host's documentation for specifics. You will likely want to search\ntheir documentation for \"ftp\" or \"uploading site\".", "title": "Other Providers" - }, + }, { - "location": "/user-guide/deploying-your-docs/#404-pages", - "text": "When MkDocs builds the documentation it will include a 404.html file in the build directory . This file will be automatically used when\ndeploying to GitHub but only on a custom domain. Other web\nservers may be configured to use it but the feature won't always be available.\nSee the documentation for your server of choice for more information.", + "location": "/user-guide/deploying-your-docs/#404-pages", + "text": "When MkDocs builds the documentation it will include a 404.html file in the build directory . This file will be automatically used when\ndeploying to GitHub but only on a custom domain. Other web\nservers may be configured to use it but the feature won't always be available.\nSee the documentation for your server of choice for more information.", "title": "404 Pages" - }, + }, { - "location": "/user-guide/custom-themes/", - "text": "Custom themes\n\uf0c1\n\n\nA guide to creating and distributing custom themes.\n\n\n\n\n\n\nNote\n\n\nIf you are looking for third party themes, they are listed in the MkDocs\n\ncommunity wiki\n. If\nyou want to share a theme you create, you should list it on the Wiki.\n\n\n\n\nWhen creating a new theme, you can either follow the steps in this guide to\ncreate one from scratch or you can download the \nmkdocs-basic-theme\n as a\nbasic, yet complete, theme with all the boilerplate required. \nYou can find\nthis base theme on \nGitHub\n.\nIt contains detailed comments in the code to describe the different features\nand their usage.\n\n\nCreating a custom theme\n\uf0c1\n\n\nThe bare minimum required for a custom theme is a \nmain.html\n \nJinja2\ntemplate\n file. This should be placed in a directory which will be the\n\ntheme_dir\n and it should be created next to the \nmkdocs.yml\n configuration\nfile. Within \nmkdocs.yml\n, specify the \ntheme_dir\n option and set it to the\nname of the directory containing \nmain.html\n. For example, given this example\nproject layout:\n\n\nmkdocs.yml\ndocs/\n index.md\n about.md\ncustom_theme/\n main.html\n ...\n\n\n\nYou would include the following settings in \nmkdocs.yml\n to use the custom theme\ndirectory:\n\n\ntheme: null\ntheme_dir: 'custom_theme'\n\n\n\n\n\nNote\n\n\nGenerally, when building your own custom theme, the \ntheme\n configuration\nsetting would be set to \nnull\n. However, if used in combination with the\n\ntheme_dir\n configuration value a custom theme can be used to replace only\nspecific parts of a built-in theme. For example, with the above layout and\nif you set \ntheme: \"mkdocs\"\n then the \nmain.html\n file in the \ntheme_dir\n\nwould replace that in the theme but otherwise the \nmkdocs\n theme would\nremain the same. This is useful if you want to make small adjustments to an\nexisting theme.\n\n\nFor more specific information, see \nstyling your docs\n.\n\n\n\n\nBasic theme\n\uf0c1\n\n\nThe simplest \nmain.html\n file is the following:\n\n\n!DOCTYPE html\n\n\nhtml\n\n \nhead\n\n \ntitle\n{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}\n/title\n\n \n/head\n\n \nbody\n\n {{ content }}\n \n/body\n\n\n/html\n\n\n\n\n\nArticle content from each page specified in \nmkdocs.yml\n is inserted using the\n\n{{ content }}\n tag. Style-sheets 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 \nnav\n and \ntoc\n objects, respectively.\nIf you wish to write your own theme, it is recommended to start with one of\nthe \nbuilt-in themes\n and modify it accordingly.\n\n\n\n\nNote\n\n\nAs MkDocs uses \nJinja\n as its template engine, you have access to all the\npower of Jinja, including \ntemplate inheritance\n. You may notice that the\nthemes included with MkDocs make extensive use of template inheritance and\nblocks, allowing users to easily override small bits and pieces of the\ntemplates from the \ntheme_dir\n. Therefore, the built-in themes are\nimplemented in a \nbase.html\n file, which \nmain.html\n extends. Although not\nrequired, third party template authors are encouraged to follow a similar\npattern and may want to define the same \nblocks\n as are used in the built-in\nthemes for consistency.\n\n\n\n\nTemplate Variables\n\uf0c1\n\n\nEach 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\n\nGlobal Context\n\uf0c1\n\n\nThe following variables are available globally on any template.\n\n\nconfig\n\uf0c1\n\n\nThe \nconfig\n variable is an instance of MkDocs' config object generated from the\n\nmkdocs.yml\n config file. While you can use any config option, some commonly\nused options include:\n\n\n\n\nconfig.site_name\n\n\nconfig.site_url\n\n\nconfig.site_author\n\n\nconfig.site_description\n\n\nconfig.repo_url\n\n\nconfig.repo_name\n\n\nconfig.copyright\n\n\nconfig.google_analytics\n\n\n\n\nnav\n\uf0c1\n\n\nThe \nnav\n 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\n\n{% if nav|length\n1 %}\n \nul\n\n {% for nav_item in nav %}\n {% if nav_item.children %}\n \nli\n{{ nav_item.title }}\n \nul\n\n {% for nav_item in nav_item.children %}\n \nli class=\n{% if nav_item.active%}current{%endif%}\n\n \na href=\n{{ nav_item.url }}\n{{ nav_item.title }}\n/a\n\n \n/li\n\n {% endfor %}\n \n/ul\n\n \n/li\n\n {% else %}\n \nli class=\n{% if nav_item.active%}current{%endif%}\n\n \na href=\n{{ nav_item.url }}\n{{ nav_item.title }}\n/a\n\n \n/li\n\n {% endif %}\n {% endfor %}\n \n/ul\n\n{% endif %}\n\n\n\n\nThe \nnav\n object also contains a \nhompage\n object, which points to the \npage\n\nobject of the homepage. For example, you may want to access \nnav.homepage.url\n.\n\n\nbase_url\n\uf0c1\n\n\nThe \nbase_url\n 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 \njs\n folder, to include \ntheme.js\n from that\nfolder on all pages you would do this:\n\n\nscript src=\n{{ base_url }}/js/theme.js\n/script\n\n\n\n\n\nextra_css\n\uf0c1\n\n\nContains a list of URLs to the style-sheets listed in the \nextra_css\n\nconfig setting. Unlike the config setting, which contains local paths, this\nvariable contains absolute paths from the homepage.\n\n\nextra_javascript\n\uf0c1\n\n\nContains a list of URLs to the scripts listed in the \nextra_javascript\n config\nsetting. Unlike the config setting, which contains local paths, this variable\ncontains absolute paths from the homepage.\n\n\nmkdocs_version\n\uf0c1\n\n\nContains the current MkDocs version.\n\n\nbuild_date_utc\n\uf0c1\n\n\nA 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\n\npage\n\uf0c1\n\n\nIn templates which are not rendered from a Markdown source file, the \npage\n\nvariable is \nNone\n. In templates which are rendered from a Markdown source file,\nthe \npage\n variable contains a page object with the following attributes:\n\n\npage.title\n\uf0c1\n\n\nContains the Title for the current page.\n\n\npage.content\n\uf0c1\n\n\nThe rendered Markdown as HTML, this is the contents of the documentation.\n\n\npage.toc\n\uf0c1\n\n\nAn object representing the Table of contents for a page. Displaying the table\nof contents as a simple list can be achieved like this.\n\n\nul\n\n{% for toc_item in page.toc %}\n \nli\na href=\n{{ toc_item.url }}\n{{ toc_item.title }}\n/a\n/li\n\n {% for toc_item in toc_item.children %}\n \nli\na href=\n{{ toc_item.url }}\n{{ toc_item.title }}\n/a\n/li\n\n {% endfor %}\n{% endfor %}\n\n/ul\n\n\n\n\n\npage.meta\n\uf0c1\n\n\nA mapping of the metadata included at the top of the markdown page. In this\nexample we define a \nsource\n property above the page title.\n\n\nsource: generics.py\n mixins.py\n\n# Page title\n\nContent...\n\n\n\n\nA template can access this metadata for the page with the \nmeta.source\n\nvariable. This could then be used to link to source files related to the\ndocumentation page.\n\n\n{% for filename in page.meta.source %}\n \na class=\ngithub\n href=\nhttps://github.com/.../{{ filename }}\n\n \nspan class=\nlabel label-info\n{{ filename }}\n/span\n\n \n/a\n\n{% endfor %}\n\n\n\n\npage.canonical_url\n\uf0c1\n\n\nThe full, canonical URL to the current page. This includes the \nsite_url\n from\nthe configuration.\n\n\npage.edit_url\n\uf0c1\n\n\nThe full URL to the input page in the source repository. Typically used to\nprovide a link to edit the source page.\n\n\npage.url\n\uf0c1\n\n\nThe URL to the current page not including the \nsite_url\n from the configuration.\n\n\npage.is_homepage\n\uf0c1\n\n\nEvaluates to \nTrue\n for the homepage of the site and \nFalse\n for all other\npages. This can be used in conjunction with other attributes of the \npage\n\nobject to alter the behavior. For example, to display a different title\non the homepage:\n\n\n{% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}\n\n\n\n\npage.previous_page\n\uf0c1\n\n\nThe page object for the previous page. The usage is the same as for\n\npage\n.\n\n\npage.next_page\n\uf0c1\n\n\nThe page object for the next page.The usage is the same as for \npage\n.\n\n\nExtra Context\n\uf0c1\n\n\nAdditional variables can be passed to the template with the\n\nextra\n configuration option. This is a\nset of key value pairs that can make custom templates far more flexible.\n\n\nFor 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 \nextra\n configuration:\n\n\nextra:\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\n\nAnd then displayed with this HTML in the custom theme.\n\n\n{{ config.extra.version }}\n\n{% if config.extra.links %}\n \nul\n\n {% for link in config.extra.links %}\n \nli\n{{ link }}\n/li\n\n {% endfor %}\n \n/ul\n\n{% endif %}\n\n\n\n\nSearch and themes\n\uf0c1\n\n\nAs of MkDocs \n0.13\n client side search support has been added to MkDocs with\n\nLunr.js\n.\n\n\nSearch can either be added to every page in the theme or to a dedicated\ntemplate which must be named \nsearch.html\n. The search template will be build\nwith the same name and can be viewable with \nmkdocs serve\n at\n\nhttp://localhost:8000/search.html\n. An example of the two different\napproaches can be seen by comparing the \nmkdocs\n and \nreadthedocs\n themes.\n\n\nThe following HTML needs to be added to the theme so the JavaScript is loaded\nfor Lunr.js.\n\n\nscript\nvar base_url = '{{ base_url }}';\n/script\n\n\nscript data-main=\n{{ base_url }}/mkdocs/js/search.js\n src=\n{{ base_url }}/mkdocs/js/require.js\n/script\n\n\n\n\n\n\n\nNote\n\n\nThe 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 \nsearch.html\n approach to only\ninclude search on one page or load the JavaScript on an event like a form\nsubmit.\n\n\n\n\nThis loads the JavaScript and sets a global variable \nbase_url\n which allows\nthe JavaScript to make the links relative to the current page. The above\nJavaScript, with the following HTML in a \nsearch.html\n template will add a\nfull search implementation to your theme.\n\n\nh1 id=\nsearch\nSearch Results\n/h1\n\n\n\nform action=\nsearch.html\n\n \ninput name=\nq\n id=\nmkdocs-search-query\n type=\ntext\n \n\n\n/form\n\n\n\ndiv id=\nmkdocs-search-results\n\n Sorry, page not found.\n\n/div\n\n\n\n\n\nThis 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 \nmkdocs-search-query\n\nand \nmkdocs-search-results\n is the directory where the results will be placed.\n\n\nPackaging Themes\n\uf0c1\n\n\nMkDocs makes use of \nPython packaging\n to distribute themes. This comes with a\nfew requirements.\n\n\nTo see an example of a package containing one theme, see the \nMkDocs Bootstrap\ntheme\n and to see a package that contains many themes, see the \nMkDocs\nBootswatch theme\n.\n\n\n\n\nNote\n\n\nIt is not strictly necessary to package a theme, as the entire theme\ncan be contained in the \ntheme_dir\n. If you have created a \"one-off theme,\"\nthat should be sufficent. However, if you intend to distribute your theme\nfor others to use, packaging the theme has some advantages. By packaging\nyour theme, your users can more easily install it and they can them take\nadvantage of the \ntheme_dir\n to make tweaks to your theme to better suit\ntheir needs.\n\n\n\n\nPackage Layout\n\uf0c1\n\n\nThe following layout is recommended for themes. Two files at the top level\ndirectory called \nMANIFEST.in\n amd \nsetup.py\n beside the theme directory which\ncontains an empty \n__init__.py\n file and your template and media files.\n\n\n.\n|-- MANIFEST.in\n|-- theme_name\n| |-- __init__.py\n| |-- main.py\n| |-- styles.css\n`-- setup.py\n\n\n\n\nThe \nMANIFEST.in\n file should contain the following contents but with\ntheme_name updated and any extra file extensions added to the include.\n\n\nrecursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff\nrecursive-exclude * __pycache__\nrecursive-exclude * *.py[co]\n\n\n\n\nThe \nsetup.py\n should include the following text with the modifications\ndescribed below.\n\n\nfrom setuptools import setup, find_packages\n\nVERSION = '0.0.1'\n\n\nsetup(\n name=\nmkdocs-themename\n,\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\n\nFill in the URL, license, description, author and author email address.\n\n\nThe name should follow the convention \nmkdocs-themename\n (like \nmkdocs-\nbootstrap\n and \nmkdocs-bootswatch\n), starting with MkDocs, using hyphens to\nseparate words and including the name of your theme.\n\n\nMost 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\n\nThe directory you created at the start of this section with the main.html file\nshould contain all of the other theme files. The minimum requirement is that\nit includes a \nmain.html\n for the theme. It \nmust\n also include a\n\n__init__.py\n file which should be empty, this file tells Python that the\ndirectory is a package.\n\n\nDistributing Themes\n\uf0c1\n\n\nWith the above changes, your theme should now be ready to install. This can be\ndone with pip, using \npip install .\n if you are still in the same directory as\nthe setup.py.\n\n\nMost Python packages, including MkDocs, are distributed on PyPI. To do this,\nyou should run the following command.\n\n\npython setup.py register\n\n\n\n\nIf you don't have an account setup, you should be prompted to create one.\n\n\nFor a much more detailed guide, see the official Python packaging\ndocumentation for \nPackaging and Distributing Projects\n.", + "location": "/user-guide/custom-themes/", + "text": "Custom themes\n\uf0c1\n\n\nA guide to creating and distributing custom themes.\n\n\n\n\n\n\nNote\n\n\nIf you are looking for third party themes, they are listed in the MkDocs\n\ncommunity wiki\n. If\nyou want to share a theme you create, you should list it on the Wiki.\n\n\n\n\nWhen creating a new theme, you can either follow the steps in this guide to\ncreate one from scratch or you can download the \nmkdocs-basic-theme\n as a\nbasic, yet complete, theme with all the boilerplate required. \nYou can find\nthis base theme on \nGitHub\n.\nIt contains detailed comments in the code to describe the different features\nand their usage.\n\n\nCreating a custom theme\n\uf0c1\n\n\nThe bare minimum required for a custom theme is a \nmain.html\n \nJinja2\ntemplate\n file. This should be placed in a directory which will be the\n\ntheme_dir\n and it should be created next to the \nmkdocs.yml\n configuration\nfile. Within \nmkdocs.yml\n, specify the \ntheme_dir\n option and set it to the\nname of the directory containing \nmain.html\n. For example, given this example\nproject layout:\n\n\nmkdocs.yml\ndocs/\n index.md\n about.md\ncustom_theme/\n main.html\n ...\n\n\n\nYou would include the following settings in \nmkdocs.yml\n to use the custom theme\ndirectory:\n\n\ntheme: null\ntheme_dir: 'custom_theme'\n\n\n\n\n\nNote\n\n\nGenerally, when building your own custom theme, the \ntheme\n configuration\nsetting would be set to \nnull\n. However, if used in combination with the\n\ntheme_dir\n configuration value a custom theme can be used to replace only\nspecific parts of a built-in theme. For example, with the above layout and\nif you set \ntheme: \"mkdocs\"\n then the \nmain.html\n file in the \ntheme_dir\n\nwould replace that in the theme but otherwise the \nmkdocs\n theme would\nremain the same. This is useful if you want to make small adjustments to an\nexisting theme.\n\n\nFor more specific information, see \nstyling your docs\n.\n\n\n\n\nBasic theme\n\uf0c1\n\n\nThe simplest \nmain.html\n file is the following:\n\n\n\n\n \n {% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}\n \n \n {{ content }}\n \n\n\n\n\n\nArticle content from each page specified in \nmkdocs.yml\n is inserted using the\n\n{{ content }}\n tag. Style-sheets 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 \nnav\n and \ntoc\n objects, respectively.\nIf you wish to write your own theme, it is recommended to start with one of\nthe \nbuilt-in themes\n and modify it accordingly.\n\n\n\n\nNote\n\n\nAs MkDocs uses \nJinja\n as its template engine, you have access to all the\npower of Jinja, including \ntemplate inheritance\n. You may notice that the\nthemes included with MkDocs make extensive use of template inheritance and\nblocks, allowing users to easily override small bits and pieces of the\ntemplates from the \ntheme_dir\n. Therefore, the built-in themes are\nimplemented in a \nbase.html\n file, which \nmain.html\n extends. Although not\nrequired, third party template authors are encouraged to follow a similar\npattern and may want to define the same \nblocks\n as are used in the built-in\nthemes for consistency.\n\n\n\n\nTemplate Variables\n\uf0c1\n\n\nEach 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\n\nGlobal Context\n\uf0c1\n\n\nThe following variables are available globally on any template.\n\n\nconfig\n\uf0c1\n\n\nThe \nconfig\n variable is an instance of MkDocs' config object generated from the\n\nmkdocs.yml\n config file. While you can use any config option, some commonly\nused options include:\n\n\n\n\nconfig.site_name\n\n\nconfig.site_url\n\n\nconfig.site_author\n\n\nconfig.site_description\n\n\nconfig.repo_url\n\n\nconfig.repo_name\n\n\nconfig.copyright\n\n\nconfig.google_analytics\n\n\n\n\nnav\n\uf0c1\n\n\nThe \nnav\n 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\n\n{% if nav|length>1 %}\n
      \n {% for nav_item in nav %}\n {% if nav_item.children %}\n
    • {{ nav_item.title }}\n \n
      • \n {% else %}\n
    • \n {{ nav_item.title }}\n
      • \n {% endif %}\n {% endfor %}\n
    \n{% endif %}\n\n\n\n\nThe \nnav\n object also contains a \nhompage\n object, which points to the \npage\n\nobject of the homepage. For example, you may want to access \nnav.homepage.url\n.\n\n\nbase_url\n\uf0c1\n\n\nThe \nbase_url\n 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 \njs\n folder, to include \ntheme.js\n from that\nfolder on all pages you would do this:\n\n\n\n\n\n\n\nextra_css\n\uf0c1\n\n\nContains a list of URLs to the style-sheets listed in the \nextra_css\n\nconfig setting. Unlike the config setting, which contains local paths, this\nvariable contains absolute paths from the homepage.\n\n\nextra_javascript\n\uf0c1\n\n\nContains a list of URLs to the scripts listed in the \nextra_javascript\n config\nsetting. Unlike the config setting, which contains local paths, this variable\ncontains absolute paths from the homepage.\n\n\nmkdocs_version\n\uf0c1\n\n\nContains the current MkDocs version.\n\n\nbuild_date_utc\n\uf0c1\n\n\nA 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\n\npage\n\uf0c1\n\n\nIn templates which are not rendered from a Markdown source file, the \npage\n\nvariable is \nNone\n. In templates which are rendered from a Markdown source file,\nthe \npage\n variable contains a page object with the following attributes:\n\n\npage.title\n\uf0c1\n\n\nContains the Title for the current page.\n\n\npage.content\n\uf0c1\n\n\nThe rendered Markdown as HTML, this is the contents of the documentation.\n\n\npage.toc\n\uf0c1\n\n\nAn object representing the Table of contents for a page. Displaying the table\nof contents as a simple list can be achieved like this.\n\n\n\n\n\n\n\npage.meta\n\uf0c1\n\n\nA mapping of the metadata included at the top of the markdown page. In this\nexample we define a \nsource\n property above the page title.\n\n\nsource: generics.py\n mixins.py\n\n# Page title\n\nContent...\n\n\n\n\nA template can access this metadata for the page with the \nmeta.source\n\nvariable. This could then be used to link to source files related to the\ndocumentation page.\n\n\n{% for filename in page.meta.source %}\n \n {{ filename }}\n \n{% endfor %}\n\n\n\n\npage.canonical_url\n\uf0c1\n\n\nThe full, canonical URL to the current page. This includes the \nsite_url\n from\nthe configuration.\n\n\npage.edit_url\n\uf0c1\n\n\nThe full URL to the input page in the source repository. Typically used to\nprovide a link to edit the source page.\n\n\npage.url\n\uf0c1\n\n\nThe URL to the current page not including the \nsite_url\n from the configuration.\n\n\npage.is_homepage\n\uf0c1\n\n\nEvaluates to \nTrue\n for the homepage of the site and \nFalse\n for all other\npages. This can be used in conjunction with other attributes of the \npage\n\nobject to alter the behavior. For example, to display a different title\non the homepage:\n\n\n{% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}\n\n\n\n\npage.previous_page\n\uf0c1\n\n\nThe page object for the previous page. The usage is the same as for\n\npage\n.\n\n\npage.next_page\n\uf0c1\n\n\nThe page object for the next page.The usage is the same as for \npage\n.\n\n\nExtra Context\n\uf0c1\n\n\nAdditional variables can be passed to the template with the\n\nextra\n configuration option. This is a\nset of key value pairs that can make custom templates far more flexible.\n\n\nFor 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 \nextra\n configuration:\n\n\nextra:\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\n\nAnd then displayed with this HTML in the custom theme.\n\n\n{{ config.extra.version }}\n\n{% if config.extra.links %}\n
      \n {% for link in config.extra.links %}\n
    • {{ link }}
      • \n {% endfor %}\n
    \n{% endif %}\n\n\n\n\nSearch and themes\n\uf0c1\n\n\nAs of MkDocs \n0.13\n client side search support has been added to MkDocs with\n\nLunr.js\n.\n\n\nSearch can either be added to every page in the theme or to a dedicated\ntemplate which must be named \nsearch.html\n. The search template will be build\nwith the same name and can be viewable with \nmkdocs serve\n at\n\nhttp://localhost:8000/search.html\n. An example of the two different\napproaches can be seen by comparing the \nmkdocs\n and \nreadthedocs\n themes.\n\n\nThe following HTML needs to be added to the theme so the JavaScript is loaded\nfor Lunr.js.\n\n\n\n\n\n\n\n\n\n\nNote\n\n\nThe 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 \nsearch.html\n approach to only\ninclude search on one page or load the JavaScript on an event like a form\nsubmit.\n\n\n\n\nThis loads the JavaScript and sets a global variable \nbase_url\n which allows\nthe JavaScript to make the links relative to the current page. The above\nJavaScript, with the following HTML in a \nsearch.html\n template will add a\nfull search implementation to your theme.\n\n\n

    Search Results

    \n\n
    \n \n
    \n\n
    \n Sorry, page not found.\n
    \n\n\n\n\nThis 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 \nmkdocs-search-query\n\nand \nmkdocs-search-results\n is the directory where the results will be placed.\n\n\nPackaging Themes\n\uf0c1\n\n\nMkDocs makes use of \nPython packaging\n to distribute themes. This comes with a\nfew requirements.\n\n\nTo see an example of a package containing one theme, see the \nMkDocs Bootstrap\ntheme\n and to see a package that contains many themes, see the \nMkDocs\nBootswatch theme\n.\n\n\n\n\nNote\n\n\nIt is not strictly necessary to package a theme, as the entire theme\ncan be contained in the \ntheme_dir\n. If you have created a \"one-off theme,\"\nthat should be sufficent. However, if you intend to distribute your theme\nfor others to use, packaging the theme has some advantages. By packaging\nyour theme, your users can more easily install it and they can them take\nadvantage of the \ntheme_dir\n to make tweaks to your theme to better suit\ntheir needs.\n\n\n\n\nPackage Layout\n\uf0c1\n\n\nThe following layout is recommended for themes. Two files at the top level\ndirectory called \nMANIFEST.in\n amd \nsetup.py\n beside the theme directory which\ncontains an empty \n__init__.py\n file and your template and media files.\n\n\n.\n|-- MANIFEST.in\n|-- theme_name\n| |-- __init__.py\n| |-- main.py\n| |-- styles.css\n`-- setup.py\n\n\n\n\nThe \nMANIFEST.in\n file should contain the following contents but with\ntheme_name updated and any extra file extensions added to the include.\n\n\nrecursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff\nrecursive-exclude * __pycache__\nrecursive-exclude * *.py[co]\n\n\n\n\nThe \nsetup.py\n should include the following text with the modifications\ndescribed below.\n\n\nfrom 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\n\nFill in the URL, license, description, author and author email address.\n\n\nThe name should follow the convention \nmkdocs-themename\n (like \nmkdocs-\nbootstrap\n and \nmkdocs-bootswatch\n), starting with MkDocs, using hyphens to\nseparate words and including the name of your theme.\n\n\nMost 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\n\nThe directory you created at the start of this section with the main.html file\nshould contain all of the other theme files. The minimum requirement is that\nit includes a \nmain.html\n for the theme. It \nmust\n also include a\n\n__init__.py\n file which should be empty, this file tells Python that the\ndirectory is a package.\n\n\nDistributing Themes\n\uf0c1\n\n\nWith the above changes, your theme should now be ready to install. This can be\ndone with pip, using \npip install .\n if you are still in the same directory as\nthe setup.py.\n\n\nMost Python packages, including MkDocs, are distributed on PyPI. To do this,\nyou should run the following command.\n\n\npython setup.py register\n\n\n\n\nIf you don't have an account setup, you should be prompted to create one.\n\n\nFor a much more detailed guide, see the official Python packaging\ndocumentation for \nPackaging and Distributing Projects\n.", "title": "Custom Themes" - }, + }, { - "location": "/user-guide/custom-themes/#custom-themes", - "text": "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 . If\nyou 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\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.", + "location": "/user-guide/custom-themes/#custom-themes", + "text": "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 . If\nyou 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\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.", "title": "Custom themes" - }, + }, { - "location": "/user-guide/custom-themes/#creating-a-custom-theme", - "text": "The bare minimum required for a custom theme is a main.html Jinja2\ntemplate 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\nfile. Within mkdocs.yml , specify the theme_dir option and set it to the\nname of the directory containing main.html . For example, given this example\nproject layout: mkdocs.yml\ndocs/\n index.md\n about.md\ncustom_theme/\n main.html\n ... You would include the following settings in mkdocs.yml to use the custom theme\ndirectory: theme: null\ntheme_dir: 'custom_theme' Note Generally, when building your own custom theme, the theme configuration\nsetting 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\nspecific parts of a built-in theme. For example, with the above layout and\nif you set theme: \"mkdocs\" then the main.html file in the theme_dir \nwould replace that in the theme but otherwise the mkdocs theme would\nremain the same. This is useful if you want to make small adjustments to an\nexisting theme. For more specific information, see styling your docs .", + "location": "/user-guide/custom-themes/#creating-a-custom-theme", + "text": "The bare minimum required for a custom theme is a main.html Jinja2\ntemplate 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\nfile. Within mkdocs.yml , specify the theme_dir option and set it to the\nname of the directory containing main.html . For example, given this example\nproject layout: mkdocs.yml\ndocs/\n index.md\n about.md\ncustom_theme/\n main.html\n ... You would include the following settings in mkdocs.yml to use the custom theme\ndirectory: theme: null\ntheme_dir: 'custom_theme' Note Generally, when building your own custom theme, the theme configuration\nsetting 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\nspecific parts of a built-in theme. For example, with the above layout and\nif you set theme: \"mkdocs\" then the main.html file in the theme_dir \nwould replace that in the theme but otherwise the mkdocs theme would\nremain the same. This is useful if you want to make small adjustments to an\nexisting theme. For more specific information, see styling your docs .", "title": "Creating a custom theme" - }, + }, { - "location": "/user-guide/custom-themes/#basic-theme", - "text": "The simplest main.html file is the following: !DOCTYPE html html \n head \n title {% if page_title %}{{ page_title }} - {% endif %}{{ site_name }} /title \n /head \n body \n {{ content }}\n /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\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. Note As MkDocs uses Jinja as its template engine, you have access to all the\npower of Jinja, including template inheritance . You may notice that the\nthemes included with MkDocs make extensive use of template inheritance and\nblocks, allowing users to easily override small bits and pieces of the\ntemplates from the theme_dir . Therefore, the built-in themes are\nimplemented in a base.html file, which main.html extends. Although not\nrequired, third party template authors are encouraged to follow a similar\npattern and may want to define the same blocks as are used in the built-in\nthemes for consistency.", + "location": "/user-guide/custom-themes/#basic-theme", + "text": "The simplest main.html file is the following: \n\n \n {% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}\n \n \n {{ content }}\n \n 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\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. Note As MkDocs uses Jinja as its template engine, you have access to all the\npower of Jinja, including template inheritance . You may notice that the\nthemes included with MkDocs make extensive use of template inheritance and\nblocks, allowing users to easily override small bits and pieces of the\ntemplates from the theme_dir . Therefore, the built-in themes are\nimplemented in a base.html file, which main.html extends. Although not\nrequired, third party template authors are encouraged to follow a similar\npattern and may want to define the same blocks as are used in the built-in\nthemes for consistency.", "title": "Basic theme" - }, + }, { - "location": "/user-guide/custom-themes/#template-variables", - "text": "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.", + "location": "/user-guide/custom-themes/#template-variables", + "text": "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.", "title": "Template Variables" - }, + }, { - "location": "/user-guide/custom-themes/#global-context", - "text": "The following variables are available globally on any template.", + "location": "/user-guide/custom-themes/#global-context", + "text": "The following variables are available globally on any template.", "title": "Global Context" - }, + }, { - "location": "/user-guide/custom-themes/#config", - "text": "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\nused options include: config.site_name config.site_url config.site_author config.site_description config.repo_url config.repo_name config.copyright config.google_analytics", + "location": "/user-guide/custom-themes/#config", + "text": "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\nused options include: config.site_name config.site_url config.site_author config.site_description config.repo_url config.repo_name config.copyright config.google_analytics", "title": "config" - }, + }, { - "location": "/user-guide/custom-themes/#nav", - "text": "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. {% if nav|length 1 %}\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 {% endfor %}\n /ul \n{% endif %} The nav object also contains a hompage object, which points to the page \nobject of the homepage. For example, you may want to access nav.homepage.url .", + "location": "/user-guide/custom-themes/#nav", + "text": "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. {% if nav|length>1 %}\n
      \n {% for nav_item in nav %}\n {% if nav_item.children %}\n
    • {{ nav_item.title }}\n \n
      • \n {% else %}\n
    • \n {{ nav_item.title }}\n
      • \n {% endif %}\n {% endfor %}\n
    \n{% endif %} The nav object also contains a hompage object, which points to the page \nobject of the homepage. For example, you may want to access nav.homepage.url .", "title": "nav" - }, + }, { - "location": "/user-guide/custom-themes/#base_url", - "text": "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: script src= {{ base_url }}/js/theme.js /script", + "location": "/user-guide/custom-themes/#base_url", + "text": "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: ", "title": "base_url" - }, + }, { - "location": "/user-guide/custom-themes/#extra_css", - "text": "Contains a list of URLs to the style-sheets listed in the extra_css \nconfig setting. Unlike the config setting, which contains local paths, this\nvariable contains absolute paths from the homepage.", + "location": "/user-guide/custom-themes/#extra_css", + "text": "Contains a list of URLs to the style-sheets listed in the extra_css \nconfig setting. Unlike the config setting, which contains local paths, this\nvariable contains absolute paths from the homepage.", "title": "extra_css" - }, + }, { - "location": "/user-guide/custom-themes/#extra_javascript", - "text": "Contains a list of URLs to the scripts listed in the extra_javascript config\nsetting. Unlike the config setting, which contains local paths, this variable\ncontains absolute paths from the homepage.", + "location": "/user-guide/custom-themes/#extra_javascript", + "text": "Contains a list of URLs to the scripts listed in the extra_javascript config\nsetting. Unlike the config setting, which contains local paths, this variable\ncontains absolute paths from the homepage.", "title": "extra_javascript" - }, + }, { - "location": "/user-guide/custom-themes/#mkdocs_version", - "text": "Contains the current MkDocs version.", + "location": "/user-guide/custom-themes/#mkdocs_version", + "text": "Contains the current MkDocs version.", "title": "mkdocs_version" - }, + }, { - "location": "/user-guide/custom-themes/#build_date_utc", - "text": "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.", + "location": "/user-guide/custom-themes/#build_date_utc", + "text": "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.", "title": "build_date_utc" - }, + }, { - "location": "/user-guide/custom-themes/#page", - "text": "In templates which are not rendered from a Markdown source file, the page \nvariable is None . In templates which are rendered from a Markdown source file,\nthe page variable contains a page object with the following attributes:", + "location": "/user-guide/custom-themes/#page", + "text": "In templates which are not rendered from a Markdown source file, the page \nvariable is None . In templates which are rendered from a Markdown source file,\nthe page variable contains a page object with the following attributes:", "title": "page" - }, + }, { - "location": "/user-guide/custom-themes/#pagetitle", - "text": "Contains the Title for the current page.", + "location": "/user-guide/custom-themes/#pagetitle", + "text": "Contains the Title for the current page.", "title": "page.title" - }, + }, { - "location": "/user-guide/custom-themes/#pagecontent", - "text": "The rendered Markdown as HTML, this is the contents of the documentation.", + "location": "/user-guide/custom-themes/#pagecontent", + "text": "The rendered Markdown as HTML, this is the contents of the documentation.", "title": "page.content" - }, + }, { - "location": "/user-guide/custom-themes/#pagetoc", - "text": "An object representing the Table of contents for a page. Displaying the table\nof contents as a simple list can be achieved like this. ul \n{% for toc_item in page.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 %} /ul", + "location": "/user-guide/custom-themes/#pagetoc", + "text": "An object representing the Table of contents for a page. Displaying the table\nof contents as a simple list can be achieved like this. ", "title": "page.toc" - }, + }, { - "location": "/user-guide/custom-themes/#pagemeta", - "text": "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. source: generics.py\n mixins.py\n\n# Page title\n\nContent... 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. {% for filename in page.meta.source %}\n a class= github href= https://github.com/.../{{ filename }} \n span class= label label-info {{ filename }} /span \n /a \n{% endfor %}", + "location": "/user-guide/custom-themes/#pagemeta", + "text": "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. source: generics.py\n mixins.py\n\n# Page title\n\nContent... 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. {% for filename in page.meta.source %}\n \n {{ filename }}\n \n{% endfor %}", "title": "page.meta" - }, + }, { - "location": "/user-guide/custom-themes/#pagecanonical_url", - "text": "The full, canonical URL to the current page. This includes the site_url from\nthe configuration.", + "location": "/user-guide/custom-themes/#pagecanonical_url", + "text": "The full, canonical URL to the current page. This includes the site_url from\nthe configuration.", "title": "page.canonical_url" - }, + }, { - "location": "/user-guide/custom-themes/#pageedit_url", - "text": "The full URL to the input page in the source repository. Typically used to\nprovide a link to edit the source page.", + "location": "/user-guide/custom-themes/#pageedit_url", + "text": "The full URL to the input page in the source repository. Typically used to\nprovide a link to edit the source page.", "title": "page.edit_url" - }, + }, { - "location": "/user-guide/custom-themes/#pageurl", - "text": "The URL to the current page not including the site_url from the configuration.", + "location": "/user-guide/custom-themes/#pageurl", + "text": "The URL to the current page not including the site_url from the configuration.", "title": "page.url" - }, + }, { - "location": "/user-guide/custom-themes/#pageis_homepage", - "text": "Evaluates to True for the homepage of the site and False for all other\npages. This can be used in conjunction with other attributes of the page \nobject to alter the behavior. For example, to display a different title\non the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}", + "location": "/user-guide/custom-themes/#pageis_homepage", + "text": "Evaluates to True for the homepage of the site and False for all other\npages. This can be used in conjunction with other attributes of the page \nobject to alter the behavior. For example, to display a different title\non the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}", "title": "page.is_homepage" - }, + }, { - "location": "/user-guide/custom-themes/#pageprevious_page", - "text": "The page object for the previous page. The usage is the same as for page .", + "location": "/user-guide/custom-themes/#pageprevious_page", + "text": "The page object for the previous page. The usage is the same as for page .", "title": "page.previous_page" - }, + }, { - "location": "/user-guide/custom-themes/#pagenext_page", - "text": "The page object for the next page.The usage is the same as for page .", + "location": "/user-guide/custom-themes/#pagenext_page", + "text": "The page object for the next page.The usage is the same as for page .", "title": "page.next_page" - }, + }, { - "location": "/user-guide/custom-themes/#extra-context", - "text": "Additional variables can be passed to the template with the extra configuration option. This is a\nset 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\nand a list of links related to the project. This can be achieved with the\nfollowing extra configuration: 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/ And then displayed with this HTML in the custom theme. {{ 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 %}", + "location": "/user-guide/custom-themes/#extra-context", + "text": "Additional variables can be passed to the template with the extra configuration option. This is a\nset 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\nand a list of links related to the project. This can be achieved with the\nfollowing extra configuration: 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/ And then displayed with this HTML in the custom theme. {{ config.extra.version }}\n\n{% if config.extra.links %}\n
      \n {% for link in config.extra.links %}\n
    • {{ link }}
      • \n {% endfor %}\n
    \n{% endif %}", "title": "Extra Context" - }, + }, { - "location": "/user-guide/custom-themes/#search-and-themes", - "text": "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\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 http://localhost:8000/search.html . An example of the two different\napproaches 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\nfor Lunr.js. 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\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. 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. h1 id= search Search Results /h1 form action= search.html \n input name= q id= mkdocs-search-query type= text /form div id= mkdocs-search-results \n Sorry, page not found. /div 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.", + "location": "/user-guide/custom-themes/#search-and-themes", + "text": "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\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 http://localhost:8000/search.html . An example of the two different\napproaches 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\nfor Lunr.js. \n Note 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. 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.

    Search Results

    \n\n
    \n \n
    \n\n
    \n Sorry, page not found.\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.", "title": "Search and themes" - }, + }, { - "location": "/user-guide/custom-themes/#packaging-themes", - "text": "MkDocs makes use of Python packaging to distribute themes. This comes with a\nfew requirements. 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 . Note It is not strictly necessary to package a theme, as the entire theme\ncan be contained in the theme_dir . If you have created a \"one-off theme,\"\nthat should be sufficent. However, if you intend to distribute your theme\nfor others to use, packaging the theme has some advantages. By packaging\nyour theme, your users can more easily install it and they can them take\nadvantage of the theme_dir to make tweaks to your theme to better suit\ntheir needs.", + "location": "/user-guide/custom-themes/#packaging-themes", + "text": "MkDocs makes use of Python packaging to distribute themes. This comes with a\nfew requirements. 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 . Note It is not strictly necessary to package a theme, as the entire theme\ncan be contained in the theme_dir . If you have created a \"one-off theme,\"\nthat should be sufficent. However, if you intend to distribute your theme\nfor others to use, packaging the theme has some advantages. By packaging\nyour theme, your users can more easily install it and they can them take\nadvantage of the theme_dir to make tweaks to your theme to better suit\ntheir needs.", "title": "Packaging Themes" - }, + }, { - "location": "/user-guide/custom-themes/#package-layout", - "text": "The following layout is recommended for themes. Two files at the top level\ndirectory called MANIFEST.in amd setup.py beside the theme directory which\ncontains an empty __init__.py file and your template and media files. .\n|-- MANIFEST.in\n|-- theme_name\n| |-- __init__.py\n| |-- main.py\n| |-- styles.css\n`-- setup.py The MANIFEST.in file should contain the following contents but with\ntheme_name updated and any extra file extensions added to the include. recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff\nrecursive-exclude * __pycache__\nrecursive-exclude * *.py[co] The setup.py should include the following text with the modifications\ndescribed below. 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) Fill in the URL, license, description, author and author email address. 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. 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. The directory you created at the start of this section with the main.html file\nshould contain all of the other theme files. The minimum requirement is that\nit 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\ndirectory is a package.", + "location": "/user-guide/custom-themes/#package-layout", + "text": "The following layout is recommended for themes. Two files at the top level\ndirectory called MANIFEST.in amd setup.py beside the theme directory which\ncontains an empty __init__.py file and your template and media files. .\n|-- MANIFEST.in\n|-- theme_name\n| |-- __init__.py\n| |-- main.py\n| |-- styles.css\n`-- setup.py The MANIFEST.in file should contain the following contents but with\ntheme_name updated and any extra file extensions added to the include. recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff\nrecursive-exclude * __pycache__\nrecursive-exclude * *.py[co] The setup.py should include the following text with the modifications\ndescribed below. 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) Fill in the URL, license, description, author and author email address. 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. 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. The directory you created at the start of this section with the main.html file\nshould contain all of the other theme files. The minimum requirement is that\nit 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\ndirectory is a package.", "title": "Package Layout" - }, + }, { - "location": "/user-guide/custom-themes/#distributing-themes", - "text": "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. Most Python packages, including MkDocs, are distributed on PyPI. To do this,\nyou should run the following command. 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\ndocumentation for Packaging and Distributing Projects .", + "location": "/user-guide/custom-themes/#distributing-themes", + "text": "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. Most Python packages, including MkDocs, are distributed on PyPI. To do this,\nyou should run the following command. 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\ndocumentation for Packaging and Distributing Projects .", "title": "Distributing Themes" - }, + }, { - "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.15.2\n\n\n\nMaintenance team\n\uf0c1\n\n\nThe current and past members of the MkDocs team.\n\n\n\n\n@tomchristie\n\n\n@d0ugal\n\n\n@waylan\n\n\n\n\nVersion 0.16 (2016-11-04)\n\uf0c1\n\n\nMajor Additions to Version 0.16.0\n\uf0c1\n\n\nTemplate variables refactored. (#874)\n\uf0c1\n\n\nPage Context\n\uf0c1\n\n\nPage specific variable names in the template context have been refactored as\ndefined in \nCustom Themes\n. The\nold variable names will issue a warning but continue to work for version 0.16,\nbut may be removed in a future version.\n\n\nAny of the following old page variables should be updated to the new ones in\nuser created and third-party templates:\n\n\n\n\n\n\n\n\nOld Variable Name\n\n\nNew Variable Name\n\n\n\n\n\n\n\n\n\n\ncurrent_page\n\n\npage\n\n\n\n\n\n\npage_title\n\n\npage.title\n\n\n\n\n\n\ncontent\n\n\npage.content\n\n\n\n\n\n\ntoc\n\n\npage.toc\n\n\n\n\n\n\nmeta\n\n\npage.meta\n\n\n\n\n\n\ncanonical_url\n\n\npage.canonical_url\n\n\n\n\n\n\nprevious_page\n\n\npage.previous_page\n\n\n\n\n\n\nnext_page\n\n\npage.next_page\n\n\n\n\n\n\n\n\nGlobal Context\n\uf0c1\n\n\nAdditionally, a number of global variables have been altered and/or deprecated\nand user created and third-party templates should be updated as outlined below:\n\n\nPreviously, the global variable \ninclude_nav\n was altered programmatically based\non the number of pages in the nav. The variable will issue a warning but\ncontinue to work for version 0.16, but may be removed in a future version. Use\n\n{% if nav|length\n1 %}\n instead.\n\n\nPreviously, the global variable \ninclude_next_prev\n was altered programmatically\nbased on the number of pages in the nav. The variable will issue a warning but\ncontinue to work for version 0.16, but may be removed in a future version. Use\n\n{% if page.next_page or page.previous_page %}\n instead.\n\n\nPreviously the global variable \npage_description\n was altered programmatically\nbased on whether the current page was the homepage. Now it simply maps to\n\nconfig['site_description']\n. Use \n{% if page.is_homepage %}\n in the template to\nconditionally change the description.\n\n\nThe global variable \nhomepage_url\n maps directly to \nnav.homepage.url\n and is\nbeing deprecated. The variable will issue a warning but continue to work for\nversion 0.16, but may be removed in a future version. Use \nnav.homepage.url\n\ninstead.\n\n\nThe global variable \nfavicon\n maps to the configuration setting \nsite_favicon\n.\nBoth the template variable and the configuration setting are being deprecated\nand will issue a warning but continue to work for version 0.16, and may be\nremoved in a future version. Use \n{{ base_url }}/img/favicon.ico\n in your\ntemplate instead. Users can simply save a copy of their custom favicon icon to\n\nimg/favicon.ico\n in either their \ndocs_dir\n or \ntheme_dir\n.\n\n\nA number of variables map directly to similarly named variables in the \nconfig\n.\nThose variables are being deprecated and will issue a warning but continue to\nwork for version 0.16, but may be removed in a future version. Use\n\nconfig.var_name\n instead, where \nvar_name\n is the name of one of the\n\nconfiguration\n variables.\n\n\nBelow is a summary of all of the changes made to the global context:\n\n\n\n\n\n\n\n\nOld Variable Name\n\n\nNew Variable Name or Expression\n\n\n\n\n\n\n\n\n\n\ncurrent_page\n\n\npage\n\n\n\n\n\n\ninclude_nav\n\n\nnav\nlength\n1\n\n\n\n\n\n\ninclude_next_prev\n\n\n(page.next_page or page.previous_page)\n\n\n\n\n\n\nsite_name\n\n\nconfig.site_name\n\n\n\n\n\n\nsite_author\n\n\nconfig.site_author\n\n\n\n\n\n\npage_description\n\n\nconfig.site_description\n\n\n\n\n\n\nrepo_url\n\n\nconfig.repo_url\n\n\n\n\n\n\nrepo_name\n\n\nconfig.repo_name\n\n\n\n\n\n\nsite_url\n\n\nconfig.site_url\n\n\n\n\n\n\ncopyright\n\n\nconfig.copyright\n\n\n\n\n\n\ngoogle_analytics\n\n\nconfig.google_analytics\n\n\n\n\n\n\nhomepage_url\n\n\nnav.homepage.url\n\n\n\n\n\n\nfavicon\n\n\n{{ base_url }}/img/favicon.ico\n\n\n\n\n\n\n\n\nIncreased Template Customization. (#607)\n\uf0c1\n\n\nThe built-in themes have been updated by having each of their many parts wrapped\nin template blocks which allow each individual block to be easily overridden\nusing the \ntheme_dir\n config setting. Without any new settings, you can use a\ndifferent analytics service, replace the default search function, or alter the\nbehavior of the navigation, among other things. See the relevant\n\ndocumentation\n for more details.\n\n\nTo enable this feature, the primary entry point for page templates has been\nchanged from \nbase.html\n to \nmain.html\n. This allows \nbase.html\n to continue to\nexist while allowing users to override \nmain.html\n and extend \nbase.html\n. For\nversion 0.16, \nbase.html\n will continue to work if no \nmain.html\n template\nexists, but it is deprecated and will raise a warning. In version 1.0, a build\nwill fail if no \nmain.html\n template exists. Any custom and third party\ntemplates should be updated accordingly.\n\n\nThe easiest way for a third party theme to be updated would be to simply add a\n\nmain.html\n file which only contains the following line:\n\n\n{% extends \nbase.html\n %}\n\n\n\n\nThat way, the theme contains the \nmain.html\n entry point, and also supports\noverriding blocks in the same manner as the built-in themes. Third party themes\nare encouraged to wrap the various pieces of their templates in blocks in order\nto support such customization.\n\n\nAuto-Populated \nextra_css\n and \nextra_javascript\n Deprecated. (#986)\n\uf0c1\n\n\nIn previous versions of MkDocs, if the \nextra_css\n or \nextra_javascript\n config\nsettings were empty, MkDocs would scan the \ndocs_dir\n and auto-populate each\nsetting with all of the CSS and JavaScript files found. This behavior is\ndeprecated and a warning will be issued. In the next release, the auto-populate\nfeature will stop working and any unlisted CSS and JavaScript files will not be\nincluded in the HTML templates. In other words, they will still be copied to the\n\nsite-dir\n, but they will not have any effect on the theme if they are not\nexplicitly listed.\n\n\nAll CSS and javaScript files in the \ndocs_dir\n should be explicitly listed in\nthe \nextra_css\n or \nextra_javascript\n config settings going forward.\n\n\nSupport for dirty builds. (#990)\n\uf0c1\n\n\nFor large sites the build time required to create the pages can become problematic,\nthus a \"dirty\" build mode was created. This mode simply compares the modified time\nof the generated HTML and source markdown. If the markdown has changed since the\nHTML then the page is re-constructed. Otherwise, the page remains as is. This mode\nmay be invoked in both the \nmkdocs serve\n and \nmkdocs build\n commands:\n\n\nmkdocs serve --dirtyreload\n\n\n\n\nmkdocs build --dirty\n\n\n\n\nIt is important to note that this method for building the pages is for development\nof content only, since the navigation and other links do not get updated on other\npages.\n\n\nStricter Directory Validation\n\uf0c1\n\n\nPreviously, a warning was issued if the \nsite_dir\n was a child directory of the\n\ndocs_dir\n. This now raises an error. Additionally, an error is now raised if\nthe \ndocs_dir\n is set to the directory which contains your config file rather\nthan a child directory. You will need to rearrange you directory structure to\nbetter conform with the documented \nlayout\n.\n\n\nOther Changes and Additions to Version 0.16.0\n\uf0c1\n\n\n\n\nBugfix: Support \ngh-deploy\n command on Windows with Python 3 (#722)\n\n\nBugfix: Include .woff2 font files in Python package build (#894)\n\n\nVarious updates and improvements to Documentation Home Page/Tutorial (#870)\n\n\nBugfix: Support livereload for config file changes (#735)\n\n\nBugfix: Non-media template files are no longer copied with media files (#807)\n\n\nAdd a flag (-e/--theme-dir) to specify theme directory with the commands\n \nmkdocs build\n and \nmkdocs serve\n (#832)\n\n\nFixed issues with Unicode file names under Windows and Python 2. (#833)\n\n\nImproved the styling of in-line code in the MkDocs theme. (#718)\n\n\nBugfix: convert variables to JSON when being passed to JavaScript (#850)\n\n\nUpdated the ReadTheDocs theme to match the upstream font sizes and colors\n more closely. (#857)\n\n\nFixes an issue with permalink markers showing when the mouse was far above\n them (#843)\n\n\nBugfix: Handle periods in directory name when automatically creating the\n pages config. (#728)\n\n\nUpdate searching to Lunr 0.7, which comes with some performance enhancements\n for larger documents (#859)\n\n\nBugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\"\n builds (#938)\n\n\nFollow links when copying media files (#869).\n\n\nChange \"Edit on...\" links to point directly to the file in the source\n repository, rather than to the root of the repository (#975), configurable\n via the new \nedit_uri\n setting.\n\n\nBugfix: Don't override config value for strict mode if not specified on CLI\n (#738).\n\n\nAdd a \n--force\n flag to the \ngh-deploy\n command to force the push to the\n repository (#973).\n\n\nImprove alignment for current selected menu item in readthedocs theme (#888).\n\n\nhttp://user.github.io/repo\n =\n \nhttps://user.github.io/repo/\n (#1029).\n\n\nImprove installation instructions (#1028).\n\n\nAccount for wide tables and consistently wrap inline code spans (#834).\n\n\nBugfix: Use absolute URLs in nav \n media links from error templates (#77).\n\n\n\n\nVersion 0.15.3 (2016-02-18)\n\uf0c1\n\n\n\n\nImprove the error message the given theme can't be found.\n\n\nFix an issue with relative symlinks (#639)\n\n\n\n\nVersion 0.15.2 (2016-02-08)\n\uf0c1\n\n\n\n\nFix an incorrect warning that states external themes \nwill be removed from\n MkDocs\n.\n\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 package maintainers.\n (#763)\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 a future 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)", + "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.15.2\n\n\n\nMaintenance team\n\uf0c1\n\n\nThe current and past members of the MkDocs team.\n\n\n\n\n@tomchristie\n\n\n@d0ugal\n\n\n@waylan\n\n\n\n\nVersion 0.16.1 (2016-12-22)\n\uf0c1\n\n\n\n\nEnsure scrollspy behavior does not affect nav bar (#1094)\n\n\nOnly \"load\" a theme when it is explicitly requested by the user (#1105)\n\n\n\n\nVersion 0.16 (2016-11-04)\n\uf0c1\n\n\nMajor Additions to Version 0.16.0\n\uf0c1\n\n\nTemplate variables refactored. (#874)\n\uf0c1\n\n\nPage Context\n\uf0c1\n\n\nPage specific variable names in the template context have been refactored as\ndefined in \nCustom Themes\n. The\nold variable names will issue a warning but continue to work for version 0.16,\nbut may be removed in a future version.\n\n\nAny of the following old page variables should be updated to the new ones in\nuser created and third-party templates:\n\n\n\n\n\n\n\n\nOld Variable Name\n\n\nNew Variable Name\n\n\n\n\n\n\n\n\n\n\ncurrent_page\n\n\npage\n\n\n\n\n\n\npage_title\n\n\npage.title\n\n\n\n\n\n\ncontent\n\n\npage.content\n\n\n\n\n\n\ntoc\n\n\npage.toc\n\n\n\n\n\n\nmeta\n\n\npage.meta\n\n\n\n\n\n\ncanonical_url\n\n\npage.canonical_url\n\n\n\n\n\n\nprevious_page\n\n\npage.previous_page\n\n\n\n\n\n\nnext_page\n\n\npage.next_page\n\n\n\n\n\n\n\n\nGlobal Context\n\uf0c1\n\n\nAdditionally, a number of global variables have been altered and/or deprecated\nand user created and third-party templates should be updated as outlined below:\n\n\nPreviously, the global variable \ninclude_nav\n was altered programmatically based\non the number of pages in the nav. The variable will issue a warning but\ncontinue to work for version 0.16, but may be removed in a future version. Use\n\n{% if nav|length>1 %}\n instead.\n\n\nPreviously, the global variable \ninclude_next_prev\n was altered programmatically\nbased on the number of pages in the nav. The variable will issue a warning but\ncontinue to work for version 0.16, but may be removed in a future version. Use\n\n{% if page.next_page or page.previous_page %}\n instead.\n\n\nPreviously the global variable \npage_description\n was altered programmatically\nbased on whether the current page was the homepage. Now it simply maps to\n\nconfig['site_description']\n. Use \n{% if page.is_homepage %}\n in the template to\nconditionally change the description.\n\n\nThe global variable \nhomepage_url\n maps directly to \nnav.homepage.url\n and is\nbeing deprecated. The variable will issue a warning but continue to work for\nversion 0.16, but may be removed in a future version. Use \nnav.homepage.url\n\ninstead.\n\n\nThe global variable \nfavicon\n maps to the configuration setting \nsite_favicon\n.\nBoth the template variable and the configuration setting are being deprecated\nand will issue a warning but continue to work for version 0.16, and may be\nremoved in a future version. Use \n{{ base_url }}/img/favicon.ico\n in your\ntemplate instead. Users can simply save a copy of their custom favicon icon to\n\nimg/favicon.ico\n in either their \ndocs_dir\n or \ntheme_dir\n.\n\n\nA number of variables map directly to similarly named variables in the \nconfig\n.\nThose variables are being deprecated and will issue a warning but continue to\nwork for version 0.16, but may be removed in a future version. Use\n\nconfig.var_name\n instead, where \nvar_name\n is the name of one of the\n\nconfiguration\n variables.\n\n\nBelow is a summary of all of the changes made to the global context:\n\n\n\n\n\n\n\n\nOld Variable Name\n\n\nNew Variable Name or Expression\n\n\n\n\n\n\n\n\n\n\ncurrent_page\n\n\npage\n\n\n\n\n\n\ninclude_nav\n\n\nnav|length>1\n\n\n\n\n\n\ninclude_next_prev\n\n\n(page.next_page or page.previous_page)\n\n\n\n\n\n\nsite_name\n\n\nconfig.site_name\n\n\n\n\n\n\nsite_author\n\n\nconfig.site_author\n\n\n\n\n\n\npage_description\n\n\nconfig.site_description\n\n\n\n\n\n\nrepo_url\n\n\nconfig.repo_url\n\n\n\n\n\n\nrepo_name\n\n\nconfig.repo_name\n\n\n\n\n\n\nsite_url\n\n\nconfig.site_url\n\n\n\n\n\n\ncopyright\n\n\nconfig.copyright\n\n\n\n\n\n\ngoogle_analytics\n\n\nconfig.google_analytics\n\n\n\n\n\n\nhomepage_url\n\n\nnav.homepage.url\n\n\n\n\n\n\nfavicon\n\n\n{{ base_url }}/img/favicon.ico\n\n\n\n\n\n\n\n\nIncreased Template Customization. (#607)\n\uf0c1\n\n\nThe built-in themes have been updated by having each of their many parts wrapped\nin template blocks which allow each individual block to be easily overridden\nusing the \ntheme_dir\n config setting. Without any new settings, you can use a\ndifferent analytics service, replace the default search function, or alter the\nbehavior of the navigation, among other things. See the relevant\n\ndocumentation\n for more details.\n\n\nTo enable this feature, the primary entry point for page templates has been\nchanged from \nbase.html\n to \nmain.html\n. This allows \nbase.html\n to continue to\nexist while allowing users to override \nmain.html\n and extend \nbase.html\n. For\nversion 0.16, \nbase.html\n will continue to work if no \nmain.html\n template\nexists, but it is deprecated and will raise a warning. In version 1.0, a build\nwill fail if no \nmain.html\n template exists. Any custom and third party\ntemplates should be updated accordingly.\n\n\nThe easiest way for a third party theme to be updated would be to simply add a\n\nmain.html\n file which only contains the following line:\n\n\n{% extends \"base.html\" %}\n\n\n\n\nThat way, the theme contains the \nmain.html\n entry point, and also supports\noverriding blocks in the same manner as the built-in themes. Third party themes\nare encouraged to wrap the various pieces of their templates in blocks in order\nto support such customization.\n\n\nAuto-Populated \nextra_css\n and \nextra_javascript\n Deprecated. (#986)\n\uf0c1\n\n\nIn previous versions of MkDocs, if the \nextra_css\n or \nextra_javascript\n config\nsettings were empty, MkDocs would scan the \ndocs_dir\n and auto-populate each\nsetting with all of the CSS and JavaScript files found. This behavior is\ndeprecated and a warning will be issued. In the next release, the auto-populate\nfeature will stop working and any unlisted CSS and JavaScript files will not be\nincluded in the HTML templates. In other words, they will still be copied to the\n\nsite-dir\n, but they will not have any effect on the theme if they are not\nexplicitly listed.\n\n\nAll CSS and javaScript files in the \ndocs_dir\n should be explicitly listed in\nthe \nextra_css\n or \nextra_javascript\n config settings going forward.\n\n\nSupport for dirty builds. (#990)\n\uf0c1\n\n\nFor large sites the build time required to create the pages can become problematic,\nthus a \"dirty\" build mode was created. This mode simply compares the modified time\nof the generated HTML and source markdown. If the markdown has changed since the\nHTML then the page is re-constructed. Otherwise, the page remains as is. This mode\nmay be invoked in both the \nmkdocs serve\n and \nmkdocs build\n commands:\n\n\nmkdocs serve --dirtyreload\n\n\n\n\nmkdocs build --dirty\n\n\n\n\nIt is important to note that this method for building the pages is for development\nof content only, since the navigation and other links do not get updated on other\npages.\n\n\nStricter Directory Validation\n\uf0c1\n\n\nPreviously, a warning was issued if the \nsite_dir\n was a child directory of the\n\ndocs_dir\n. This now raises an error. Additionally, an error is now raised if\nthe \ndocs_dir\n is set to the directory which contains your config file rather\nthan a child directory. You will need to rearrange you directory structure to\nbetter conform with the documented \nlayout\n.\n\n\nOther Changes and Additions to Version 0.16.0\n\uf0c1\n\n\n\n\nBugfix: Support \ngh-deploy\n command on Windows with Python 3 (#722)\n\n\nBugfix: Include .woff2 font files in Python package build (#894)\n\n\nVarious updates and improvements to Documentation Home Page/Tutorial (#870)\n\n\nBugfix: Support livereload for config file changes (#735)\n\n\nBugfix: Non-media template files are no longer copied with media files (#807)\n\n\nAdd a flag (-e/--theme-dir) to specify theme directory with the commands\n \nmkdocs build\n and \nmkdocs serve\n (#832)\n\n\nFixed issues with Unicode file names under Windows and Python 2. (#833)\n\n\nImproved the styling of in-line code in the MkDocs theme. (#718)\n\n\nBugfix: convert variables to JSON when being passed to JavaScript (#850)\n\n\nUpdated the ReadTheDocs theme to match the upstream font sizes and colors\n more closely. (#857)\n\n\nFixes an issue with permalink markers showing when the mouse was far above\n them (#843)\n\n\nBugfix: Handle periods in directory name when automatically creating the\n pages config. (#728)\n\n\nUpdate searching to Lunr 0.7, which comes with some performance enhancements\n for larger documents (#859)\n\n\nBugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\"\n builds (#938)\n\n\nFollow links when copying media files (#869).\n\n\nChange \"Edit on...\" links to point directly to the file in the source\n repository, rather than to the root of the repository (#975), configurable\n via the new \nedit_uri\n setting.\n\n\nBugfix: Don't override config value for strict mode if not specified on CLI\n (#738).\n\n\nAdd a \n--force\n flag to the \ngh-deploy\n command to force the push to the\n repository (#973).\n\n\nImprove alignment for current selected menu item in readthedocs theme (#888).\n\n\nhttp://user.github.io/repo\n => \nhttps://user.github.io/repo/\n (#1029).\n\n\nImprove installation instructions (#1028).\n\n\nAccount for wide tables and consistently wrap inline code spans (#834).\n\n\nBugfix: Use absolute URLs in nav & media links from error templates (#77).\n\n\n\n\nVersion 0.15.3 (2016-02-18)\n\uf0c1\n\n\n\n\nImprove the error message the given theme can't be found.\n\n\nFix an issue with relative symlinks (#639)\n\n\n\n\nVersion 0.15.2 (2016-02-08)\n\uf0c1\n\n\n\n\nFix an incorrect warning that states external themes \nwill be removed from\n MkDocs\n.\n\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 package maintainers.\n (#763)\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 a future 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 >= 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 \n
      \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" - }, + }, { - "location": "/about/release-notes/#release-notes", - "text": "", + "location": "/about/release-notes/#release-notes", + "text": "", "title": "Release Notes" - }, + }, { - "location": "/about/release-notes/#upgrading", - "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.15.2", + "location": "/about/release-notes/#upgrading", + "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.15.2", "title": "Upgrading" - }, + }, { - "location": "/about/release-notes/#maintenance-team", - "text": "The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan", + "location": "/about/release-notes/#maintenance-team", + "text": "The current and past members of the MkDocs team. @tomchristie @d0ugal @waylan", "title": "Maintenance team" - }, + }, { - "location": "/about/release-notes/#version-016-2016-11-04", - "text": "", + "location": "/about/release-notes/#version-0161-2016-12-22", + "text": "Ensure scrollspy behavior does not affect nav bar (#1094) Only \"load\" a theme when it is explicitly requested by the user (#1105)", + "title": "Version 0.16.1 (2016-12-22)" + }, + { + "location": "/about/release-notes/#version-016-2016-11-04", + "text": "", "title": "Version 0.16 (2016-11-04)" - }, + }, { - "location": "/about/release-notes/#major-additions-to-version-0160", - "text": "", + "location": "/about/release-notes/#major-additions-to-version-0160", + "text": "", "title": "Major Additions to Version 0.16.0" - }, + }, { - "location": "/about/release-notes/#template-variables-refactored-874", - "text": "", + "location": "/about/release-notes/#template-variables-refactored-874", + "text": "", "title": "Template variables refactored. (#874)" - }, + }, { - "location": "/about/release-notes/#page-context", - "text": "Page specific variable names in the template context have been refactored as\ndefined in Custom Themes . The\nold variable names will issue a warning but continue to work for version 0.16,\nbut may be removed in a future version. Any of the following old page variables should be updated to the new ones in\nuser 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", + "location": "/about/release-notes/#page-context", + "text": "Page specific variable names in the template context have been refactored as\ndefined in Custom Themes . The\nold variable names will issue a warning but continue to work for version 0.16,\nbut may be removed in a future version. Any of the following old page variables should be updated to the new ones in\nuser 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", "title": "Page Context" - }, + }, { - "location": "/about/release-notes/#global-context", - "text": "Additionally, a number of global variables have been altered and/or deprecated\nand user created and third-party templates should be updated as outlined below: Previously, the global variable include_nav was altered programmatically based\non the number of pages in the nav. The variable will issue a warning but\ncontinue 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\nbased on the number of pages in the nav. The variable will issue a warning but\ncontinue 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\nbased 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\nconditionally change the description. The global variable homepage_url maps directly to nav.homepage.url and is\nbeing deprecated. The variable will issue a warning but continue to work for\nversion 0.16, but may be removed in a future version. Use nav.homepage.url \ninstead. The global variable favicon maps to the configuration setting site_favicon .\nBoth the template variable and the configuration setting are being deprecated\nand will issue a warning but continue to work for version 0.16, and may be\nremoved in a future version. Use {{ base_url }}/img/favicon.ico in your\ntemplate 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 .\nThose variables are being deprecated and will issue a warning but continue to\nwork 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. 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", + "location": "/about/release-notes/#global-context", + "text": "Additionally, a number of global variables have been altered and/or deprecated\nand user created and third-party templates should be updated as outlined below: Previously, the global variable include_nav was altered programmatically based\non the number of pages in the nav. The variable will issue a warning but\ncontinue 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\nbased on the number of pages in the nav. The variable will issue a warning but\ncontinue 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\nbased 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\nconditionally change the description. The global variable homepage_url maps directly to nav.homepage.url and is\nbeing deprecated. The variable will issue a warning but continue to work for\nversion 0.16, but may be removed in a future version. Use nav.homepage.url \ninstead. The global variable favicon maps to the configuration setting site_favicon .\nBoth the template variable and the configuration setting are being deprecated\nand will issue a warning but continue to work for version 0.16, and may be\nremoved in a future version. Use {{ base_url }}/img/favicon.ico in your\ntemplate 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 .\nThose variables are being deprecated and will issue a warning but continue to\nwork 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. 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", "title": "Global Context" - }, + }, { - "location": "/about/release-notes/#increased-template-customization-607", - "text": "The built-in themes have been updated by having each of their many parts wrapped\nin template blocks which allow each individual block to be easily overridden\nusing the theme_dir config setting. Without any new settings, you can use a\ndifferent analytics service, replace the default search function, or alter the\nbehavior of the navigation, among other things. See the relevant documentation for more details. To enable this feature, the primary entry point for page templates has been\nchanged from base.html to main.html . This allows base.html to continue to\nexist while allowing users to override main.html and extend base.html . For\nversion 0.16, base.html will continue to work if no main.html template\nexists, but it is deprecated and will raise a warning. In version 1.0, a build\nwill fail if no main.html template exists. Any custom and third party\ntemplates 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: {% extends base.html %} That way, the theme contains the main.html entry point, and also supports\noverriding blocks in the same manner as the built-in themes. Third party themes\nare encouraged to wrap the various pieces of their templates in blocks in order\nto support such customization.", + "location": "/about/release-notes/#increased-template-customization-607", + "text": "The built-in themes have been updated by having each of their many parts wrapped\nin template blocks which allow each individual block to be easily overridden\nusing the theme_dir config setting. Without any new settings, you can use a\ndifferent analytics service, replace the default search function, or alter the\nbehavior of the navigation, among other things. See the relevant documentation for more details. To enable this feature, the primary entry point for page templates has been\nchanged from base.html to main.html . This allows base.html to continue to\nexist while allowing users to override main.html and extend base.html . For\nversion 0.16, base.html will continue to work if no main.html template\nexists, but it is deprecated and will raise a warning. In version 1.0, a build\nwill fail if no main.html template exists. Any custom and third party\ntemplates 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: {% extends \"base.html\" %} That way, the theme contains the main.html entry point, and also supports\noverriding blocks in the same manner as the built-in themes. Third party themes\nare encouraged to wrap the various pieces of their templates in blocks in order\nto support such customization.", "title": "Increased Template Customization. (#607)" - }, + }, { - "location": "/about/release-notes/#auto-populated-extra_css-and-extra_javascript-deprecated-986", - "text": "In previous versions of MkDocs, if the extra_css or extra_javascript config\nsettings were empty, MkDocs would scan the docs_dir and auto-populate each\nsetting with all of the CSS and JavaScript files found. This behavior is\ndeprecated and a warning will be issued. In the next release, the auto-populate\nfeature will stop working and any unlisted CSS and JavaScript files will not be\nincluded 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\nexplicitly listed. All CSS and javaScript files in the docs_dir should be explicitly listed in\nthe extra_css or extra_javascript config settings going forward.", + "location": "/about/release-notes/#auto-populated-extra_css-and-extra_javascript-deprecated-986", + "text": "In previous versions of MkDocs, if the extra_css or extra_javascript config\nsettings were empty, MkDocs would scan the docs_dir and auto-populate each\nsetting with all of the CSS and JavaScript files found. This behavior is\ndeprecated and a warning will be issued. In the next release, the auto-populate\nfeature will stop working and any unlisted CSS and JavaScript files will not be\nincluded 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\nexplicitly listed. All CSS and javaScript files in the docs_dir should be explicitly listed in\nthe extra_css or extra_javascript config settings going forward.", "title": "Auto-Populated extra_css and extra_javascript Deprecated. (#986)" - }, + }, { - "location": "/about/release-notes/#support-for-dirty-builds-990", - "text": "For large sites the build time required to create the pages can become problematic,\nthus a \"dirty\" build mode was created. This mode simply compares the modified time\nof the generated HTML and source markdown. If the markdown has changed since the\nHTML then the page is re-constructed. Otherwise, the page remains as is. This mode\nmay be invoked in both the mkdocs serve and mkdocs build commands: mkdocs serve --dirtyreload mkdocs build --dirty It is important to note that this method for building the pages is for development\nof content only, since the navigation and other links do not get updated on other\npages.", + "location": "/about/release-notes/#support-for-dirty-builds-990", + "text": "For large sites the build time required to create the pages can become problematic,\nthus a \"dirty\" build mode was created. This mode simply compares the modified time\nof the generated HTML and source markdown. If the markdown has changed since the\nHTML then the page is re-constructed. Otherwise, the page remains as is. This mode\nmay be invoked in both the mkdocs serve and mkdocs build commands: mkdocs serve --dirtyreload mkdocs build --dirty It is important to note that this method for building the pages is for development\nof content only, since the navigation and other links do not get updated on other\npages.", "title": "Support for dirty builds. (#990)" - }, + }, { - "location": "/about/release-notes/#stricter-directory-validation", - "text": "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\nthe docs_dir is set to the directory which contains your config file rather\nthan a child directory. You will need to rearrange you directory structure to\nbetter conform with the documented layout .", + "location": "/about/release-notes/#stricter-directory-validation", + "text": "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\nthe docs_dir is set to the directory which contains your config file rather\nthan a child directory. You will need to rearrange you directory structure to\nbetter conform with the documented layout .", "title": "Stricter Directory Validation" - }, + }, { - "location": "/about/release-notes/#other-changes-and-additions-to-version-0160", - "text": "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\n 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\n more closely. (#857) Fixes an issue with permalink markers showing when the mouse was far above\n them (#843) Bugfix: Handle periods in directory name when automatically creating the\n pages config. (#728) Update searching to Lunr 0.7, which comes with some performance enhancements\n for larger documents (#859) Bugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\"\n builds (#938) Follow links when copying media files (#869). Change \"Edit on...\" links to point directly to the file in the source\n repository, rather than to the root of the repository (#975), configurable\n via the new edit_uri setting. Bugfix: Don't override config value for strict mode if not specified on CLI\n (#738). Add a --force flag to the gh-deploy command to force the push to the\n 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).", + "location": "/about/release-notes/#other-changes-and-additions-to-version-0160", + "text": "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\n 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\n more closely. (#857) Fixes an issue with permalink markers showing when the mouse was far above\n them (#843) Bugfix: Handle periods in directory name when automatically creating the\n pages config. (#728) Update searching to Lunr 0.7, which comes with some performance enhancements\n for larger documents (#859) Bugfix: Support SOURCE_DATE_EPOCH environment variable for \"reproducible\"\n builds (#938) Follow links when copying media files (#869). Change \"Edit on...\" links to point directly to the file in the source\n repository, rather than to the root of the repository (#975), configurable\n via the new edit_uri setting. Bugfix: Don't override config value for strict mode if not specified on CLI\n (#738). Add a --force flag to the gh-deploy command to force the push to the\n 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).", "title": "Other Changes and Additions to Version 0.16.0" - }, + }, { - "location": "/about/release-notes/#version-0153-2016-02-18", - "text": "Improve the error message the given theme can't be found. Fix an issue with relative symlinks (#639)", + "location": "/about/release-notes/#version-0153-2016-02-18", + "text": "Improve the error message the given theme can't be found. Fix an issue with relative symlinks (#639)", "title": "Version 0.15.3 (2016-02-18)" - }, + }, { - "location": "/about/release-notes/#version-0152-2016-02-08", - "text": "Fix an incorrect warning that states external themes will be removed from\n MkDocs .", + "location": "/about/release-notes/#version-0152-2016-02-08", + "text": "Fix an incorrect warning that states external themes will be removed from\n MkDocs .", "title": "Version 0.15.2 (2016-02-08)" - }, + }, { - "location": "/about/release-notes/#version-0151-2016-01-30", - "text": "Lower the minimum supported Click version to 3.3 for package maintainers.\n (#763)", + "location": "/about/release-notes/#version-0151-2016-01-30", + "text": "Lower the minimum supported Click version to 3.3 for package maintainers.\n (#763)", "title": "Version 0.15.1 (2016-01-30)" - }, + }, { - "location": "/about/release-notes/#version-0150-2016-01-21", - "text": "", + "location": "/about/release-notes/#version-0150-2016-01-21", + "text": "", "title": "Version 0.15.0 (2016-01-21)" - }, + }, { - "location": "/about/release-notes/#major-additions-to-version-0150", - "text": "", + "location": "/about/release-notes/#major-additions-to-version-0150", + "text": "", "title": "Major Additions to Version 0.15.0" - }, + }, { - "location": "/about/release-notes/#add-support-for-installable-themes", - "text": "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. MkDocs Bootstrap MkDocs Bootswatch They will be included with MkDocs by default until a future release. After that\nthey will be installable with pip: pip install mkdocs-bootstrap and pip\ninstall mkdocs-bootswatch See the documentation for Styling your docs for more information about using\nand customising themes and Custom themes for creating and distributing new\nthemes", + "location": "/about/release-notes/#add-support-for-installable-themes", + "text": "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. MkDocs Bootstrap MkDocs Bootswatch They will be included with MkDocs by default until a future release. After that\nthey will be installable with pip: pip install mkdocs-bootstrap and pip\ninstall mkdocs-bootswatch See the documentation for Styling your docs for more information about using\nand customising themes and Custom themes for creating and distributing new\nthemes", "title": "Add support for installable themes" - }, + }, { - "location": "/about/release-notes/#other-changes-and-additions-to-version-0150", - "text": "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 \n 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\n for the page. (#204) Bugfix: Add all ancestors to the page attribute ancestors rather than just\n 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)", + "location": "/about/release-notes/#other-changes-and-additions-to-version-0150", + "text": "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 \n 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\n for the page. (#204) Bugfix: Add all ancestors to the page attribute ancestors rather than just\n 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)", "title": "Other Changes and Additions to Version 0.15.0" - }, + }, { - "location": "/about/release-notes/#version-0140-2015-06-09", - "text": "Improve Unicode handling by ensuring that all config strings are loaded as\n 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\n 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.\n (#578) Bugfix: Handle (pass-through instead of dropping) HTML entities while\n parsing TOC. (#612) Bugfix: Default extra_templates to an empty list, don't automatically\n discover them. (#616)", + "location": "/about/release-notes/#version-0140-2015-06-09", + "text": "Improve Unicode handling by ensuring that all config strings are loaded as\n 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\n 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.\n (#578) Bugfix: Handle (pass-through instead of dropping) HTML entities while\n parsing TOC. (#612) Bugfix: Default extra_templates to an empty list, don't automatically\n discover them. (#616)", "title": "Version 0.14.0 (2015-06-09)" - }, + }, { - "location": "/about/release-notes/#version-0133-2015-06-02", - "text": "Bugfix: 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)", + "location": "/about/release-notes/#version-0133-2015-06-02", + "text": "Bugfix: 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)", "title": "Version 0.13.3 (2015-06-02)" - }, + }, { - "location": "/about/release-notes/#version-0132-2015-05-30", - "text": "Bugfix: Ensure all errors and warnings are logged before exiting. (#536) Bugfix: Fix compatibility issues with ReadTheDocs. (#554)", + "location": "/about/release-notes/#version-0132-2015-05-30", + "text": "Bugfix: Ensure all errors and warnings are logged before exiting. (#536) Bugfix: Fix compatibility issues with ReadTheDocs. (#554)", "title": "Version 0.13.2 (2015-05-30)" - }, + }, { - "location": "/about/release-notes/#version-0131-2015-05-27", - "text": "Bugfix: Fix a problem with minimal configurations which only contain a list\n of paths in the pages config. (#562)", + "location": "/about/release-notes/#version-0131-2015-05-27", + "text": "Bugfix: Fix a problem with minimal configurations which only contain a list\n of paths in the pages config. (#562)", "title": "Version 0.13.1 (2015-05-27)" - }, + }, { - "location": "/about/release-notes/#version-0130-2015-05-26", - "text": "", + "location": "/about/release-notes/#version-0130-2015-05-26", + "text": "", "title": "Version 0.13.0 (2015-05-26)" - }, + }, { - "location": "/about/release-notes/#deprecations-to-version-0130", - "text": "", + "location": "/about/release-notes/#deprecations-to-version-0130", + "text": "", "title": "Deprecations to Version 0.13.0" - }, + }, { - "location": "/about/release-notes/#deprecate-the-json-command", - "text": "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. 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\nno configuration is needed to enable it.", + "location": "/about/release-notes/#deprecate-the-json-command", + "text": "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. 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\nno configuration is needed to enable it.", "title": "Deprecate the JSON command" - }, + }, { - "location": "/about/release-notes/#change-the-pages-configuration", - "text": "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.", + "location": "/about/release-notes/#change-the-pages-configuration", + "text": "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.", "title": "Change the pages configuration" - }, + }, { - "location": "/about/release-notes/#warn-users-about-the-removal-of-builtin-themes", - "text": "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.", + "location": "/about/release-notes/#warn-users-about-the-removal-of-builtin-themes", + "text": "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.", "title": "Warn users about the removal of builtin themes" - }, + }, { - "location": "/about/release-notes/#major-additions-to-version-0130", - "text": "", + "location": "/about/release-notes/#major-additions-to-version-0130", + "text": "", "title": "Major Additions to Version 0.13.0" - }, + }, { - "location": "/about/release-notes/#search", - "text": "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 readthedocs themes. See the custom theme documentation on supporting search \nfor adding it to your own themes.", + "location": "/about/release-notes/#search", + "text": "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 readthedocs themes. See the custom theme documentation on supporting search \nfor adding it to your own themes.", "title": "Search" - }, + }, { - "location": "/about/release-notes/#new-command-line-interface", - "text": "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. 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 mkdocs build --help to have them displayed.", + "location": "/about/release-notes/#new-command-line-interface", + "text": "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. 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 mkdocs build --help to have them displayed.", "title": "New Command Line Interface" - }, + }, { - "location": "/about/release-notes/#support-extra-html-and-xml-files", - "text": "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. 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 . By default MkDocs will use this approach to create a sitemap for the\ndocumentation.", + "location": "/about/release-notes/#support-extra-html-and-xml-files", + "text": "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. 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 . By default MkDocs will use this approach to create a sitemap for the\ndocumentation.", "title": "Support Extra HTML and XML files" - }, + }, { - "location": "/about/release-notes/#other-changes-and-additions-to-version-0130", - "text": "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\n called index.md (#535) Bugfix: Fix errors with unicode filenames (#542).", + "location": "/about/release-notes/#other-changes-and-additions-to-version-0130", + "text": "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\n called index.md (#535) Bugfix: Fix errors with unicode filenames (#542).", "title": "Other Changes and Additions to Version 0.13.0" - }, + }, { - "location": "/about/release-notes/#version-0122-2015-04-22", - "text": "Bugfix: 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)", + "location": "/about/release-notes/#version-0122-2015-04-22", + "text": "Bugfix: 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)", "title": "Version 0.12.2 (2015-04-22)" - }, + }, { - "location": "/about/release-notes/#version-0121-2015-04-14", - "text": "Bugfix: Fixed a CSS bug in the table of contents on some browsers where the\n bottom item was not clickable.", + "location": "/about/release-notes/#version-0121-2015-04-14", + "text": "Bugfix: Fixed a CSS bug in the table of contents on some browsers where the\n bottom item was not clickable.", "title": "Version 0.12.1 (2015-04-14)" - }, + }, { - "location": "/about/release-notes/#version-0120-2015-04-14", - "text": "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\n 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\n 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\n 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\n pages. (#150) Bugfix: Remove the site_name from the page title, this needs to be added\n 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\n 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\n fix problems with titles containing code. (#367) Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden\n 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\n 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)", + "location": "/about/release-notes/#version-0120-2015-04-14", + "text": "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\n 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\n 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\n 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\n pages. (#150) Bugfix: Remove the site_name from the page title, this needs to be added\n 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\n 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\n fix problems with titles containing code. (#367) Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden\n 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\n 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)", "title": "Version 0.12.0 (2015-04-14)" - }, + }, { - "location": "/about/release-notes/#version-0111-2014-11-20", - "text": "Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs\n theme. (#233)", + "location": "/about/release-notes/#version-0111-2014-11-20", + "text": "Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs\n theme. (#233)", "title": "Version 0.11.1 (2014-11-20)" - }, + }, { - "location": "/about/release-notes/#version-0110-2014-11-18", - "text": "Render 404.html files if they exist for the current theme. (#194) Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs\n 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\n the MkDocs theme. (#183) Bugfix: Display section titles in the ReadTheDocs theme. (#175) Bugfix: Use the polling observer in watchdog so rebuilding works on\n filesystems without inotify. (#184) Bugfix: Improve error output for common configuration related errors. (#176)", + "location": "/about/release-notes/#version-0110-2014-11-18", + "text": "Render 404.html files if they exist for the current theme. (#194) Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs\n 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\n the MkDocs theme. (#183) Bugfix: Display section titles in the ReadTheDocs theme. (#175) Bugfix: Use the polling observer in watchdog so rebuilding works on\n filesystems without inotify. (#184) Bugfix: Improve error output for common configuration related errors. (#176)", "title": "Version 0.11.0 (2014-11-18)" - }, + }, { - "location": "/about/release-notes/#version-0100-2014-10-29", - "text": "Added support for Python 3.3 and 3.4. (#103) Configurable Python-Markdown extensions with the config setting\n markdown_extensions . (#74) Added mkdocs json command to output your rendered\n documentation as json files. (#128) Added --clean switch to build , json and gh-deploy commands to\n remove stale files from the output directory. (#157) Support multiple theme directories to allow replacement of\n 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)", + "location": "/about/release-notes/#version-0100-2014-10-29", + "text": "Added support for Python 3.3 and 3.4. (#103) Configurable Python-Markdown extensions with the config setting\n markdown_extensions . (#74) Added mkdocs json command to output your rendered\n documentation as json files. (#128) Added --clean switch to build , json and gh-deploy commands to\n remove stale files from the output directory. (#157) Support multiple theme directories to allow replacement of\n individual templates rather than copying the full theme. (#129) Bugfix: Fix
        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)", "title": "Version 0.10.0 (2014-10-29)" - }, + }, { - "location": "/about/contributing/", - "text": "Contributing to MkDocs\n\uf0c1\n\n\nAn introduction to contributing to the MkDocs project.\n\n\nThe 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\n\n\nCode patches via pull requests\n\n\nDocumentation improvements\n\n\nBug reports and patch reviews\n\n\n\n\nCode of Conduct\n\uf0c1\n\n\nEveryone interacting in the MkDocs project's codebases, issue trackers, chat\nrooms, and mailing lists is expected to follow the \nPyPA Code of Conduct\n.\n\n\nReporting an Issue\n\uf0c1\n\n\nPlease 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 full error and\ntraceback.\n\n\nTesting the Development Version\n\uf0c1\n\n\nIf 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 \nstrongly\n recommended\nthat you do this within a \nvirtualenv\n.\n\n\npip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz\n\n\n\n\nInstalling for Development\n\uf0c1\n\n\nFirst you'll need to fork and clone the repository. Once you have a local\ncopy, run the following command. It is \nstrongly\n recommended that you do\nthis within a \nvirtualenv\n.\n\n\npip install --editable .\n\n\n\n\nThis will install MkDocs in development mode which binds the \nmkdocs\n command\nto the git repository.\n\n\nRunning the tests\n\uf0c1\n\n\nTo run the tests, it is recommended that you use \nTox\n. This just needs\nto be pip installed and then the test suite can be ran for MkDocs but running\nthe command \ntox\n in the root of your MkDocs repository.\n\n\nIt 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 \nTravis\n when you submit a pull request.\n\n\nSubmitting Pull Requests\n\uf0c1\n\n\nOnce 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.", + "location": "/about/contributing/", + "text": "Contributing to MkDocs\n\uf0c1\n\n\nAn introduction to contributing to the MkDocs project.\n\n\nThe 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\n\n\nCode patches via pull requests\n\n\nDocumentation improvements\n\n\nBug reports and patch reviews\n\n\n\n\nCode of Conduct\n\uf0c1\n\n\nEveryone interacting in the MkDocs project's codebases, issue trackers, chat\nrooms, and mailing lists is expected to follow the \nPyPA Code of Conduct\n.\n\n\nReporting an Issue\n\uf0c1\n\n\nPlease 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 full error and\ntraceback.\n\n\nTesting the Development Version\n\uf0c1\n\n\nIf 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 \nstrongly\n recommended\nthat you do this within a \nvirtualenv\n.\n\n\npip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz\n\n\n\n\nInstalling for Development\n\uf0c1\n\n\nFirst you'll need to fork and clone the repository. Once you have a local\ncopy, run the following command. It is \nstrongly\n recommended that you do\nthis within a \nvirtualenv\n.\n\n\npip install --editable .\n\n\n\n\nThis will install MkDocs in development mode which binds the \nmkdocs\n command\nto the git repository.\n\n\nRunning the tests\n\uf0c1\n\n\nTo run the tests, it is recommended that you use \nTox\n. This just needs\nto be pip installed and then the test suite can be ran for MkDocs but running\nthe command \ntox\n in the root of your MkDocs repository.\n\n\nIt 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 \nTravis\n when you submit a pull request.\n\n\nSubmitting Pull Requests\n\uf0c1\n\n\nOnce 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.", "title": "Contributing" - }, + }, { - "location": "/about/contributing/#contributing-to-mkdocs", - "text": "An introduction to contributing to the MkDocs project. 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: Code patches via pull requests Documentation improvements Bug reports and patch reviews", + "location": "/about/contributing/#contributing-to-mkdocs", + "text": "An introduction to contributing to the MkDocs project. 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: Code patches via pull requests Documentation improvements Bug reports and patch reviews", "title": "Contributing to MkDocs" - }, + }, { - "location": "/about/contributing/#code-of-conduct", - "text": "Everyone interacting in the MkDocs project's codebases, issue trackers, chat\nrooms, and mailing lists is expected to follow the PyPA Code of Conduct .", + "location": "/about/contributing/#code-of-conduct", + "text": "Everyone interacting in the MkDocs project's codebases, issue trackers, chat\nrooms, and mailing lists is expected to follow the PyPA Code of Conduct .", "title": "Code of Conduct" - }, + }, { - "location": "/about/contributing/#reporting-an-issue", - "text": "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 full error and\ntraceback.", + "location": "/about/contributing/#reporting-an-issue", + "text": "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 full error and\ntraceback.", "title": "Reporting an Issue" - }, + }, { - "location": "/about/contributing/#testing-the-development-version", - "text": "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 . pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz", + "location": "/about/contributing/#testing-the-development-version", + "text": "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 . pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz", "title": "Testing the Development Version" - }, + }, { - "location": "/about/contributing/#installing-for-development", - "text": "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 . pip install --editable . This will install MkDocs in development mode which binds the mkdocs command\nto the git repository.", + "location": "/about/contributing/#installing-for-development", + "text": "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 . pip install --editable . This will install MkDocs in development mode which binds the mkdocs command\nto the git repository.", "title": "Installing for Development" - }, + }, { - "location": "/about/contributing/#running-the-tests", - "text": "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. 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.", + "location": "/about/contributing/#running-the-tests", + "text": "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. 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.", "title": "Running the tests" - }, + }, { - "location": "/about/contributing/#submitting-pull-requests", - "text": "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.", + "location": "/about/contributing/#submitting-pull-requests", + "text": "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.", "title": "Submitting Pull Requests" - }, + }, { - "location": "/about/license/", - "text": "License\n\uf0c1\n\n\nThe legal stuff.\n\n\n\n\nIncluded projects\n\uf0c1\n\n\nThemes used under license from the ReadTheDocs projects.\n\n\n\n\nReadTheDocs theme - \nView license\n.\n\n\n\n\nMany thanks to the authors and contributors of those wonderful projects.\n\n\nMkDocs License (BSD)\n\uf0c1\n\n\nCopyright \u00a9 2014, Tom Christie. All rights reserved.\n\n\nRedistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:\n\n\nRedistributions 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\n\nTHIS 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.", + "location": "/about/license/", + "text": "License\n\uf0c1\n\n\nThe legal stuff.\n\n\n\n\nIncluded projects\n\uf0c1\n\n\nThemes used under license from the ReadTheDocs projects.\n\n\n\n\nReadTheDocs theme - \nView license\n.\n\n\n\n\nMany thanks to the authors and contributors of those wonderful projects.\n\n\nMkDocs License (BSD)\n\uf0c1\n\n\nCopyright \u00a9 2014, Tom Christie. All rights reserved.\n\n\nRedistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:\n\n\nRedistributions 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\n\nTHIS 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.", "title": "License" - }, + }, { - "location": "/about/license/#license", - "text": "The legal stuff.", + "location": "/about/license/#license", + "text": "The legal stuff.", "title": "License" - }, + }, { - "location": "/about/license/#included-projects", - "text": "Themes used under license from the ReadTheDocs projects. ReadTheDocs theme - View license . Many thanks to the authors and contributors of those wonderful projects.", + "location": "/about/license/#included-projects", + "text": "Themes used under license from the ReadTheDocs projects. ReadTheDocs theme - View license . Many thanks to the authors and contributors of those wonderful projects.", "title": "Included projects" - }, + }, { - "location": "/about/license/#mkdocs-license-bsd", - "text": "Copyright \u00a9 2014, Tom Christie. All rights reserved. Redistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met: 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. 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.", + "location": "/about/license/#mkdocs-license-bsd", + "text": "Copyright \u00a9 2014, Tom Christie. All rights reserved. Redistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met: 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. 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.", "title": "MkDocs License (BSD)" } ] diff --git a/sitemap.xml b/sitemap.xml index 51e57a6e..858b8251 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -4,7 +4,7 @@ http://www.mkdocs.org/ - 2016-11-04 + 2016-12-22 daily @@ -13,31 +13,31 @@ http://www.mkdocs.org/user-guide/writing-your-docs/ - 2016-11-04 + 2016-12-22 daily http://www.mkdocs.org/user-guide/styling-your-docs/ - 2016-11-04 + 2016-12-22 daily http://www.mkdocs.org/user-guide/configuration/ - 2016-11-04 + 2016-12-22 daily http://www.mkdocs.org/user-guide/deploying-your-docs/ - 2016-11-04 + 2016-12-22 daily http://www.mkdocs.org/user-guide/custom-themes/ - 2016-11-04 + 2016-12-22 daily @@ -47,19 +47,19 @@ http://www.mkdocs.org/about/release-notes/ - 2016-11-04 + 2016-12-22 daily http://www.mkdocs.org/about/contributing/ - 2016-11-04 + 2016-12-22 daily http://www.mkdocs.org/about/license/ - 2016-11-04 + 2016-12-22 daily diff --git a/user-guide/configuration/index.html b/user-guide/configuration/index.html index 5346f7a6..6397a006 100644 --- a/user-guide/configuration/index.html +++ b/user-guide/configuration/index.html @@ -226,7 +226,7 @@ Pages. This option can be overridden by a command line option in gh-deploy

        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: gh-pages

        +

        default: origin

        Documentation layout

        pages

        This setting is used to determine the set of pages that should be built for the