Last active
February 3, 2018 17:07
-
-
Save yeraydiazdiaz/804b102195252dd7fc5ab059b7fc1100 to your computer and use it in GitHub Desktop.
MkDocs Lunr.js version comparison
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| /** | |
| * 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:lunr@1.0.0 | |
| * 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:') | |
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "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\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\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_<event_name>()" | |
| }, | |
| { | |
| "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)" | |
| } | |
| ] | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment