MkDocs Lunr.js version comparison

lunr1vs2.js

/**
 * Comparison between lunr1 and lunr2 searching based on MkDocs search index JSON
 *
 * Install both versions of lunr:
 * 1. install Yarn `npm i -g yarn`
 * 2. yarn add lunr1@npm:[email protected]
 * 3. yarn add lunr@latest
 *
 * `search_index.json` should available in the same directory as this script
 * Run `node test.js`
 */

const lunr = require('lunr')
const lunr1 = require('lunr1')
const fs = require('fs')
const readline = require('readline')
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  terminal: false
})
rl.on('line', function(line){
  searchLunr1(line)
  searchLunr2(line)
})

let documents = {}
let data = JSON.parse(fs.readFileSync('./search_index.json'))
let indexLunr1 = lunr1(function () {
  this.field('title', {boost: 10})
  this.field('text')
  this.ref('location')
})
for (doc of data.docs){
    indexLunr1.add(doc)
    documents[doc.location] = doc
}

var indexLunr2 = lunr(function () {
  this.field('title')
  this.field('text')
  this.ref('location')
  for (doc of data.docs){
      this.add(doc)
  }
})

console.log('Please enter search terms:')

function searchLunr2(queryText) {
  console.log(`Lunr 2.x - searching for: "${queryText}"`);
  results = indexLunr2.query(function () {
    for (term of queryText.split(' ')) {
      this.term(term, { fields: ['title'], boost: 10 })
      this.term(term, { fields: ['title'], boost: 10 })
      this.term(term, { fields: ['text'] })
      this.term(term, { fields: ['text'] })
    }
  })
  for (result of results.slice(0, 3)) {
    let doc = documents[result.ref]
    console.log(`[${result.score}]: ${result.ref}`)
    console.log(`Title: ${doc.title}`)
  }
  console.log('\n\nPlease enter search terms:')
}

function searchLunr1(query) {
  console.log(`Lunr 1.0.0 - searching for: "${query}"`);
  results = indexLunr1.search(query)
  for (result of results.slice(0, 3)) {
    let doc = documents[result.ref]
    console.log(`[${result.score}]: ${result.ref}`)
    console.log(`Title: ${doc.title}`)
  }
  console.log('\n\nPlease enter search terms:')
}

search_index.json

{
    "docs": [
        {
            "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.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 would like manpages installed for MkDocs, the \nclick-man\n tool can\ngenerate and install them for you. Simply run the following two commands:\n\n\npip install click-man\nclick-man --target path/to/man/pages mkdocs\n\n\n\nSee the \nclick-man documentation\n for an explaination of why manpages are\nnot automaticaly generated and installed by pip.\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 automatically 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 its\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\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.",
            "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.",
            "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 .",
            "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.",
            "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.",
            "title": "Easy to customize"
        },
        {
            "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 ,  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.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).",
            "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",
            "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 would like manpages installed for MkDocs, the  click-man  tool can\ngenerate and install them for you. Simply run the following two commands:  pip install click-man\nclick-man --target path/to/man/pages mkdocs  See the  click-man documentation  for an explaination of why manpages are\nnot automaticaly generated and installed by pip.    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.",
            "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!",
            "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.",
            "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 automatically 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 its\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",
            "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.",
            "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.",
            "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 differently.\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.",
            "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 differently.  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.",
            "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/",
            "title": "File layout"
        },
        {
            "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.",
            "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.",
            "title": "Images and media"
        },
        {
            "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",
            "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```",
            "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 [theme directory][theme_dir]. You\ncan also create your own \ncustom theme\n from the ground 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\nThe default theme, which was built as a custom \nBootstrap\n theme, supports most\nevery feature of MkDocs. It only supports the default\n\ntheme configuration options\n.\n\n\n\n\nreadthedocs\n\uf0c1\n\n\nA clone of the default theme used by the \nRead the Docs\n service. This theme\nonly supports features in its parent theme and does not support any MkDocs\n\ntheme configuration options\n in addition to the defaults.\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 theme\n\ncustom_dir\n setting.\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\ntheme \ncustom_dir\n.\n\n\n\n\nUsing the theme custom_dir\n\uf0c1\n\n\nThe theme.\ncustom_dir\n configuration option can be used to point to a directory\nof files which override the files in a parent theme. The parent theme would be\nthe theme defined in the theme.\nname\n configuration option. Any file in the\n\ncustom_dir\n with the same name as a file in the parent theme will replace the\nfile of the same name in the parent theme. Any additional files in the\n\ncustom_dir\n will be added to the parent theme. The contents of the \ncustom_dir\n\nshould mirror the directory structure of the parent theme. You may include\ntemplates, JavaScript files, CSS files, images, fonts, or any other media\nincluded in a theme.\n\n\n\n\nNote\n\n\nFor this to work, the theme \nname\n setting must be set to a known installed theme.\nIf the \nname\n setting is instead set to \nnull\n (or not defined), then there\nis no theme to override and the contents of the \ncustom_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:\n    name: mkdocs\n    custom_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 parent theme (defined in \nname\n) but not included\nin the \ncustom_dir\n will still be utilized. The \ncustom_dir\n will only\noverride/replace files in the parent theme. If you want to remove files, or\nbuild a theme from scratch, then you should review the documentation for\nbuilding 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 \ncustom_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 %}\n<title>Custom title goes here</title>\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<head>\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\nexplanation of blocks, consult the \nJinja documentation\n.\n\n\nCombining the custom_dir and Template Blocks\n\uf0c1\n\n\nAdding a JavaScript library to the \ncustom_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    <script src=\"{{ base_url }}/js/somelib.js\"></script>\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 \ncustom_dir\n. The same would be required for\nany additional CSS files included in the \ncustom_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][theme_dir]. You\ncan also create your own  custom theme  from the ground 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": "",
            "title": "Built-in themes"
        },
        {
            "location": "/user-guide/styling-your-docs/#mkdocs",
            "text": "The default theme, which was built as a custom  Bootstrap  theme, supports most\nevery feature of MkDocs. It only supports the default theme configuration options .",
            "title": "mkdocs"
        },
        {
            "location": "/user-guide/styling-your-docs/#readthedocs",
            "text": "A clone of the default theme used by the  Read the Docs  service. This theme\nonly supports features in its parent theme and does not support any MkDocs theme configuration options  in addition to the defaults.",
            "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.",
            "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 custom_dir  setting.",
            "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\ntheme  custom_dir .",
            "title": "Using the docs_dir"
        },
        {
            "location": "/user-guide/styling-your-docs/#using-the-theme-custom_dir",
            "text": "The theme. custom_dir  configuration option can be used to point to a directory\nof files which override the files in a parent theme. The parent theme would be\nthe theme defined in the theme. name  configuration option. Any file in the custom_dir  with the same name as a file in the parent theme will replace the\nfile of the same name in the parent theme. Any additional files in the custom_dir  will be added to the parent theme. The contents of the  custom_dir \nshould mirror the directory structure of the parent theme. You may include\ntemplates, JavaScript files, CSS files, images, fonts, or any other media\nincluded in a theme.   Note  For this to work, the theme  name  setting must be set to a known installed theme.\nIf the  name  setting is instead set to  null  (or not defined), then there\nis no theme to override and the contents of the  custom_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:\n    name: mkdocs\n    custom_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 parent theme (defined in  name ) but not included\nin the  custom_dir  will still be utilized. The  custom_dir  will only\noverride/replace files in the parent theme. If you want to remove files, or\nbuild a theme from scratch, then you should review the documentation for\nbuilding a  custom theme .",
            "title": "Using the theme custom_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  custom_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 %}\n<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\nexplanation of blocks, consult the  Jinja documentation .",
            "title": "Overriding Template Blocks"
        },
        {
            "location": "/user-guide/styling-your-docs/#combining-the-custom_dir-and-template-blocks",
            "text": "Adding a JavaScript library to the  custom_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  custom_dir . The same would be required for\nany additional CSS files included in the  custom_dir .",
            "title": "Combining the custom_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, and if your theme supports it, provides a link directly to the page in\nyour source repository. This makes it easier to find and edit the source for the\npage. If \nrepo_url\n is not set, this option is ignored. On some themes, setting\nthis option may cause an edit link to be used in place of a repository link.\nOther themes may show both links.\n\n\nThe \nedit_uri\n supports query ('?') and fragment ('#') characters. For\nrepository hosts that use a query or a fragment to access the files, the\n\nedit_uri\n might be set as follows. (Note the \n?\n and \n#\n in the URI...)\n\n\n# Query string example\nedit_uri: '?query=root/path/docs/'\n\n\n\n\n# Hash fragment example\nedit_uri: '#root/path/docs/'\n\n\n\n\nFor other repository hosts, simply specify the relative path to the docs\ndirectory.\n\n\n# Query string example\nedit_uri: root/path/docs/\n\n\n\n\n\n\nNote\n\n\nOn a few known hosts (specifically GitHub and Bitbucket), the \nedit_uri\n is\nderived from the 'repo_url' and does not need to be set manually. Simply\ndefining a \nrepo_url\n will automatically populate the \nedit_uri\n config\nsetting.\n\n\nFor example, for a GitHub-hosted repository, the \nedit_uri\n would be\nautomatically set as \nedit/master/docs/\n (Note the \nedit\n path and \nmaster\n\nbranch).\n\n\nFor a Bitbucket-hosted repository, the equivalent \nedit_uri\n would be\nautomatically set as \nsrc/default/docs/\n (note the \nsrc\n path and \ndefault\n\nbranch).\n\n\nTo use a different URI than the default (for example a different branch),\nsimply set the \nedit_uri\n to your desired string. If you do not want any\n\"edit URL link\" displayed on your pages, then set \nedit_uri\n to an empty\nstring to disable the automatic setting.\n\n\n\n\n\n\nWarning\n\n\nOn GitHub, the default \"edit\" path (\nedit/master/docs/\n) opens the page in\nthe online GitHub editor. This functionality requires that the user have and\nbe logged in to a GitHub account. Otherwise, the user will be redirected to\na login/signup page. Alternatively, use the \"blob\" path\n(\nblob/master/docs/\n) to open a read-only view, which supports anonymous\naccess.\n\n\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\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 and theme specific configuration of your documentation site.\nMay be either a string or a set of key/value pairs.\n\n\nIf a string, it must be the string name of a known installed theme. For a list\nof available themes visit \nstyling your docs\n.\n\n\nAn example set of key/value pairs might look something like this:\n\n\ntheme:\n    name: mkdocs\n    custom_dir: my_theme_customizations/\n    static_templates:\n        - sitemap.html\n    include_sidebar: false\n\n\n\n\nIf a set of key/value pairs, the following nested keys can be defined:\n\n\n\n\nname:\n\uf0c1\n\n\nThe string name of a known installed theme. For a list of available themes\nvisit \nstyling your docs\n.\n\n\ncustom_dir:\n\uf0c1\n\n\nA directory to custom a theme. This can either be a relative directory, in\nwhich case it is resolved relative to the directory containing your\nconfiguration 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\nground up.\n\n\nstatic_templates:\n\uf0c1\n\n\nA list of templates to render as static pages. The templates must be located\nin either the theme's template directory or in the \ncustom_dir\n defined in\nthe theme configuration.\n\n\n(theme specific keywords)\n\uf0c1\n\n\nAny additional keywords supported by the theme can also be defined. See the\ndocumentation for the theme you are using for details.\n\n\n\n\ndefault\n: \n'mkdocs'\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 your configuration file, or it can be an absolute\ndirectory path from the root of your local file system.\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 your configuration file, or it can be an absolute\ndirectory path from the root of your local file system.\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 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. Must be of the format\n\nIP:PORT\n.\n\n\nAllows a custom default to be set without the need to pass it through the\n\n--dev_addr\n option every time the \nmkdocs serve\n command is called.\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 separated by a colon. If you\nwould like to define multiple options for a single extension, each option must be\ndefined on a separate 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[]\n (an empty list).\n\n\nplugins\n\uf0c1\n\n\nA list of plugins (with optional configuration settings) to use when building\nthe site . See the \nPlugins\n documentation for full details.\n\n\nIf the \nplugins\n config setting is defined in the \nmkdocs.yml\n config file, then\nany defaults (such as \nsearch\n) are ignored and you need to explicitly re-enable\nthe defaults if you would like to continue using them:\n\n\nplugins:\n    - search\n    - your_other_plugin\n\n\n\n\nTo completely disable all plugins, including any defaults, set the \nplugins\n\nsetting to an empty list:\n\n\nplugins: []\n\n\n\n\ndefault\n: \n['search']\n (the \"search\" plugin included with MkDocs).",
            "title": "Configuration"
        },
        {
            "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.",
            "title": "Introduction"
        },
        {
            "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.",
            "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",
            "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",
            "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",
            "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, and if your theme supports it, provides a link directly to the page in\nyour source repository. This makes it easier to find and edit the source for the\npage. If  repo_url  is not set, this option is ignored. On some themes, setting\nthis option may cause an edit link to be used in place of a repository link.\nOther themes may show both links.  The  edit_uri  supports query ('?') and fragment ('#') characters. For\nrepository hosts that use a query or a fragment to access the files, the edit_uri  might be set as follows. (Note the  ?  and  #  in the URI...)  # Query string example\nedit_uri: '?query=root/path/docs/'  # Hash fragment example\nedit_uri: '#root/path/docs/'  For other repository hosts, simply specify the relative path to the docs\ndirectory.  # Query string example\nedit_uri: root/path/docs/   Note  On a few known hosts (specifically GitHub and Bitbucket), the  edit_uri  is\nderived from the 'repo_url' and does not need to be set manually. Simply\ndefining a  repo_url  will automatically populate the  edit_uri  config\nsetting.  For example, for a GitHub-hosted repository, the  edit_uri  would be\nautomatically set as  edit/master/docs/  (Note the  edit  path and  master \nbranch).  For a Bitbucket-hosted repository, the equivalent  edit_uri  would be\nautomatically set as  src/default/docs/  (note the  src  path and  default \nbranch).  To use a different URI than the default (for example a different branch),\nsimply set the  edit_uri  to your desired string. If you do not want any\n\"edit URL link\" displayed on your pages, then set  edit_uri  to an empty\nstring to disable the automatic setting.    Warning  On GitHub, the default \"edit\" path ( edit/master/docs/ ) opens the page in\nthe online GitHub editor. This functionality requires that the user have and\nbe logged in to a GitHub account. Otherwise, the user will be redirected to\na login/signup page. Alternatively, use the \"blob\" path\n( blob/master/docs/ ) to open a read-only view, which supports anonymous\naccess.   default :  edit/master/docs/  or  src/default/docs/  for GitHub or Bitbucket\nrepos, respectively, if  repo_url  matches those domains, otherwise  null",
            "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",
            "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",
            "title": "site_author"
        },
        {
            "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",
            "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",
            "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 :  origin",
            "title": "remote_name"
        },
        {
            "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).",
            "title": "pages"
        },
        {
            "location": "/user-guide/configuration/#build-directories",
            "text": "",
            "title": "Build directories"
        },
        {
            "location": "/user-guide/configuration/#theme",
            "text": "Sets the theme and theme specific configuration of your documentation site.\nMay be either a string or a set of key/value pairs.  If a string, it must be the string name of a known installed theme. For a list\nof available themes visit  styling your docs .  An example set of key/value pairs might look something like this:  theme:\n    name: mkdocs\n    custom_dir: my_theme_customizations/\n    static_templates:\n        - sitemap.html\n    include_sidebar: false  If a set of key/value pairs, the following nested keys can be defined:",
            "title": "theme"
        },
        {
            "location": "/user-guide/configuration/#name",
            "text": "The string name of a known installed theme. For a list of available themes\nvisit  styling your docs .",
            "title": "name:"
        },
        {
            "location": "/user-guide/configuration/#custom_dir",
            "text": "A directory to custom a theme. This can either be a relative directory, in\nwhich case it is resolved relative to the directory containing your\nconfiguration 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\nground up.",
            "title": "custom_dir:"
        },
        {
            "location": "/user-guide/configuration/#static_templates",
            "text": "A list of templates to render as static pages. The templates must be located\nin either the theme's template directory or in the  custom_dir  defined in\nthe theme configuration.",
            "title": "static_templates:"
        },
        {
            "location": "/user-guide/configuration/#theme-specific-keywords",
            "text": "Any additional keywords supported by the theme can also be defined. See the\ndocumentation for the theme you are using for details.   default :  'mkdocs'",
            "title": "(theme specific keywords)"
        },
        {
            "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 your configuration file, or it can be an absolute\ndirectory path from the root of your local file system.  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 your configuration file, or it can be an absolute\ndirectory path from the root of your local file system.  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 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).",
            "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).",
            "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.",
            "title": "extra"
        },
        {
            "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",
            "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",
            "title": "strict"
        },
        {
            "location": "/user-guide/configuration/#dev_addr",
            "text": "Determines the address used when running  mkdocs serve . Must be of the format IP:PORT .  Allows a custom default to be set without the need to pass it through the --dev_addr  option every time the  mkdocs serve  command is called.  default :  '127.0.0.1:8000'",
            "title": "dev_addr"
        },
        {
            "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 separated by a colon. If you\nwould like to define multiple options for a single extension, each option must be\ndefined on a separate 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 :  []  (an empty list).",
            "title": "markdown_extensions"
        },
        {
            "location": "/user-guide/configuration/#plugins",
            "text": "A list of plugins (with optional configuration settings) to use when building\nthe site . See the  Plugins  documentation for full details.  If the  plugins  config setting is defined in the  mkdocs.yml  config file, then\nany defaults (such as  search ) are ignored and you need to explicitly re-enable\nthe defaults if you would like to continue using them:  plugins:\n    - search\n    - your_other_plugin  To completely disable all plugins, including any defaults, set the  plugins \nsetting to an empty list:  plugins: []  default :  ['search']  (the \"search\" plugin included with MkDocs).",
            "title": "plugins"
        },
        {
            "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\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",
            "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.",
            "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.",
            "title": "Read the Docs"
        },
        {
            "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.",
            "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 template\n\nfile. This should be placed in a directory which will be the \ncustom_dir\n and it\nshould be created next to the \nmkdocs.yml\n configuration file. Within\n\nmkdocs.yml\n, specify the theme \ncustom_dir\n option and set it to the name of\nthe directory containing \nmain.html\n. For example, given this example project\nlayout:\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:\n    name: null\n    custom_dir: 'custom_theme'\n\n\n\n\n\nNote\n\n\nGenerally, when building your own custom theme, the theme \nname\n\nconfiguration setting would be set to \nnull\n. However, if used in\ncombination with the \ncustom_dir\n configuration value a custom theme can be\nused to replace only specific parts of a built-in theme. For example, with\nthe above layout and if you set \nname: \"mkdocs\"\n then the \nmain.html\n file\nin the \ncustom_dir\n would replace that in the theme but otherwise the\n\nmkdocs\n theme would remain the same. This is useful if you want to make\nsmall adjustments to an existing 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<html>\n  <head>\n    <title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>\n  </head>\n  <body>\n    {{ content }}\n  </body>\n</html>\n\n\n\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 theme [custom_dir]. 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    <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 %}\n\n\n\n\nThe \nnav\n object also contains a \nhomepage\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<script src=\"{{ base_url }}/js/theme.js\"></script>\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<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 %}\n</ul>\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  <a class=\"github\" href=\"https://github.com/.../{{ filename }}\">\n    <span class=\"label label-info\">{{ filename }}</span>\n  </a>\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  <ul>\n  {% for link in config.extra.links %}\n      <li>{{ link }}</li>\n  {% endfor %}\n  </ul>\n{% endif %}\n\n\n\n\nSearch and themes\n\uf0c1\n\n\nAs of MkDocs \n0.17\n client side search support has been added to MkDocs via the\n\nsearch\n plugin. A theme needs to provide a few things for the plugin to work\nwith the theme.\n\n\nWhile the \nsearch\n plugin is activated by default, users can disable the plugin\nand themes should acount for this. It is recomended that theme templates wrap\nsearch specific markup with a check for the plugin:\n\n\n{% if 'search' in config['plugins'] %}\n    search stuff here...\n{% endif %}\n\n\n\n\nAt its most basic functionality, the search plugin will simply provide an index\nfile which is no more than a JSON file containing the content of all pages.\nThe theme would need to implement its own search functionality client-side.\nHowever, with a few settings and the necessary templates, the plugin can provide\na complete functioning client-side search tool based on \nlunr.js\n.\n\n\nThe following options can be set in the \ntheme's configuration file\n,\n\nmkdocs_theme.yml\n:\n\n\ninclude_search_page\n\uf0c1\n\n\nDetermines whether the search plugin expects the theme to provide a dedicated\nsearch page via a template located at \nsearch/search.html\n.\n\n\nWhen \ninclude_search_page\n is set to \ntrue\n, the search template will be built\nand available at \nsearch/search.html\n. This method is used by the \nreadthedocs\n\ntheme.\n\n\nWhen \ninclude_search_page\n is set to \nfalse\n or not defined, it is expected that\nthe theme provide some other mechanisms for displaying search results. For\nexample, the \nmkdocs\n theme displays results on any page via a modal.\n\n\nsearch_index_only\n\uf0c1\n\n\nDetermines whether the search plugin should only generate a search index or a\ncomplete search solution.\n\n\nWhen \nsearch_index_only\n is set to \ntrue\n or not defined, the search plugin\nmakes no modifications to the Jinja environment. A complete solution using the\nprovided index file is the responsability of the theme.\n\n\nWhen \nsearch_index_only\n is set to \nfalse\n, then the search plugin modifies the\nJinja environment by adding its own \ntemplates\n directory (with a lower\nprecedence than the theme) and adds its scripts to the \nextra_javascript\n config\nsetting.\n\n\nThe following HTML needs to be added to the theme so that the provided\nJavaScript is able to properly load Lunr.js and make relative links to the\nsearch results from the current page.\n\n\n<script>var base_url = '{{ base_url }}';</script>\n\n\n\n\n\n\nNote\n\n\nThe provided 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 \nsearch_index_only: true\n to only include\nsearch on one page or load the JavaScript on an event like a form submit.\n\n\n\n\nThe following HTML in a \nsearch/search.html\n template will add a full search\nimplementation to your theme.\n\n\n<h1 id=\"search\">Search Results</h1>\n\n<form action=\"search.html\">\n  <input name=\"q\" id=\"mkdocs-search-query\" type=\"text\" >\n</form>\n\n<div id=\"mkdocs-search-results\">\n  Sorry, page not found.\n</div>\n\n\n\n\nThe JavaScript in the plugin works by looking for the specific ID's used in the\nabove HTML. The input for the user to type the search query must have the ID\n\nmkdocs-search-query\n and \nmkdocs-search-results\n is the div where the results\nwill 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 \ncustom_dir\n. If you have created a \"one-off theme,\"\nthat should be sufficient. 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 then take\nadvantage of the [custom_dir] 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 and \nsetup.py\n beside the theme directory which\ncontains an empty \n__init__.py\n file, a theme configuration file\n(\nmkdocs-theme.yml\n), and your template and media files.\n\n\n.\n|-- MANIFEST.in\n|-- theme_name\n|   |-- __init__.py\n|   |-- mkdocs-theme.yml\n|   |-- main.html\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\nTheme Configuration\n\uf0c1\n\n\nA packaged theme is required to include a configuration file named\n\nmkdocs_theme.yml\n which is placed in the root of your template files. The file\nshould contain default configuration options for the theme. However, if the\ntheme offers no configuration options, the file is still required and can be\nleft blank.\n\n\nThe theme author is free to define any arbitrary options deemed necessary and\nthose options will be made available in the templates to control behavior.\nFor example, a theme might want to make a sidebar optional and include the\nfollowing in the \nmkdocs_theme.yml\n file:\n\n\nshow_sidebar: true\n\n\n\n\nThen in a template, that config option could be referenced:\n\n\n{% if config.theme.show_sidebar %}\n<div id=\"sidebar\">...</div>\n{% endif %}\n\n\n\n\nAnd the user could override the default in their project's \nmkdocs.yml\n config\nfile:\n\n\ntheme:\n    name: themename\n    show_sidebar: false\n\n\n\n\nIn addition to arbitrary options defined by the theme, MkDocs defines a few\nspecial options which alters its behavior:\n\n\n\n\nstatic_templates\n\uf0c1\n\n\nThis option mirrors the \ntheme\n config option of the same name and allows\nsome defaults to be set by the theme. Note that while the user can add\ntemplates to this list, the user cannot remove templates included in the\ntheme's config.\n\n\nextends\n\uf0c1\n\n\nDefines a parent theme that this theme inherits from. The value should be\nthe string name of the parent theme. Normal Jinja inheritance rules apply.\n\n\n\n\nPlugins may also define some options which allow the theme to inform a plugin\nabout which set of plugin options it expects. See the documentation for any\nplugins you may wish to support in your theme.\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.",
            "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 template \nfile. This should be placed in a directory which will be the  custom_dir  and it\nshould be created next to the  mkdocs.yml  configuration file. Within mkdocs.yml , specify the theme  custom_dir  option and set it to the name of\nthe directory containing  main.html . For example, given this example project\nlayout:  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:\n    name: null\n    custom_dir: 'custom_theme'   Note  Generally, when building your own custom theme, the theme  name \nconfiguration setting would be set to  null . However, if used in\ncombination with the  custom_dir  configuration value a custom theme can be\nused to replace only specific parts of a built-in theme. For example, with\nthe above layout and if you set  name: \"mkdocs\"  then the  main.html  file\nin the  custom_dir  would replace that in the theme but otherwise the mkdocs  theme would remain the same. This is useful if you want to make\nsmall adjustments to an existing 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>\n<html>\n  <head>\n    <title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>\n  </head>\n  <body>\n    {{ content }}\n  </body>\n</html>  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 [custom_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.",
            "title": "Template Variables"
        },
        {
            "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",
            "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  homepage  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>",
            "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.",
            "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.",
            "title": "extra_javascript"
        },
        {
            "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.",
            "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:",
            "title": "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.",
            "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 %}\n</ul>",
            "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 %}",
            "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.",
            "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.",
            "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.",
            "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 }}",
            "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 .",
            "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 .",
            "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 %}",
            "title": "Extra Context"
        },
        {
            "location": "/user-guide/custom-themes/#search-and-themes",
            "text": "As of MkDocs  0.17  client side search support has been added to MkDocs via the search  plugin. A theme needs to provide a few things for the plugin to work\nwith the theme.  While the  search  plugin is activated by default, users can disable the plugin\nand themes should acount for this. It is recomended that theme templates wrap\nsearch specific markup with a check for the plugin:  {% if 'search' in config['plugins'] %}\n    search stuff here...\n{% endif %}  At its most basic functionality, the search plugin will simply provide an index\nfile which is no more than a JSON file containing the content of all pages.\nThe theme would need to implement its own search functionality client-side.\nHowever, with a few settings and the necessary templates, the plugin can provide\na complete functioning client-side search tool based on  lunr.js .  The following options can be set in the  theme's configuration file , mkdocs_theme.yml :",
            "title": "Search and themes"
        },
        {
            "location": "/user-guide/custom-themes/#include_search_page",
            "text": "Determines whether the search plugin expects the theme to provide a dedicated\nsearch page via a template located at  search/search.html .  When  include_search_page  is set to  true , the search template will be built\nand available at  search/search.html . This method is used by the  readthedocs \ntheme.  When  include_search_page  is set to  false  or not defined, it is expected that\nthe theme provide some other mechanisms for displaying search results. For\nexample, the  mkdocs  theme displays results on any page via a modal.",
            "title": "include_search_page"
        },
        {
            "location": "/user-guide/custom-themes/#search_index_only",
            "text": "Determines whether the search plugin should only generate a search index or a\ncomplete search solution.  When  search_index_only  is set to  true  or not defined, the search plugin\nmakes no modifications to the Jinja environment. A complete solution using the\nprovided index file is the responsability of the theme.  When  search_index_only  is set to  false , then the search plugin modifies the\nJinja environment by adding its own  templates  directory (with a lower\nprecedence than the theme) and adds its scripts to the  extra_javascript  config\nsetting.  The following HTML needs to be added to the theme so that the provided\nJavaScript is able to properly load Lunr.js and make relative links to the\nsearch results from the current page.  <script>var base_url = '{{ base_url }}';</script>   Note  The provided 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  search_index_only: true  to only include\nsearch on one page or load the JavaScript on an event like a form submit.   The following HTML in a  search/search.html  template will add a full search\nimplementation to your theme.  <h1 id=\"search\">Search Results</h1>\n\n<form action=\"search.html\">\n  <input name=\"q\" id=\"mkdocs-search-query\" type=\"text\" >\n</form>\n\n<div id=\"mkdocs-search-results\">\n  Sorry, page not found.\n</div>  The JavaScript in the plugin works by looking for the specific ID's used in the\nabove HTML. The input for the user to type the search query must have the ID mkdocs-search-query  and  mkdocs-search-results  is the div where the results\nwill be placed.",
            "title": "search_index_only"
        },
        {
            "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  custom_dir . If you have created a \"one-off theme,\"\nthat should be sufficient. 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 then take\nadvantage of the [custom_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  and  setup.py  beside the theme directory which\ncontains an empty  __init__.py  file, a theme configuration file\n( mkdocs-theme.yml ), and your template and media files.  .\n|-- MANIFEST.in\n|-- theme_name\n|   |-- __init__.py\n|   |-- mkdocs-theme.yml\n|   |-- main.html\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/#theme-configuration",
            "text": "A packaged theme is required to include a configuration file named mkdocs_theme.yml  which is placed in the root of your template files. The file\nshould contain default configuration options for the theme. However, if the\ntheme offers no configuration options, the file is still required and can be\nleft blank.  The theme author is free to define any arbitrary options deemed necessary and\nthose options will be made available in the templates to control behavior.\nFor example, a theme might want to make a sidebar optional and include the\nfollowing in the  mkdocs_theme.yml  file:  show_sidebar: true  Then in a template, that config option could be referenced:  {% if config.theme.show_sidebar %}\n<div id=\"sidebar\">...</div>\n{% endif %}  And the user could override the default in their project's  mkdocs.yml  config\nfile:  theme:\n    name: themename\n    show_sidebar: false  In addition to arbitrary options defined by the theme, MkDocs defines a few\nspecial options which alters its behavior:",
            "title": "Theme Configuration"
        },
        {
            "location": "/user-guide/custom-themes/#static_templates",
            "text": "This option mirrors the  theme  config option of the same name and allows\nsome defaults to be set by the theme. Note that while the user can add\ntemplates to this list, the user cannot remove templates included in the\ntheme's config.",
            "title": "static_templates"
        },
        {
            "location": "/user-guide/custom-themes/#extends",
            "text": "Defines a parent theme that this theme inherits from. The value should be\nthe string name of the parent theme. Normal Jinja inheritance rules apply.   Plugins may also define some options which allow the theme to inform a plugin\nabout which set of plugin options it expects. See the documentation for any\nplugins you may wish to support in your theme.",
            "title": "extends"
        },
        {
            "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": "/user-guide/plugins/",
            "text": "MkDocs Plugins\n\uf0c1\n\n\nA Guide to installing, using and creating MkDocs Plugins\n\n\n\n\nInstalling Plugins\n\uf0c1\n\n\nBefore a plugin can be used, it must be installed on the system. If you are\nusing a plugin which comes with MkDocs, then it was installed when you installed\nMkDocs. However, to install third party plugins, you need to determine the\nappropriate package name and install it using \npip\n:\n\n\npip install mkdocs-foo-plugin\n\n\n\nOnce a plugin has been successfully installed, it is ready to use. It just needs\nto be \nenabled\n in the configuration file.\n\n\nUsing Plugins\n\uf0c1\n\n\nThe \nplugins\n configuration option should contain a list of plugins to\nuse when building the site. Each \"plugin\" must be a string name assigned to the\nplugin (see the documentation for a given plugin to determine its \"name\"). A\nplugin listed here must already be \ninstalled\n.\n\n\nplugins:\n    - search\n\n\n\n\nSome plugins may provide configuration options of their own. If you would like\nto set any configuration options, then you can nest a key/value mapping\n(\noption_name: option value\n) of any options that a given plugin supports. Note\nthat a colon (\n:\n) must follow the plugin name and then on a new line the option\nname and value must be indented and separated by a colon. If you would like to\ndefine multiple options for a single plugin, each option must be defined on a\nseparate line.\n\n\nplugins:\n    - search:\n        lang: en\n        foo: bar\n\n\n\n\nFor information regarding the configuration options available for a given plugin,\nsee that plugin's documentation.\n\n\nFor a list of default plugins and how to override them, see the\n\nconfiguration\n documentation.\n\n\nDeveloping Plugins\n\uf0c1\n\n\nLike MkDocs, plugins must be written in Python. It is generally expected that\neach plugin would be distributed as a separate Python module, although it is\npossible to define multiple plugins in the same module. At a minimum, a MkDocs\nPlugin must consist of a \nBasePlugin\n subclass and an \nentry point\n which\npoints to it.\n\n\nBasePlugin\n\uf0c1\n\n\nA subclass of \nmkdocs.plugins.BasePlugin\n should define the behavior of the plugin.\nThe class generally consists of actions to perform on specific events in the build\nprocess as well as a configuration scheme for the plugin.\n\n\nAll \nBasePlugin\n subclasses contain the following attributes:\n\n\nconfig_scheme\n\uf0c1\n\n\n\n\nA tuple of configuration validation class instances (to be defined in a subclass).\n\n\n\n\nconfig\n\uf0c1\n\n\n\n\nA dictionary of configuration options for the plugin which is populated by the\n\nload_config\n method.\n\n\n\n\nAll \nBasePlugin\n subclasses contain the following method(s):\n\n\nload_config(options)\n\uf0c1\n\n\n\n\nLoads configuration from a dictionary of options. Returns a tuple of \n(errors,\nwarnings)\n.\n\n\n\n\non_<event_name>()\n\uf0c1\n\n\n\n\n\n\nOptional methods which define the behavior for specific \nevents\n. The plugin\nshould define its behavior within these methods. Replace \n<event_name>\n with\nthe actual name of the event. For example, the \npre_build\n event would be\ndefined in the \non_pre_build\n method.\n\n\nMost events accept one positional argument and various keyword arguments. It\nis generally expected that the positional argument would be modified (or\nreplaced) by the plugin and returned. If nothing is returned (the method\nreturns \nNone\n), then the original, unmodified object is used. The keyword\narguments are simply provided to give context and/or supply data which may\nbe used to determine how the positional argument should be modified. It is\ngood practice to accept keyword arguments as \n**kwargs\n. In the event that\nadditional keywords are provided to an event in a future version of MkDocs,\nthere will be no need to alter your plugin.\n\n\nFor example, the following event would add an additional static_template to\nthe theme config:\n\n\nclass MyPlugin(BasePlugin):\n    def on_config(self, config, **kwargs):\n        config['theme'].static_templates.add('my_template.html')\n        return config\n\n\n\n\n\n\n\nEvents\n\uf0c1\n\n\nThere are three kinds of events: \nGlobal Events\n, \nPage Events\n and\n\nTemplate Events\n.\n\n\nGlobal Events\n\uf0c1\n\n\nGlobal events are called once per build at either the beginning or end of the\nbuild process. Any changes made in these events will have a global effect on the\nentire site.\n\n\non_serve\n\uf0c1\n\n\n\n\n\n\nThe \nserve\n event is only called when the \nserve\n command is used during\ndevelopment. It is passed the \nServer\n instance which can be modified before\nit is activated. For example, additional files or directories could be added\nto the list of \"watched\" filed for auto-reloading.\n\n\n\n\nParameters:\n\n\nserver:\n \nlivereload.Server\n instance\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\nlivereload.Server\n instance\n\n\n\n\n\n\n\n\non_config\n\uf0c1\n\n\n\n\n\n\nThe \nconfig\n event is the first event called on build and is run immediately\nafter the user configuration is loaded and validated. Any alterations to the\nconfig should be made here.\n\n\n\n\nParameters:\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\nglobal configuration object\n\n\n\n\n\n\n\n\non_pre_build\n\uf0c1\n\n\n\n\n\n\nThe \npre_build\n event does not alter any variables. Use this event to call\npre-build scripts.\n\n\n\n\nParameters:\n\n\nconfig:\n global configuration object\n\n\n\n\n\n\n\n\non_nav\n\uf0c1\n\n\n\n\n\n\nThe \nnav\n event is called after the site navigation is created and can\nbe used to alter the site navigation.\n\n\n\n\nParameters:\n\n\nsite_navigation:\n global navigation object\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\nglobal navigation object\n\n\n\n\n\n\n\n\non_env\n\uf0c1\n\n\n\n\n\n\nThe \nenv\n event is called after the Jinja template environment is created\nand can be used to alter the Jinja environment.\n\n\n\n\nParameters:\n\n\nenv:\n global Jinja environment\n\n\nconfig:\n global configuration object\n\n\nsite_navigation:\n global navigation object\n\n\nReturns:\n\n\nglobal Jinja Environment\n\n\n\n\n\n\n\n\non_post_build\n\uf0c1\n\n\n\n\n\n\nThe \npost_build\n event does not alter any variables. Use this event to call\npost-build scripts.\n\n\n\n\nParameters:\n\n\nconfig:\n global configuration object\n\n\n\n\n\n\n\n\nTemplate Events\n\uf0c1\n\n\nTemplate events are called once for each non-page template. Each template event\nwill be called for each template defined in the \nextra_templates\n config setting\nas well as any \nstatic_templates\n defined in the theme. All template events are\ncalled after the \nenv\n event and before any \npage events\n.\n\n\non_pre_template\n\uf0c1\n\n\n\n\n\n\nThe \npre_template\n event is called immediately after the subject template is\nloaded and can be used to alter the content of the template.\n\n\n\n\nParameters:\n\n\ntemplate\n: the template contents as string\n\n\ntemplate_name\n: string filename of template\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\ntemplate contents as string\n\n\n\n\n\n\n\n\non_template_context\n\uf0c1\n\n\n\n\n\n\nThe \ntemplate_context\n event is called immediately after the context is created\nfor the subject template and can be used to alter the context for that specific\ntemplate only.\n\n\n\n\nParameters:\n\n\ncontext\n: dict of template context variables\n\n\ntemplate_name\n: string filename of template\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\ndict of template context variables\n\n\n\n\n\n\n\n\non_post_template\n\uf0c1\n\n\n\n\n\n\nThe \npost_template\n event is called after the template is rendered, but before\nit is written to disc and can be used to alter the output of the template.\nIf an empty string is returned, the template is skipped and nothing is is\nwritten to disc.\n\n\n\n\nParameters:\n\n\noutput_content\n: output of rendered template as string\n\n\ntemplate_name\n: string filename of template\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\noutput of rendered template as string\n\n\n\n\n\n\n\n\nPage Events\n\uf0c1\n\n\nPage events are called once for each Markdown page included in the site. All\npage events are called after the \npost_template\n event and before the \npost_build\n\nevent.\n\n\non_pre_page\n\uf0c1\n\n\n\n\n\n\nThe \npre_page\n event is called before any actions are taken on the subject\npage and can be used to alter the \nPage\n instance.\n\n\n\n\nParameters:\n\n\npage:\n \nmkdocs.nav.Page\n instance\n\n\nconfig:\n global configuration object\n\n\nsite_navigation:\n global navigation object\n\n\nReturns:\n\n\nmkdocs.nav.Page\n instance\n\n\n\n\n\n\n\n\non_page_read_source\n\uf0c1\n\n\n\n\n\n\nThe \non_page_read_source\n event can replace the default mechanism to read\nthe contents of a page's source from the filesystem.\n\n\n\n\nParameters:\n\n\npage:\n \nmkdocs.nav.Page\n instance\n\n\nconfig:\n global configuration object\n\n\nReturns:\n\n\nThe raw source for a page as unicode string. If \nNone\n is returned, the\n  default loading from a file will be performed.\n\n\n\n\n\n\n\n\non_page_markdown\n\uf0c1\n\n\n\n\n\n\nThe \npage_markdown\n event is called after the page's markdown is loaded\nfrom file and can be used to alter the Markdown source text. The meta-\ndata has been stripped off and is available as \npage.meta\n at this point.\n\n\n\n\nParameters:\n\n\nmarkdown:\n Markdown source text of page as string\n\n\npage:\n \nmkdocs.nav.Page\n instance\n\n\nconfig:\n global configuration object\n\n\nsite_navigation:\n global navigation object\n\n\nReturns:\n\n\nMarkdown source text of page as string\n\n\n\n\n\n\n\n\non_page_content\n\uf0c1\n\n\n\n\n\n\nThe \npage_content\n event is called after the Markdown text is rendered to\nHTML (but before being passed to a template) and can be used to alter the\nHTML body of the page.\n\n\n\n\nParameters:\n\n\nhtml:\n HTML rendered from Markdown source as string\n\n\npage:\n \nmkdocs.nav.Page\n instance\n\n\nconfig:\n global configuration object\n\n\nsite_navigation:\n global navigation object\n\n\nReturns:\n\n\nHTML rendered from Markdown source as string\n\n\n\n\n\n\n\n\non_page_context\n\uf0c1\n\n\n\n\n\n\nThe \npage_context\n event is called after the context for a page is created\nand can be used to alter the context for that specific page only.\n\n\n\n\nParameters:\n\n\ncontext\n: dict of template context variables\n\n\npage:\n \nmkdocs.nav.Page\n instance\n\n\nconfig:\n global configuration object\n\n\nsite_navigation:\n global navigation object\n\n\nReturns:\n\n\ndict of template context variables\n\n\n\n\n\n\n\n\non_post_page\n\uf0c1\n\n\n\n\n\n\nThe \npost_template\n event is called after the template is rendered, but\nbefore it is written to disc and can be used to alter the output of the\npage. If an empty string is returned, the page is skipped and nothing is\nwritten to disc.\n\n\n\n\nParameters:\n\n\noutput_content:\n output of rendered template as string\n\n\npage:\n \nmkdocs.nav.Page\n instance\n\n\nconfig:\n global configuration object\n\n\nsite_navigation:\n global navigation object\n\n\nReturns:\n\n\noutput of rendered template as string\n\n\n\n\n\n\n\n\nEntry Point\n\uf0c1\n\n\nPlugins need to be packaged as Python libraries (distributed on PyPI separate\nfrom MkDocs) and each must register as a Plugin via a setuptools entry_point.\nAdd the following to your \nsetup.py\n script:\n\n\nentry_points={\n    'mkdocs.plugins': [\n        'pluginname = path.to.some_plugin:SomePluginClass',\n    ]\n}\n\n\n\n\nThe \npluginname\n would be the name used by users (in the config file) and\n\npath.to.some_plugin:SomePluginClass\n would be the importable plugin itself\n(\nfrom path.to.some_plugin import SomePluginClass\n) where \nSomePluginClass\n is a\nsubclass of \nBasePlugin\n which defines the plugin behavior. Naturally, multiple\nPlugin classes could exist in the same module. Simply define each as a separate\nentry_point.\n\n\nentry_points={\n    'mkdocs.plugins': [\n        'featureA = path.to.my_plugins:PluginA',\n        'featureB = path.to.my_plugins:PluginB'\n    ]\n}\n\n\n\n\nNote that registering a plugin does not activate it. The user still needs to\ntell MkDocs to use if via the config.",
            "title": "Plugins"
        },
        {
            "location": "/user-guide/plugins/#mkdocs-plugins",
            "text": "A Guide to installing, using and creating MkDocs Plugins",
            "title": "MkDocs Plugins"
        },
        {
            "location": "/user-guide/plugins/#installing-plugins",
            "text": "Before a plugin can be used, it must be installed on the system. If you are\nusing a plugin which comes with MkDocs, then it was installed when you installed\nMkDocs. However, to install third party plugins, you need to determine the\nappropriate package name and install it using  pip :  pip install mkdocs-foo-plugin  Once a plugin has been successfully installed, it is ready to use. It just needs\nto be  enabled  in the configuration file.",
            "title": "Installing Plugins"
        },
        {
            "location": "/user-guide/plugins/#using-plugins",
            "text": "The  plugins  configuration option should contain a list of plugins to\nuse when building the site. Each \"plugin\" must be a string name assigned to the\nplugin (see the documentation for a given plugin to determine its \"name\"). A\nplugin listed here must already be  installed .  plugins:\n    - search  Some plugins may provide configuration options of their own. If you would like\nto set any configuration options, then you can nest a key/value mapping\n( option_name: option value ) of any options that a given plugin supports. Note\nthat a colon ( : ) must follow the plugin name and then on a new line the option\nname and value must be indented and separated by a colon. If you would like to\ndefine multiple options for a single plugin, each option must be defined on a\nseparate line.  plugins:\n    - search:\n        lang: en\n        foo: bar  For information regarding the configuration options available for a given plugin,\nsee that plugin's documentation.  For a list of default plugins and how to override them, see the configuration  documentation.",
            "title": "Using Plugins"
        },
        {
            "location": "/user-guide/plugins/#developing-plugins",
            "text": "Like MkDocs, plugins must be written in Python. It is generally expected that\neach plugin would be distributed as a separate Python module, although it is\npossible to define multiple plugins in the same module. At a minimum, a MkDocs\nPlugin must consist of a  BasePlugin  subclass and an  entry point  which\npoints to it.",
            "title": "Developing Plugins"
        },
        {
            "location": "/user-guide/plugins/#baseplugin",
            "text": "A subclass of  mkdocs.plugins.BasePlugin  should define the behavior of the plugin.\nThe class generally consists of actions to perform on specific events in the build\nprocess as well as a configuration scheme for the plugin.  All  BasePlugin  subclasses contain the following attributes:",
            "title": "BasePlugin"
        },
        {
            "location": "/user-guide/plugins/#config_scheme",
            "text": "A tuple of configuration validation class instances (to be defined in a subclass).",
            "title": "config_scheme"
        },
        {
            "location": "/user-guide/plugins/#config",
            "text": "A dictionary of configuration options for the plugin which is populated by the load_config  method.   All  BasePlugin  subclasses contain the following method(s):",
            "title": "config"
        },
        {
            "location": "/user-guide/plugins/#load_configoptions",
            "text": "Loads configuration from a dictionary of options. Returns a tuple of  (errors,\nwarnings) .",
            "title": "load_config(options)"
        },
        {
            "location": "/user-guide/plugins/#on_event_name",
            "text": "Optional methods which define the behavior for specific  events . The plugin\nshould define its behavior within these methods. Replace  <event_name>  with\nthe actual name of the event. For example, the  pre_build  event would be\ndefined in the  on_pre_build  method.  Most events accept one positional argument and various keyword arguments. It\nis generally expected that the positional argument would be modified (or\nreplaced) by the plugin and returned. If nothing is returned (the method\nreturns  None ), then the original, unmodified object is used. The keyword\narguments are simply provided to give context and/or supply data which may\nbe used to determine how the positional argument should be modified. It is\ngood practice to accept keyword arguments as  **kwargs . In the event that\nadditional keywords are provided to an event in a future version of MkDocs,\nthere will be no need to alter your plugin.  For example, the following event would add an additional static_template to\nthe theme config:  class MyPlugin(BasePlugin):\n    def on_config(self, config, **kwargs):\n        config['theme'].static_templates.add('my_template.html')\n        return config",
            "title": "on_&lt;event_name&gt;()"
        },
        {
            "location": "/user-guide/plugins/#events",
            "text": "There are three kinds of events:  Global Events ,  Page Events  and Template Events .",
            "title": "Events"
        },
        {
            "location": "/user-guide/plugins/#global-events",
            "text": "Global events are called once per build at either the beginning or end of the\nbuild process. Any changes made in these events will have a global effect on the\nentire site.",
            "title": "Global Events"
        },
        {
            "location": "/user-guide/plugins/#on_serve",
            "text": "The  serve  event is only called when the  serve  command is used during\ndevelopment. It is passed the  Server  instance which can be modified before\nit is activated. For example, additional files or directories could be added\nto the list of \"watched\" filed for auto-reloading.   Parameters:  server:   livereload.Server  instance  config:  global configuration object  Returns:  livereload.Server  instance",
            "title": "on_serve"
        },
        {
            "location": "/user-guide/plugins/#on_config",
            "text": "The  config  event is the first event called on build and is run immediately\nafter the user configuration is loaded and validated. Any alterations to the\nconfig should be made here.   Parameters:  config:  global configuration object  Returns:  global configuration object",
            "title": "on_config"
        },
        {
            "location": "/user-guide/plugins/#on_pre_build",
            "text": "The  pre_build  event does not alter any variables. Use this event to call\npre-build scripts.   Parameters:  config:  global configuration object",
            "title": "on_pre_build"
        },
        {
            "location": "/user-guide/plugins/#on_nav",
            "text": "The  nav  event is called after the site navigation is created and can\nbe used to alter the site navigation.   Parameters:  site_navigation:  global navigation object  config:  global configuration object  Returns:  global navigation object",
            "title": "on_nav"
        },
        {
            "location": "/user-guide/plugins/#on_env",
            "text": "The  env  event is called after the Jinja template environment is created\nand can be used to alter the Jinja environment.   Parameters:  env:  global Jinja environment  config:  global configuration object  site_navigation:  global navigation object  Returns:  global Jinja Environment",
            "title": "on_env"
        },
        {
            "location": "/user-guide/plugins/#on_post_build",
            "text": "The  post_build  event does not alter any variables. Use this event to call\npost-build scripts.   Parameters:  config:  global configuration object",
            "title": "on_post_build"
        },
        {
            "location": "/user-guide/plugins/#template-events",
            "text": "Template events are called once for each non-page template. Each template event\nwill be called for each template defined in the  extra_templates  config setting\nas well as any  static_templates  defined in the theme. All template events are\ncalled after the  env  event and before any  page events .",
            "title": "Template Events"
        },
        {
            "location": "/user-guide/plugins/#on_pre_template",
            "text": "The  pre_template  event is called immediately after the subject template is\nloaded and can be used to alter the content of the template.   Parameters:  template : the template contents as string  template_name : string filename of template  config:  global configuration object  Returns:  template contents as string",
            "title": "on_pre_template"
        },
        {
            "location": "/user-guide/plugins/#on_template_context",
            "text": "The  template_context  event is called immediately after the context is created\nfor the subject template and can be used to alter the context for that specific\ntemplate only.   Parameters:  context : dict of template context variables  template_name : string filename of template  config:  global configuration object  Returns:  dict of template context variables",
            "title": "on_template_context"
        },
        {
            "location": "/user-guide/plugins/#on_post_template",
            "text": "The  post_template  event is called after the template is rendered, but before\nit is written to disc and can be used to alter the output of the template.\nIf an empty string is returned, the template is skipped and nothing is is\nwritten to disc.   Parameters:  output_content : output of rendered template as string  template_name : string filename of template  config:  global configuration object  Returns:  output of rendered template as string",
            "title": "on_post_template"
        },
        {
            "location": "/user-guide/plugins/#page-events",
            "text": "Page events are called once for each Markdown page included in the site. All\npage events are called after the  post_template  event and before the  post_build \nevent.",
            "title": "Page Events"
        },
        {
            "location": "/user-guide/plugins/#on_pre_page",
            "text": "The  pre_page  event is called before any actions are taken on the subject\npage and can be used to alter the  Page  instance.   Parameters:  page:   mkdocs.nav.Page  instance  config:  global configuration object  site_navigation:  global navigation object  Returns:  mkdocs.nav.Page  instance",
            "title": "on_pre_page"
        },
        {
            "location": "/user-guide/plugins/#on_page_read_source",
            "text": "The  on_page_read_source  event can replace the default mechanism to read\nthe contents of a page's source from the filesystem.   Parameters:  page:   mkdocs.nav.Page  instance  config:  global configuration object  Returns:  The raw source for a page as unicode string. If  None  is returned, the\n  default loading from a file will be performed.",
            "title": "on_page_read_source"
        },
        {
            "location": "/user-guide/plugins/#on_page_markdown",
            "text": "The  page_markdown  event is called after the page's markdown is loaded\nfrom file and can be used to alter the Markdown source text. The meta-\ndata has been stripped off and is available as  page.meta  at this point.   Parameters:  markdown:  Markdown source text of page as string  page:   mkdocs.nav.Page  instance  config:  global configuration object  site_navigation:  global navigation object  Returns:  Markdown source text of page as string",
            "title": "on_page_markdown"
        },
        {
            "location": "/user-guide/plugins/#on_page_content",
            "text": "The  page_content  event is called after the Markdown text is rendered to\nHTML (but before being passed to a template) and can be used to alter the\nHTML body of the page.   Parameters:  html:  HTML rendered from Markdown source as string  page:   mkdocs.nav.Page  instance  config:  global configuration object  site_navigation:  global navigation object  Returns:  HTML rendered from Markdown source as string",
            "title": "on_page_content"
        },
        {
            "location": "/user-guide/plugins/#on_page_context",
            "text": "The  page_context  event is called after the context for a page is created\nand can be used to alter the context for that specific page only.   Parameters:  context : dict of template context variables  page:   mkdocs.nav.Page  instance  config:  global configuration object  site_navigation:  global navigation object  Returns:  dict of template context variables",
            "title": "on_page_context"
        },
        {
            "location": "/user-guide/plugins/#on_post_page",
            "text": "The  post_template  event is called after the template is rendered, but\nbefore it is written to disc and can be used to alter the output of the\npage. If an empty string is returned, the page is skipped and nothing is\nwritten to disc.   Parameters:  output_content:  output of rendered template as string  page:   mkdocs.nav.Page  instance  config:  global configuration object  site_navigation:  global navigation object  Returns:  output of rendered template as string",
            "title": "on_post_page"
        },
        {
            "location": "/user-guide/plugins/#entry-point",
            "text": "Plugins need to be packaged as Python libraries (distributed on PyPI separate\nfrom MkDocs) and each must register as a Plugin via a setuptools entry_point.\nAdd the following to your  setup.py  script:  entry_points={\n    'mkdocs.plugins': [\n        'pluginname = path.to.some_plugin:SomePluginClass',\n    ]\n}  The  pluginname  would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass  would be the importable plugin itself\n( from path.to.some_plugin import SomePluginClass ) where  SomePluginClass  is a\nsubclass of  BasePlugin  which defines the plugin behavior. Naturally, multiple\nPlugin classes could exist in the same module. Simply define each as a separate\nentry_point.  entry_points={\n    'mkdocs.plugins': [\n        'featureA = path.to.my_plugins:PluginA',\n        'featureB = path.to.my_plugins:PluginB'\n    ]\n}  Note that registering a plugin does not activate it. The user still needs to\ntell MkDocs to use if via the config.",
            "title": "Entry Point"
        },
        {
            "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\nDevelopment Version\n\uf0c1\n\n\n\n\nRefactor \ncopy_media_files\n util function for more flexibility (#1370).\n\n\n\n\nVersion 0.17.2 (2017-11-15)\n\uf0c1\n\n\n\n\nBugfix: Correct \nextra_*\n config setting regressions (#1335 & #1336).\n\n\n\n\nTest second level nav\n\uf0c1\n\n\n\n\nTest test test\n\n\n\n\nVersion 0.17.1 (2017-10-30)\n\uf0c1\n\n\n\n\nBugfix: Support \nrepo_url\n with missing ending slash. (#1321).\n\n\nBugfix: Add length support to \nmkdocs.toc.TableOfContext\n (#1325).\n\n\nBugfix: Add some theme specific settings to the search plugin for third party\n  themes (#1316).\n\n\nBugfix: Override \nsite_url\n with \ndev_addr\n on local server (#1317).\n\n\n\n\nVersion 0.17.0 (2017-10-19)\n\uf0c1\n\n\nMajor Additions to Version 0.17.0\n\uf0c1\n\n\nPlugin API. (#206)\n\uf0c1\n\n\nA new \nPlugin API\n has been added to MkDocs which allows users to define their\nown custom behaviors. See the included documentation for a full explanation of\nthe API.\n\n\nThe previously built-in search functionality has been removed and wrapped in a\nplugin (named \"search\") with no changes in behavior. When MkDocs builds, the\nsearch index is now written to \nsearch/search_index.json\n instead of\n\nmkdocs/search_index.json\n. If no plugins setting is defined in the config,\nthen the \nsearch\n plugin will be included by default. See the\n\nconfiguration\n documentation for information on overriding the\ndefault.\n\n\nTheme Customization. (#1164)\n\uf0c1\n\n\nSupport had been added to provide theme specific customizations. Theme authors\ncan define default options as documented in \nTheme Configuration\n. A theme can\nnow inherit from another theme, define various static templates to be rendered,\nand define arbitrary default variables to control behavior in the templates.\nThe theme configuration is defined in a configuruation file named\n\nmkdocs_theme.yml\n which should be placed at the root of your template files. A\nwarning will be raised if no configuration file is found and an error will be\nraised in a future release.\n\n\nUsers can override those defaults under the \ntheme\n configuration option of\ntheir \nmkdocs.yml\n configuration file, which now accepts nested options. One\nsuch nested option is the \ncustom_dir\n option, which replaces the now deprecated\n\ntheme_dir\n option. If users had previously set the \ntheme_dir\n option, a\nwarning will be issued, with an error expected in a future release.\n\n\nIf a configuration previously defined a \ntheme_dir\n like this:\n\n\ntheme: mkdocs\ntheme_dir: custom\n\n\n\n\nThen the configuration should be adjusted as follows:\n\n\ntheme:\n    name: mkdocs\n    custom_dir: custom\n\n\n\n\nSee the \ntheme\n configuration option documentation for details.\n\n\nPreviously deprecated Template variables removed. (#1168)\n\uf0c1\n\n\nPage Template\n\uf0c1\n\n\nThe primary entry point for page templates has been changed from \nbase.html\n to\n\nmain.html\n. This allows \nbase.html\n to continue to exist while allowing users\nto override \nmain.html\n and extend \nbase.html\n. For version 0.16, \nbase.html\n\ncontinued to work if no \nmain.html\n template existed, but it raised a\ndeprecation warning. In version 1.0, a build will fail if no \nmain.html\n\ntemplate exists.\n\n\nContext Variables\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 issued a warning in version 0.16, but have been removed in\nversion 1.0.\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\nAdditionally, a number of global variables have been altered and/or removed\nand user created and third-party templates should be updated as outlined below:\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\nAuto-Populated extra_css and extra_javascript Fully 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. On version 0.16 this\nbehavior was deprecated and a warning was issued. In 1.0 any unlisted CSS and\nJavaScript files will not be included in the HTML templates, however, a warning\nwill be issued. In other words, they will still be copied to the \nsite-dir\n, but\nthey will not have any effect on the theme if they are not explicitly 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\nOther Changes and Additions to Version 0.17.0\n\uf0c1\n\n\n\n\nAdd \"edit Link\" support to MkDocs theme (#1129)\n\n\nOpen files with \nutf-8-sig\n to account for BOM (#1186)\n\n\nSymbolic links are now followed consistently (#1134)\n\n\nSupport for keyboard navigation shortcuts added to included themes (#1095)\n\n\nSome refactoring and improvements to config_options (#1296)\n\n\nOfficially added support for Python 3.6 (#1296)\n\n\n404 Error page added to readthedocs theme (#1296))\n\n\nInternal refactor of Markdown processing (#713)\n\n\nRemoved special error message for mkdocs-bootstrap and mkdocs-bootswatch\n  themes (#1168)\n\n\nThe legacy pages config is no longer supported (#1168)\n\n\nThe deprecated \njson\n command has been removed (#481)\n\n\nSupport for Python 2.6 has been dropped (#165)\n\n\nFile permissions are no longer copied during build (#1292)\n\n\nSupport query and fragment strings in \nedit_uri\n (#1224 & #1273)\n\n\n\n\nVersion 0.16.3 (2017-04-04)\n\uf0c1\n\n\n\n\nFix error raised by autoscrolling in the readthedocs theme (#1177)\n\n\nFix a few documentation typos (#1181 & #1185)\n\n\nFix a regression to livereload server introduced in 0.16.2 (#1174)\n\n\n\n\nVersion 0.16.2 (2017-03-13)\n\uf0c1\n\n\n\n\nSystem root (\n/\n) is not a valid path for site_dir or docs_dir (#1161)\n\n\nRefactor readthedocs theme navigation (#1155 & #1156)\n\n\nAdd support to dev server to serve custom error pages (#1040)\n\n\nEnsure nav.homepage.url is not blank on error pages (#1131)\n\n\nIncrease livereload dependency to 2.5.1 (#1106)\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 customizing 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 dependency on the six library. (#583)\n\n\nRemove dependency on the ghp-import library. (#547)\n\n\nAdd \n--quiet\n and \n--verbose\n options to all sub-commands. (#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\nStandardize 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 URLs 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 files 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 versions 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<ul>\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 behavior. (#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": "",
            "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",
            "title": "Upgrading"
        },
        {
            "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/#development-version",
            "text": "Refactor  copy_media_files  util function for more flexibility (#1370).",
            "title": "Development Version"
        },
        {
            "location": "/about/release-notes/#version-0172-2017-11-15",
            "text": "Bugfix: Correct  extra_*  config setting regressions (#1335 & #1336).",
            "title": "Version 0.17.2 (2017-11-15)"
        },
        {
            "location": "/about/release-notes/#test-second-level-nav",
            "text": "Test test test",
            "title": "Test second level nav"
        },
        {
            "location": "/about/release-notes/#version-0171-2017-10-30",
            "text": "Bugfix: Support  repo_url  with missing ending slash. (#1321).  Bugfix: Add length support to  mkdocs.toc.TableOfContext  (#1325).  Bugfix: Add some theme specific settings to the search plugin for third party\n  themes (#1316).  Bugfix: Override  site_url  with  dev_addr  on local server (#1317).",
            "title": "Version 0.17.1 (2017-10-30)"
        },
        {
            "location": "/about/release-notes/#version-0170-2017-10-19",
            "text": "",
            "title": "Version 0.17.0 (2017-10-19)"
        },
        {
            "location": "/about/release-notes/#major-additions-to-version-0170",
            "text": "",
            "title": "Major Additions to Version 0.17.0"
        },
        {
            "location": "/about/release-notes/#plugin-api-206",
            "text": "A new  Plugin API  has been added to MkDocs which allows users to define their\nown custom behaviors. See the included documentation for a full explanation of\nthe API.  The previously built-in search functionality has been removed and wrapped in a\nplugin (named \"search\") with no changes in behavior. When MkDocs builds, the\nsearch index is now written to  search/search_index.json  instead of mkdocs/search_index.json . If no plugins setting is defined in the config,\nthen the  search  plugin will be included by default. See the configuration  documentation for information on overriding the\ndefault.",
            "title": "Plugin API. (#206)"
        },
        {
            "location": "/about/release-notes/#theme-customization-1164",
            "text": "Support had been added to provide theme specific customizations. Theme authors\ncan define default options as documented in  Theme Configuration . A theme can\nnow inherit from another theme, define various static templates to be rendered,\nand define arbitrary default variables to control behavior in the templates.\nThe theme configuration is defined in a configuruation file named mkdocs_theme.yml  which should be placed at the root of your template files. A\nwarning will be raised if no configuration file is found and an error will be\nraised in a future release.  Users can override those defaults under the  theme  configuration option of\ntheir  mkdocs.yml  configuration file, which now accepts nested options. One\nsuch nested option is the  custom_dir  option, which replaces the now deprecated theme_dir  option. If users had previously set the  theme_dir  option, a\nwarning will be issued, with an error expected in a future release.  If a configuration previously defined a  theme_dir  like this:  theme: mkdocs\ntheme_dir: custom  Then the configuration should be adjusted as follows:  theme:\n    name: mkdocs\n    custom_dir: custom  See the  theme  configuration option documentation for details.",
            "title": "Theme Customization. (#1164)"
        },
        {
            "location": "/about/release-notes/#previously-deprecated-template-variables-removed-1168",
            "text": "",
            "title": "Previously deprecated Template variables removed. (#1168)"
        },
        {
            "location": "/about/release-notes/#page-template",
            "text": "The primary entry point for page templates has been changed from  base.html  to main.html . This allows  base.html  to continue to exist while allowing users\nto override  main.html  and extend  base.html . For version 0.16,  base.html \ncontinued to work if no  main.html  template existed, but it raised a\ndeprecation warning. In version 1.0, a build will fail if no  main.html \ntemplate exists.",
            "title": "Page Template"
        },
        {
            "location": "/about/release-notes/#context-variables",
            "text": "Page specific variable names in the template context have been refactored as\ndefined in  Custom Themes . The\nold variable names issued a warning in version 0.16, but have been removed in\nversion 1.0.  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     Additionally, a number of global variables have been altered and/or removed\nand user created and third-party templates should be updated as outlined below:     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": "Context Variables"
        },
        {
            "location": "/about/release-notes/#auto-populated-extra_css-and-extra_javascript-fully-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. On version 0.16 this\nbehavior was deprecated and a warning was issued. In 1.0 any unlisted CSS and\nJavaScript files will not be included in the HTML templates, however, a warning\nwill be issued. In other words, they will still be copied to the  site-dir , but\nthey will not have any effect on the theme if they are not explicitly listed.  All CSS and javaScript files in the  docs_dir  should be explicitly listed in\nthe  extra_css  or  extra_javascript  config settings going forward.",
            "title": "Auto-Populated extra_css and extra_javascript Fully Deprecated. (#986)"
        },
        {
            "location": "/about/release-notes/#other-changes-and-additions-to-version-0170",
            "text": "Add \"edit Link\" support to MkDocs theme (#1129)  Open files with  utf-8-sig  to account for BOM (#1186)  Symbolic links are now followed consistently (#1134)  Support for keyboard navigation shortcuts added to included themes (#1095)  Some refactoring and improvements to config_options (#1296)  Officially added support for Python 3.6 (#1296)  404 Error page added to readthedocs theme (#1296))  Internal refactor of Markdown processing (#713)  Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch\n  themes (#1168)  The legacy pages config is no longer supported (#1168)  The deprecated  json  command has been removed (#481)  Support for Python 2.6 has been dropped (#165)  File permissions are no longer copied during build (#1292)  Support query and fragment strings in  edit_uri  (#1224 & #1273)",
            "title": "Other Changes and Additions to Version 0.17.0"
        },
        {
            "location": "/about/release-notes/#version-0163-2017-04-04",
            "text": "Fix error raised by autoscrolling in the readthedocs theme (#1177)  Fix a few documentation typos (#1181 & #1185)  Fix a regression to livereload server introduced in 0.16.2 (#1174)",
            "title": "Version 0.16.3 (2017-04-04)"
        },
        {
            "location": "/about/release-notes/#version-0162-2017-03-13",
            "text": "System root ( / ) is not a valid path for site_dir or docs_dir (#1161)  Refactor readthedocs theme navigation (#1155 & #1156)  Add support to dev server to serve custom error pages (#1040)  Ensure nav.homepage.url is not blank on error pages (#1131)  Increase livereload dependency to 2.5.1 (#1106)",
            "title": "Version 0.16.2 (2017-03-13)"
        },
        {
            "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": "",
            "title": "Major Additions to Version 0.16.0"
        },
        {
            "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",
            "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",
            "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.",
            "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.",
            "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.",
            "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 .",
            "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).",
            "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)",
            "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 .",
            "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)",
            "title": "Version 0.15.1 (2016-01-30)"
        },
        {
            "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": "",
            "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 customizing 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)",
            "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 dependency on the six library. (#583)  Remove dependency on the ghp-import library. (#547)  Add  --quiet  and  --verbose  options to all sub-commands. (#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)",
            "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)",
            "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)",
            "title": "Version 0.13.1 (2015-05-27)"
        },
        {
            "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": "",
            "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.",
            "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.",
            "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.",
            "title": "Warn users about the removal of builtin themes"
        },
        {
            "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.",
            "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.",
            "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.",
            "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).",
            "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)",
            "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.",
            "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)  Standardize 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 URLs 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 files 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 versions 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)",
            "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)",
            "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 behavior. (#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/test_second_level/",
            "text": "Test second level\n\uf0c1\n\n\nVersion 0.17.2 (2017-11-15)\n\uf0c1\n\n\n\n\nBugfix: Correct \nextra_*\n config setting regressions (#1335 & #1336).\n\n\n\n\nTest second level nav\n\uf0c1\n\n\n\n\nTest test test",
            "title": "Some other page"
        },
        {
            "location": "/about/test_second_level/#test-second-level",
            "text": "",
            "title": "Test second level"
        },
        {
            "location": "/about/test_second_level/#version-0172-2017-11-15",
            "text": "Bugfix: Correct  extra_*  config setting regressions (#1335 & #1336).",
            "title": "Version 0.17.2 (2017-11-15)"
        },
        {
            "location": "/about/test_second_level/#test-second-level-nav",
            "text": "Test test test",
            "title": "Test second level nav"
        },
        {
            "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",
            "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 .",
            "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.",
            "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",
            "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.",
            "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.",
            "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.",
            "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.",
            "title": "License"
        },
        {
            "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.",
            "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.",
            "title": "MkDocs License (BSD)"
        }
    ]
}