centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
mkdocs/about/release-notes/index.html
Tom Christie 2d44ad3c58 Deployed bb7e8b62 with MkDocs version: 1.5.3
2024-08-30 13:33:35 +01:00

2497 lines
229 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="author" content="MkDocs Team">
<link rel="canonical" href="https://www.mkdocs.org/about/release-notes/">
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>Release Notes - MkDocs</title>
<link href="../../css/bootstrap.min.css" rel="stylesheet">
<link href="../../css/font-awesome.min.css" rel="stylesheet">
<link href="../../css/base.css" rel="stylesheet">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css">
<link href="../../assets/_mkdocstrings.css" rel="stylesheet">
<link href="../../css/extra.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/yaml.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/django.min.js"></script>
<script>hljs.highlightAll();</script>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-274394082"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', "G-274394082");
</script>
</head>
<body>
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href="../..">MkDocs</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-toggle="collapse" data-target="#navbar-collapse">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="navitem">
<a href="../.." class="nav-link">Home</a>
</li>
<li class="navitem">
<a href="../../getting-started/" class="nav-link">Getting Started</a>
</li>
<li class="dropdown">
<a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">User Guide <b class="caret"></b></a>
<ul class="dropdown-menu">
<li>
<a href="../../user-guide/" class="dropdown-item">User Guide</a>
</li>
<li>
<a href="../../user-guide/installation/" class="dropdown-item">Installation</a>
</li>
<li>
<a href="../../user-guide/writing-your-docs/" class="dropdown-item">Writing Your Docs</a>
</li>
<li>
<a href="../../user-guide/choosing-your-theme/" class="dropdown-item">Choosing Your Theme</a>
</li>
<li>
<a href="../../user-guide/customizing-your-theme/" class="dropdown-item">Customizing Your Theme</a>
</li>
<li>
<a href="../../user-guide/localizing-your-theme/" class="dropdown-item">Localizing Your Theme</a>
</li>
<li>
<a href="../../user-guide/configuration/" class="dropdown-item">Configuration</a>
</li>
<li>
<a href="../../user-guide/cli/" class="dropdown-item">Command Line Interface</a>
</li>
<li>
<a href="../../user-guide/deploying-your-docs/" class="dropdown-item">Deploying Your Docs</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">Developer Guide <b class="caret"></b></a>
<ul class="dropdown-menu">
<li>
<a href="../../dev-guide/" class="dropdown-item">Developer Guide</a>
</li>
<li>
<a href="../../dev-guide/themes/" class="dropdown-item">Themes</a>
</li>
<li>
<a href="../../dev-guide/translations/" class="dropdown-item">Translations</a>
</li>
<li>
<a href="../../dev-guide/plugins/" class="dropdown-item">Plugins</a>
</li>
<li>
<a href="../../dev-guide/api/" class="dropdown-item">API Reference</a>
</li>
</ul>
</li>
<li class="dropdown active">
<a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">About <b class="caret"></b></a>
<ul class="dropdown-menu">
<li>
<a href="./" class="dropdown-item active">Release Notes</a>
</li>
<li>
<a href="../contributing/" class="dropdown-item">Contributing</a>
</li>
<li>
<a href="../license/" class="dropdown-item">License</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ml-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-toggle="modal" data-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../../dev-guide/api/" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="../contributing/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/mkdocs/mkdocs/blob/master/docs/about/release-notes.md" class="nav-link"><i class="fa fa-github"></i> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-light navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-toggle="collapse" data-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-secondary">
<ul class="nav flex-column">
<li class="nav-item" data-level="1"><a href="#release-notes" class="nav-link">Release Notes</a>
<ul class="nav flex-column">
<li class="nav-item" data-level="2"><a href="#upgrading" class="nav-link">Upgrading</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#maintenance-team" class="nav-link">Maintenance team</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-161-2024-08-30" class="nav-link">Version 1.6.1 (2024-08-30)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-160-2024-04-20" class="nav-link">Version 1.6.0 (2024-04-20)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-153-2023-09-18" class="nav-link">Version 1.5.3 (2023-09-18)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-152-2023-08-02" class="nav-link">Version 1.5.2 (2023-08-02)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-151-2023-07-28" class="nav-link">Version 1.5.1 (2023-07-28)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-150-2023-07-26" class="nav-link">Version 1.5.0 (2023-07-26)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-143-2023-05-02" class="nav-link">Version 1.4.3 (2023-05-02)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-142-2022-11-01" class="nav-link">Version 1.4.2 (2022-11-01)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-141-2022-10-15" class="nav-link">Version 1.4.1 (2022-10-15)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-140-2022-09-27" class="nav-link">Version 1.4.0 (2022-09-27)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-131-2022-07-19" class="nav-link">Version 1.3.1 (2022-07-19)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-130-2022-03-26" class="nav-link">Version 1.3.0 (2022-03-26)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-124-2022-03-26" class="nav-link">Version 1.2.4 (2022-03-26)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-123-2021-10-12" class="nav-link">Version 1.2.3 (2021-10-12)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-122-2021-07-18" class="nav-link">Version 1.2.2 (2021-07-18)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-121-2021-06-09" class="nav-link">Version 1.2.1 (2021-06-09)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-12-2021-06-04" class="nav-link">Version 1.2 (2021-06-04)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-112-2020-05-14" class="nav-link">Version 1.1.2 (2020-05-14)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-111-2020-05-12" class="nav-link">Version 1.1.1 (2020-05-12)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-11-2020-02-22" class="nav-link">Version 1.1 (2020-02-22)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-104-2018-09-07" class="nav-link">Version 1.0.4 (2018-09-07)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-103-2018-08-29" class="nav-link">Version 1.0.3 (2018-08-29)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-102-2018-08-22" class="nav-link">Version 1.0.2 (2018-08-22)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-101-2018-08-13" class="nav-link">Version 1.0.1 (2018-08-13)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-10-2018-08-03" class="nav-link">Version 1.0 (2018-08-03)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0175-2018-07-06" class="nav-link">Version 0.17.5 (2018-07-06)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0174-2018-06-08" class="nav-link">Version 0.17.4 (2018-06-08)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0173-2018-03-07" class="nav-link">Version 0.17.3 (2018-03-07)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0172-2017-11-15" class="nav-link">Version 0.17.2 (2017-11-15)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0171-2017-10-30" class="nav-link">Version 0.17.1 (2017-10-30)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0170-2017-10-19" class="nav-link">Version 0.17.0 (2017-10-19)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0163-2017-04-04" class="nav-link">Version 0.16.3 (2017-04-04)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0162-2017-03-13" class="nav-link">Version 0.16.2 (2017-03-13)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0161-2016-12-22" class="nav-link">Version 0.16.1 (2016-12-22)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-016-2016-11-04" class="nav-link">Version 0.16 (2016-11-04)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0153-2016-02-18" class="nav-link">Version 0.15.3 (2016-02-18)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0152-2016-02-08" class="nav-link">Version 0.15.2 (2016-02-08)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0151-2016-01-30" class="nav-link">Version 0.15.1 (2016-01-30)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0150-2016-01-21" class="nav-link">Version 0.15.0 (2016-01-21)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0140-2015-06-09" class="nav-link">Version 0.14.0 (2015-06-09)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0133-2015-06-02" class="nav-link">Version 0.13.3 (2015-06-02)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0132-2015-05-30" class="nav-link">Version 0.13.2 (2015-05-30)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0131-2015-05-27" class="nav-link">Version 0.13.1 (2015-05-27)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0130-2015-05-26" class="nav-link">Version 0.13.0 (2015-05-26)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0122-2015-04-22" class="nav-link">Version 0.12.2 (2015-04-22)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0121-2015-04-14" class="nav-link">Version 0.12.1 (2015-04-14)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0120-2015-04-14" class="nav-link">Version 0.12.0 (2015-04-14)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0111-2014-11-20" class="nav-link">Version 0.11.1 (2014-11-20)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0110-2014-11-18" class="nav-link">Version 0.11.0 (2014-11-18)</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#version-0100-2014-10-29" class="nav-link">Version 0.10.0 (2014-10-29)</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="release-notes">Release Notes<a class="headerlink" href="#release-notes" title="Permanent link"></a></h1>
<hr />
<h2 id="upgrading">Upgrading<a class="headerlink" href="#upgrading" title="Permanent link"></a></h2>
<p>To upgrade MkDocs to the latest version, use pip:</p>
<pre class="highlight"><code class="language-bash">pip install -U mkdocs</code></pre>
<p>You can determine your currently installed version using <code>mkdocs --version</code>:</p>
<pre class="highlight"><code class="language-console">$ mkdocs --version
mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10)</code></pre>
<h2 id="maintenance-team">Maintenance team<a class="headerlink" href="#maintenance-team" title="Permanent link"></a></h2>
<p>The current and past members of the MkDocs team.</p>
<ul>
<li><a href="https://github.com/tomchristie/">@tomchristie</a></li>
<li><a href="https://github.com/d0ugal/">@d0ugal</a></li>
<li><a href="https://github.com/waylan/">@waylan</a></li>
<li><a href="https://github.com/oprypin/">@oprypin</a></li>
<li><a href="https://github.com/ultrabug/">@ultrabug</a></li>
</ul>
<h2 id="version-161-2024-08-30">Version 1.6.1 (2024-08-30)<a class="headerlink" href="#version-161-2024-08-30" title="Permanent link"></a></h2>
<h3 id="fixed">Fixed<a class="headerlink" href="#fixed" title="Permanent link"></a></h3>
<ul>
<li>Fix build error when environment variable <code>SOURCE_DATE_EPOCH=0</code> is set. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3795" title="GitHub Issue mkdocs/mkdocs #3795">#3795</a></li>
<li>Fix build error when <code>mkdocs_theme.yml</code> config is empty. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3700" title="GitHub Issue mkdocs/mkdocs #3700">#3700</a></li>
<li>Support <code>python -W</code> and <code>PYTHONWARNINGS</code> instead of overriding the configuration. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3809" title="GitHub Issue mkdocs/mkdocs #3809">#3809</a></li>
<li>Support running with Docker under strict mode, by removing <code>0.0.0.0</code> dev server warning. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3784" title="GitHub Issue mkdocs/mkdocs #3784">#3784</a></li>
<li>Drop unnecessary <code>changefreq</code> from <code>sitemap.xml</code>. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3629" title="GitHub Issue mkdocs/mkdocs #3629">#3629</a></li>
<li>Fix JavaScript console error when closing menu dropdown. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3774" title="GitHub Issue mkdocs/mkdocs #3774">#3774</a></li>
<li>Fix JavaScript console error that occur on repeated clicks. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3730" title="GitHub Issue mkdocs/mkdocs #3730">#3730</a></li>
<li>Fix JavaScript console error that can occur on dropdown selections. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3694" title="GitHub Issue mkdocs/mkdocs #3694">#3694</a></li>
</ul>
<h3 id="added">Added<a class="headerlink" href="#added" title="Permanent link"></a></h3>
<ul>
<li>Added translations for Dutch. <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3804" title="GitHub Issue mkdocs/mkdocs #3804">#3804</a></li>
<li>Added and updated translations for Chinese (Simplified). <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3684" title="GitHub Issue mkdocs/mkdocs #3684">#3684</a></li>
</ul>
<h2 id="version-160-2024-04-20">Version 1.6.0 (2024-04-20)<a class="headerlink" href="#version-160-2024-04-20" title="Permanent link"></a></h2>
<h3 id="local-preview">Local preview<a class="headerlink" href="#local-preview" title="Permanent link"></a></h3>
<ul>
<li>
<p><code>mkdocs serve</code> no longer locks up the browser when more than 5 tabs are open. This is achieved by closing the polling connection whenever a tab becomes inactive. Background tabs will no longer auto-reload either - that will instead happen as soon the tab is opened again. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3391" title="GitHub Issue mkdocs/mkdocs #3391">#3391</a></p>
</li>
<li>
<p>New flag <code>serve --open</code> to open the site in a browser.<br />
After the first build is finished, this flag will cause the default OS Web browser to be opened at the home page of the local site.<br />
Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3500" title="GitHub Issue mkdocs/mkdocs #3500">#3500</a></p>
</li>
</ul>
<h4 id="drafts">Drafts<a class="headerlink" href="#drafts" title="Permanent link"></a></h4>
<div class="admonition danger">
<p class="admonition-title">Changed from version 1.5</p>
</div>
<p><strong>The <code>exclude_docs</code> config was split up into two separate concepts.</strong></p>
<p>The <code>exclude_docs</code> config no longer has any special behavior for <code>mkdocs serve</code> - it now always completely excludes the listed documents from the site.</p>
<p>If you wish to use the "drafts" functionality like the <code>exclude_docs</code> key used to do in MkDocs 1.5, please switch to the <strong>new config key <code>draft_docs</code></strong>.</p>
<p>See <a href="../../user-guide/configuration/#exclude_docs">documentation</a>.</p>
<p>Other changes:</p>
<ul>
<li>Reduce warning levels when a "draft" page has a link to a non-existent file. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3449" title="GitHub Issue mkdocs/mkdocs #3449">#3449</a></li>
</ul>
<h3 id="update-to-deduction-of-page-titles">Update to deduction of page titles<a class="headerlink" href="#update-to-deduction-of-page-titles" title="Permanent link"></a></h3>
<p>MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases.</p>
<p>Now tags are always fully sanitized from the title. Though it still remains the case that <a class="autorefs autorefs-internal" href="../../dev-guide/themes/#mkdocs.structure.pages.Page.title"><code>Page.title</code></a> is expected to contain HTML entities and is passed directly to the themes.</p>
<p>Images (notably, emojis in some extensions) get preserved in the title only through their <code>alt</code> attribute's value.</p>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3564" title="GitHub Issue mkdocs/mkdocs #3564">#3564</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3578" title="GitHub Issue mkdocs/mkdocs #3578">#3578</a></p>
<h3 id="themes">Themes<a class="headerlink" href="#themes" title="Permanent link"></a></h3>
<ul>
<li>Built-in themes now also support Polish language (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3613" title="GitHub Issue mkdocs/mkdocs #3613">#3613</a>)</li>
</ul>
<h4 id="readthedocs-theme">"readthedocs" theme<a class="headerlink" href="#readthedocs-theme" title="Permanent link"></a></h4>
<ul>
<li>
<p>Fix: "readthedocs" theme can now correctly handle deeply nested nav configurations (over 2 levels deep), without confusedly expanding all sections and jumping around vertically. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3464" title="GitHub Issue mkdocs/mkdocs #3464">#3464</a>)</p>
</li>
<li>
<p>Fix: "readthedocs" theme now shows a link to the repository (with a generic logo) even when isn't one of the 3 known hosters. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3435" title="GitHub Issue mkdocs/mkdocs #3435">#3435</a>)</p>
</li>
<li>
<p>"readthedocs" theme now also has translation for the word "theme" in the footer that mistakenly always remained in English. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3613" title="GitHub Issue mkdocs/mkdocs #3613">#3613</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3625" title="GitHub Issue mkdocs/mkdocs #3625">#3625</a>)</p>
</li>
</ul>
<h4 id="mkdocs-theme">"mkdocs" theme<a class="headerlink" href="#mkdocs-theme" title="Permanent link"></a></h4>
<p>The "mkdocs" theme got a big update to a newer version of Bootstrap, meaning a slight overhaul of styles. Colors (most notably of admonitions) have much better contrast.</p>
<p>The "mkdocs" theme now has support for dark mode - both automatic (based on the OS/browser setting) and with a manual toggle. Both of these options are <strong>not</strong> enabled by default and need to be configured explicitly.<br />
See <code>color_mode</code>, <code>user_color_mode_toggle</code> in <a href="../../user-guide/choosing-your-theme/#mkdocs"><strong>documentation</strong></a>.</p>
<div class="admonition warning">
<p class="admonition-title">Possible breaking change</p>
<p>jQuery is no longer included into the "mkdocs" theme. If you were relying on it in your scripts, you will need to separately add it first (into mkdocs.yml) as an extra script:</p>
<pre class="highlight"><code class="language-yaml">extra_javascript:
- https://code.jquery.com/jquery-3.7.1.min.js</code></pre>
<p>Or even better if the script file is copied and included from your docs dir.</p>
</div>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3493" title="GitHub Issue mkdocs/mkdocs #3493">#3493</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3649" title="GitHub Issue mkdocs/mkdocs #3649">#3649</a></p>
<h3 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link"></a></h3>
<h4 id="new-enabled-setting-for-all-plugins">New "<code>enabled</code>" setting for all plugins<a class="headerlink" href="#new-enabled-setting-for-all-plugins" title="Permanent link"></a></h4>
<p>You may have seen some plugins take up the convention of having a setting <code>enabled: false</code> (or usually controlled through an environment variable) to make the plugin do nothing.</p>
<p>Now <em>every</em> plugin has this setting. Plugins can still <em>choose</em> to implement this config themselves and decide how it behaves (and unless they drop older versions of MkDocs, they still should for now), but now there's always a fallback for every plugin.</p>
<p>See <a href="../../user-guide/configuration/#enabled-option"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3395" title="GitHub Issue mkdocs/mkdocs #3395">#3395</a></p>
<h3 id="validation">Validation<a class="headerlink" href="#validation" title="Permanent link"></a></h3>
<h4 id="validation-of-hyperlinks-between-pages">Validation of hyperlinks between pages<a class="headerlink" href="#validation-of-hyperlinks-between-pages" title="Permanent link"></a></h4>
<h5 id="absolute-links">Absolute links<a class="headerlink" href="#absolute-links" title="Permanent link"></a></h5>
<blockquote>
<p>Historically, within Markdown, MkDocs only recognized <strong>relative</strong> links that lead to another physical <code>*.md</code> document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected or, more recently, warned against).</p>
</blockquote>
<p>If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly.</p>
<p>If you set the setting <code>validation.links.absolute_links</code> to the new value <code>relative_to_docs</code>, all Markdown links starting with <code>/</code> will be understood as being relative to the <code>docs_dir</code> root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably.</p>
<p>So, now any document (e.g. "dir1/foo.md") can link to the document "dir2/bar.md" as <code>[link](/dir2/bar.md)</code>, in addition to the previously only correct way <code>[link](../dir2/bar.md)</code>.</p>
<p>You have to enable the setting, though. The default is still to just skip any processing of such links.</p>
<p>See <a href="../../user-guide/configuration/#validation-of-absolute-links"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3485" title="GitHub Issue mkdocs/mkdocs #3485">#3485</a></p>
<h6 id="absolute-links-within-nav">Absolute links within nav<a class="headerlink" href="#absolute-links-within-nav" title="Permanent link"></a></h6>
<p>Absolute links within the <code>nav:</code> config were also always skipped. It is now possible to also validate them in the same way with <code>validation.nav.absolute_links</code>. Though it makes a bit less sense because then the syntax is simply redundant with the syntax that comes without the leading slash.</p>
<h5 id="anchors">Anchors<a class="headerlink" href="#anchors" title="Permanent link"></a></h5>
<p>There is a new config setting that is recommended to enable warnings for:</p>
<pre class="highlight"><code class="language-yaml">validation:
anchors: warn</code></pre>
<p>Example of a warning that this can produce:</p>
<pre class="highlight"><code class="language-text">WARNING - Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.</code></pre>
<p>Any of the below methods of declaring an anchor will be detected by MkDocs:</p>
<pre class="highlight"><code class="language-markdown">## Heading producing an anchor
## Another heading {#custom-anchor-for-heading-using-attr-list}
&lt;a id="raw-anchor"&gt;&lt;/a&gt;
[](){#markdown-anchor-using-attr-list}</code></pre>
<p>Plugins and extensions that insert anchors, in order to be compatible with this, need to be developed as treeprocessors that insert <code>etree</code> elements as their mode of operation, rather than raw HTML which is undetectable for this purpose.</p>
<p>If you as a user are dealing with falsely reported missing anchors and there's no way to resolve this, you can choose to disable these messages by setting this option to <code>ignore</code> (and they are at INFO level by default anyway).</p>
<p>See <a href="../../user-guide/configuration/#validation"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3463" title="GitHub Issue mkdocs/mkdocs #3463">#3463</a></p>
<p>Other changes:</p>
<ul>
<li>
<p>When the <code>nav</code> config is not specified at all, the <code>not_in_nav</code> setting (originally added in 1.5.0) gains an additional behavior: documents covered by <code>not_in_nav</code> will not be part of the automatically deduced navigation. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3443" title="GitHub Issue mkdocs/mkdocs #3443">#3443</a></p>
</li>
<li>
<p>Fix: the <code>!relative</code> YAML tag for <code>markdown_extensions</code> (originally added in 1.5.0) - it was broken in many typical use cases.</p>
<p>See <a href="../../user-guide/configuration/#paths-relative-to-the-current-file-or-site"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3466" title="GitHub Issue mkdocs/mkdocs #3466">#3466</a></p>
</li>
<li>
<p>Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3437" title="GitHub Issue mkdocs/mkdocs #3437">#3437</a></p>
</li>
<li>
<p>MkDocs used to shorten error messages for unexpected errors such as "file not found", but that is no longer the case, the full error message and stack trace will be possible to see (unless the error has a proper handler, of course). Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3445" title="GitHub Issue mkdocs/mkdocs #3445">#3445</a></p>
</li>
</ul>
<h3 id="upgrades-for-plugin-developers">Upgrades for plugin developers<a class="headerlink" href="#upgrades-for-plugin-developers" title="Permanent link"></a></h3>
<h4 id="plugins-can-add-multiple-handlers-for-the-same-event-type-at-multiple-priorities">Plugins can add multiple handlers for the same event type, at multiple priorities<a class="headerlink" href="#plugins-can-add-multiple-handlers-for-the-same-event-type-at-multiple-priorities" title="Permanent link"></a></h4>
<p>See <a class="autorefs autorefs-internal" href="../../dev-guide/plugins/#mkdocs.plugins.CombinedEvent"><code>mkdocs.plugins.CombinedEvent</code></a> in <a href="../../dev-guide/plugins/#event-priorities"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3448" title="GitHub Issue mkdocs/mkdocs #3448">#3448</a></p>
<h4 id="enabling-true-generated-files-and-expanding-the-file-api">Enabling true generated files and expanding the <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File"><code>File</code></a> API<a class="headerlink" href="#enabling-true-generated-files-and-expanding-the-file-api" title="Permanent link"></a></h4>
<p>See <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File"><strong>documentation</strong></a>.</p>
<ul>
<li>
<p>There is a new pair of attributes <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.content_string"><code>File.content_string</code></a>/<a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.content_bytes"><code>content_bytes</code></a> that becomes the official API for obtaining the content of a file and is used by MkDocs itself.</p>
<p>This replaces the old approach where one had to manually read the file located at <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.abs_src_path"><code>File.abs_src_path</code></a>, although that is still the primary action that these new attributes do under the hood.</p>
</li>
<li>
<p>The content of a <code>File</code> can be backed by a string and no longer has to be a real existing file at <code>abs_src_path</code>.</p>
<p>It is possible to <strong>set</strong> the attribute <code>File.content_string</code> or <code>File.content_bytes</code> and it will take precedence over <code>abs_src_path</code>.</p>
<p>Further, <code>abs_src_path</code> is no longer guaranteed to be present and can be <code>None</code> instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute.</p>
</li>
<li>
<p>There is a new constructor <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.generated"><code>File.generated()</code></a> that should be used by plugins instead of the <code>File()</code> constructor. It is much more convenient because one doesn't need to manually look up the values such as <code>docs_dir</code> and <code>use_directory_urls</code>. Its signature is one of:</p>
<pre class="highlight"><code class="language-python">f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str)</code></pre>
<p>This way, it is now extremely easy to add a virtual file even from a hook:</p>
<pre class="highlight"><code class="language-python">def on_files(files: Files, config: MkDocsConfig):
files.append(File.generated(config, 'fake/path.md', content="Hello, world!"))</code></pre>
<p>For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused <code>docs_dir</code>.</p>
</li>
<li>
<p>There is a new attribute <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.generated_by"><code>File.generated_by</code></a> that arose by convention - for generated files it should be set to the name of the plugin (the key in the <code>plugins:</code> collection) that produced this file. This attribute is populated automatically when using the <code>File.generated()</code> constructor.</p>
</li>
<li>
<p>It is possible to set the <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.edit_uri"><code>edit_uri</code></a> attribute of a <code>File</code>, for example from a plugin or hook, to make it different from the default (equal to <code>src_uri</code>), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the <code>edit_uri</code> to that source file or script accordingly.</p>
</li>
<li>
<p>The <code>File</code> object now stores its original <code>src_dir</code>, <code>dest_dir</code>, <code>use_directory_urls</code> values as attributes.</p>
</li>
<li>
<p>Fields of <code>File</code> are computed on demand but cached. Only the three above attributes are primary ones, and partly also <a class="autorefs autorefs-internal" href="../../dev-guide/api/#mkdocs.structure.files.File.dest_uri"><code>dest_uri</code></a>. This way, it is possible to, for example, overwrite <code>dest_uri</code> of a <code>File</code>, and <code>abs_dest_path</code> will be calculated based on it. However you need to clear the attribute first using <code>del f.abs_dest_path</code>, because the values are cached.</p>
</li>
<li>
<p><code>File</code> instances are now hashable (can be used as keys of a <code>dict</code>). Two files can no longer be considered "equal" unless it's the exact same instance of <code>File</code>.</p>
</li>
</ul>
<p>Other changes:</p>
<ul>
<li>
<p>The internal storage of <code>File</code> objects inside a <code>Files</code> object has been reworked, so any plugins that choose to access <code>Files._files</code> will get a deprecation warning.</p>
</li>
<li>
<p>The order of <code>File</code> objects inside a <code>Files</code> collection is no longer significant when automatically inferring the <code>nav</code>. They get forcibly sorted according to the default alphabetic order.</p>
</li>
</ul>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3451" title="GitHub Issue mkdocs/mkdocs #3451">#3451</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3463" title="GitHub Issue mkdocs/mkdocs #3463">#3463</a></p>
<h3 id="hooks-and-debugging">Hooks and debugging<a class="headerlink" href="#hooks-and-debugging" title="Permanent link"></a></h3>
<ul>
<li>
<p>Hook files can now import adjacent *.py files using the <code>import</code> statement. Previously this was possible to achieve only through a <code>sys.path</code> workaround. See the new mention in <a href="../../user-guide/configuration/#hooks">documentation</a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3568" title="GitHub Issue mkdocs/mkdocs #3568">#3568</a></p>
</li>
<li>
<p>Verbose <code>-v</code> log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3444" title="GitHub Issue mkdocs/mkdocs #3444">#3444</a></p>
</li>
</ul>
<h3 id="deprecations">Deprecations<a class="headerlink" href="#deprecations" title="Permanent link"></a></h3>
<ul>
<li>
<p>Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3429" title="GitHub Issue mkdocs/mkdocs #3429">#3429</a></p>
</li>
<li>
<p>The theme config file <code>mkdocs_theme.yml</code> no longer executes YAML tags. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3465" title="GitHub Issue mkdocs/mkdocs #3465">#3465</a></p>
</li>
<li>
<p>The plugin event <code>on_page_read_source</code> is soft-deprecated because there is always a better alternative to it (see the new <code>File</code> API or just <code>on_page_markdown</code>, depending on the desired interaction).</p>
<p>When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case.</p>
<p>See <a href="../../dev-guide/plugins/#on_page_read_source"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3503" title="GitHub Issue mkdocs/mkdocs #3503">#3503</a></p>
</li>
</ul>
<h4 id="api-deprecations">API deprecations<a class="headerlink" href="#api-deprecations" title="Permanent link"></a></h4>
<ul>
<li>
<p>It is no longer allowed to set <code>File.page</code> to a type other than <code>Page</code> or a subclass thereof. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3443" title="GitHub Issue mkdocs/mkdocs #3443">#3443</a> - following the deprecation in version 1.5.3 and <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3381" title="GitHub Issue mkdocs/mkdocs #3381">#3381</a>.</p>
</li>
<li>
<p><code>Theme._vars</code> is deprecated - use <code>theme['foo']</code> instead of <code>theme._vars['foo']</code></p>
</li>
<li>
<p><code>utils</code>: <code>modified_time()</code>, <code>get_html_path()</code>, <code>get_url_path()</code>, <code>is_html_file()</code>, <code>is_template_file()</code> are removed. <code>path_to_url()</code> is deprecated.</p>
</li>
<li>
<p><code>LiveReloadServer.watch()</code> no longer accepts a custom callback.</p>
</li>
</ul>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3429" title="GitHub Issue mkdocs/mkdocs #3429">#3429</a></p>
<h3 id="misc">Misc<a class="headerlink" href="#misc" title="Permanent link"></a></h3>
<ul>
<li>The <code>sitemap.xml.gz</code> file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3460" title="GitHub Issue mkdocs/mkdocs #3460">#3460</a></li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.5.3...1.6.0">commit log</a>.</p>
<h2 id="version-153-2023-09-18">Version 1.5.3 (2023-09-18)<a class="headerlink" href="#version-153-2023-09-18" title="Permanent link"></a></h2>
<ul>
<li>
<p>Fix <code>mkdocs serve</code> sometimes locking up all browser tabs when navigating quickly (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3390" title="GitHub Issue mkdocs/mkdocs #3390">#3390</a>)</p>
</li>
<li>
<p>Add many new supported languages for "search" plugin - update lunr-languages to 1.12.0 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3334" title="GitHub Issue mkdocs/mkdocs #3334">#3334</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.5.0): In "readthedocs" theme the styling of "breadcrumb navigation" was broken for nested pages (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3383" title="GitHub Issue mkdocs/mkdocs #3383">#3383</a>)</p>
</li>
<li>
<p>Built-in themes now also support Chinese (Traditional, Taiwan) language (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3154" title="GitHub Issue mkdocs/mkdocs #3154">#3154</a>)</p>
</li>
<li>
<p>Plugins can now set <code>File.page</code> to their own subclass of <code>Page</code>. There is also now a warning if <code>File.page</code> is set to anything other than a strict subclass of <code>Page</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3367" title="GitHub Issue mkdocs/mkdocs #3367">#3367</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3381" title="GitHub Issue mkdocs/mkdocs #3381">#3381</a>)</p>
<p>Note that just instantiating a <code>Page</code> <a href="https://github.com/mkdocs/mkdocs/blob/f94ab3f62d0416d484d81a0c695c8ca86ab3b975/mkdocs/structure/pages.py#L34">sets the file automatically</a>, so care needs to be taken not to create an unneeded <code>Page</code>.</p>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.5.2...1.5.3">commit log</a>.</p>
<h2 id="version-152-2023-08-02">Version 1.5.2 (2023-08-02)<a class="headerlink" href="#version-152-2023-08-02" title="Permanent link"></a></h2>
<ul>
<li>
<p>Bugfix (regression in 1.5.0): Restore functionality of <code>--no-livereload</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3320" title="GitHub Issue mkdocs/mkdocs #3320">#3320</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.5.0): The new page title detection would sometimes be unable to drop anchorlinks - fix that. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3325" title="GitHub Issue mkdocs/mkdocs #3325">#3325</a>)</p>
</li>
<li>
<p>Partly bring back pre-1.5 API: <code>extra_javascript</code> items will once again be mostly strings, and only sometimes <code>ExtraScriptValue</code> (when the extra <code>script</code> functionality is used).</p>
<p>Plugins should be free to append strings to <code>config.extra_javascript</code>, but when reading the values, they must still make sure to read it as <code>str(value)</code> in case it is an <code>ExtraScriptValue</code> item. For querying the attributes such as <code>.type</code> you need to check <code>isinstance</code> first. Static type checking will guide you in that. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3324" title="GitHub Issue mkdocs/mkdocs #3324">#3324</a>)</p>
</li>
</ul>
<p>See <a href="https://github.com/mkdocs/mkdocs/compare/1.5.1...1.5.2">commit log</a>.</p>
<h2 id="version-151-2023-07-28">Version 1.5.1 (2023-07-28)<a class="headerlink" href="#version-151-2023-07-28" title="Permanent link"></a></h2>
<ul>
<li>
<p>Bugfix (regression in 1.5.0): Make it possible to treat <code>ExtraScriptValue</code> as a path. This lets some plugins still work despite the breaking change.</p>
</li>
<li>
<p>Bugfix (regression in 1.5.0): Prevent errors for special setups that have 3 conflicting files, such as <code>index.html</code>, <code>index.md</code> <em>and</em> <code>README.md</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3314" title="GitHub Issue mkdocs/mkdocs #3314">#3314</a>)</p>
</li>
</ul>
<p>See <a href="https://github.com/mkdocs/mkdocs/compare/1.5.0...1.5.1">commit log</a>.</p>
<h2 id="version-150-2023-07-26">Version 1.5.0 (2023-07-26)<a class="headerlink" href="#version-150-2023-07-26" title="Permanent link"></a></h2>
<h3 id="new-command-mkdocs-get-deps">New command <code>mkdocs get-deps</code><a class="headerlink" href="#new-command-mkdocs-get-deps" title="Permanent link"></a></h3>
<p>This command guesses the Python dependencies that a MkDocs site requires in order to build. It simply prints the PyPI packages that need to be installed. In the terminal it can be combined directly with an installation command as follows:</p>
<pre class="highlight"><code class="language-bash">pip install $(mkdocs get-deps)</code></pre>
<p>The idea is that right after running this command, you can directly follow it up with <code>mkdocs build</code> and it will almost always "just work", without needing to think which dependencies to install.</p>
<p>The way it works is by scanning <code>mkdocs.yml</code> for <code>themes:</code>, <code>plugins:</code>, <code>markdown_extensions:</code> items and doing a reverse lookup based on a large list of known projects (catalog, see below).</p>
<p>Of course, you're welcome to use a "virtualenv" with such a command. Also note that for environments that require stability (for example CI) directly installing deps in this way is not a very reliable approach as it precludes dependency pinning.</p>
<p>The command allows overriding which config file is used (instead of <code>mkdocs.yml</code> in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See <a href="../../user-guide/cli/#mkdocs-get-deps"><code>mkdocs get-deps --help</code></a>.</p>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3205" title="GitHub Issue mkdocs/mkdocs #3205">#3205</a></p>
<h3 id="mkdocs-has-an-official-catalog-of-plugins">MkDocs has an official catalog of plugins<a class="headerlink" href="#mkdocs-has-an-official-catalog-of-plugins" title="Permanent link"></a></h3>
<p>Check out <a href="https://github.com/mkdocs/catalog">https://github.com/mkdocs/catalog</a> and add all your general-purpose plugins, themes and extensions there, so that they can be looked up through <code>mkdocs get-deps</code>.</p>
<p>This was renamed from "best-of-mkdocs" and received significant updates. In addition to <code>pip</code> installation commands, the page now shows the config boilerplate needed to add a plugin.</p>
<h3 id="expanded-validation-of-links">Expanded validation of links<a class="headerlink" href="#expanded-validation-of-links" title="Permanent link"></a></h3>
<h4 id="validated-links-in-markdown">Validated links in Markdown<a class="headerlink" href="#validated-links-in-markdown" title="Permanent link"></a></h4>
<blockquote>
<p>As you may know, within Markdown, MkDocs really only recognizes <strong>relative</strong> links that lead to another physical <code>*.md</code> document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. MkDocs knows that in the output it should turn those <code>*.md</code> links into <code>*.html</code> as appropriate, and it would also always tell you if such a link doesn't actually lead to an existing file.</p>
</blockquote>
<p>However, the checks for links were really loose and had many concessions. For example, links that started with <code>/</code> ("absolute") and links that <em>ended</em> with <code>/</code> were left as is and no warning was shown, which allowed such very fragile links to sneak into site sources: links that happen to work right now but get no validation and links that confusingly need an extra level of <code>..</code> with <code>use_directory_urls</code> enabled.</p>
<p>Now, in addition to validating relative links, MkDocs will print <code>INFO</code> messages for unrecognized types of links (including absolute links). They look like this:</p>
<pre class="highlight"><code class="language-text">INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'?</code></pre>
<p>If you don't want any changes, not even the <code>INFO</code> messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to <code>mkdocs.yml</code> (<strong>not</strong> recommended):</p>
<pre class="highlight"><code class="language-yaml">validation:
absolute_links: ignore
unrecognized_links: ignore</code></pre>
<p>If, on the opposite end, you want these to print <code>WARNING</code> messages and cause <code>mkdocs build --strict</code> to fail, you are recommended to configure these to <code>warn</code> instead.</p>
<p>See <a href="../../user-guide/configuration/#validation"><strong>documentation</strong></a> for actual recommended settings and more details. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3283" title="GitHub Issue mkdocs/mkdocs #3283">#3283</a></p>
<h4 id="validated-links-in-the-nav">Validated links in the nav<a class="headerlink" href="#validated-links-in-the-nav" title="Permanent link"></a></h4>
<p>Links to documents in the <a href="../../user-guide/configuration/#nav"><code>nav</code> configuration</a> now also have configurable validation, though with no changes to the defaults.</p>
<p>You are welcomed to turn on validation for files that were forgotten and excluded from the nav. Example:</p>
<pre class="highlight"><code class="language-yaml">validation:
nav:
omitted_files: warn
absolute_links: warn</code></pre>
<p>This can make the following message appear with the <code>WARNING</code> level (as opposed to <code>INFO</code> as the only option previously), thus being caught by <code>mkdocs --strict</code>:</p>
<pre class="highlight"><code class="language-text">INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: ...</code></pre>
<p>See <a href="../../user-guide/configuration/#validation"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3283" title="GitHub Issue mkdocs/mkdocs #3283">#3283</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1755" title="GitHub Issue mkdocs/mkdocs #1755">#1755</a></p>
<h4 id="mark-docs-as-intentionally-not-in-nav">Mark docs as intentionally "not in nav"<a class="headerlink" href="#mark-docs-as-intentionally-not-in-nav" title="Permanent link"></a></h4>
<p>There is a new config <code>not_in_nav</code>. With it, you can mark particular patterns of files as exempt from the above <code>omitted_files</code> warning type; no messages will be printed for them anymore. (As a corollary, setting this config to <code>*</code> is the same as ignoring <code>omitted_files</code> altogether.)</p>
<p>This is useful if you generally like these warnings about files that were forgotten from the nav, but still have some pages that you knowingly excluded from the nav and just want to build and copy them.</p>
<p>The <code>not_in_nav</code> config is a set of gitignore-like patterns. See the next section for an explanation of another such config.</p>
<p>See <a href="../../user-guide/configuration/#not_in_nav"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3224" title="GitHub Issue mkdocs/mkdocs #3224">#3224</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1888" title="GitHub Issue mkdocs/mkdocs #1888">#1888</a></p>
<h3 id="excluded-doc-files">Excluded doc files<a class="headerlink" href="#excluded-doc-files" title="Permanent link"></a></h3>
<p>There is a new config <code>exclude_docs</code> that tells MkDocs to ignore certain files under <code>docs_dir</code> and <em>not</em> copy them to the built <code>site</code> as part of the build.</p>
<p>Historically MkDocs would always ignore file names starting with a dot, and that's all. Now this is all configurable: you can un-ignore these and/or ignore more patterns of files.</p>
<p>The <code>exclude_docs</code> config follows the <a href="https://git-scm.com/docs/gitignore#_pattern_format">.gitignore pattern format</a> and is specified as a multiline YAML string. For example:</p>
<pre class="highlight"><code class="language-yaml">exclude_docs: |
*.py # Excludes e.g. docs/hooks/foo.py
/requirements.txt # Excludes docs/requirements.txt</code></pre>
<p>Validation of links (described above) is also affected by <code>exclude_docs</code>. During <code>mkdocs serve</code> the messages explain the interaction, whereas during <code>mkdocs build</code> excluded files are as good as nonexistent.</p>
<p>As an additional related change, if you have a need to have both <code>README.md</code> and <code>index.md</code> files in a directory but publish only one of them, you can now use this feature to explicitly ignore one of them and avoid warnings.</p>
<p>See <a href="../../user-guide/configuration/#exclude_docs"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3224" title="GitHub Issue mkdocs/mkdocs #3224">#3224</a></p>
<h4 id="drafts_1">Drafts<a class="headerlink" href="#drafts_1" title="Permanent link"></a></h4>
<div class="admonition danger">
<p class="admonition-title">Dropped from version 1.6:</p>
<p>The <code>exclude_docs</code> config no longer applies the "drafts" functionality for <code>mkdocs serve</code>. This was renamed to <a href="../../user-guide/configuration/#draft_docs"><code>draft_docs</code></a>.</p>
</div>
<p>The <code>exclude_docs</code> config has another behavior: all excluded Markdown pages will still be previewable in <code>mkdocs serve</code> only, just with a "DRAFT" marker on top. Then they will of course be excluded from <code>mkdocs build</code> or <code>gh-deploy</code>.</p>
<p>If you don't want <code>mkdocs serve</code> to have any special behaviors and instead want it to perform completely normal builds, use the new flag <code>mkdocs serve --clean</code>.</p>
<p>See <a href="../../user-guide/configuration/#exclude_docs"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3224" title="GitHub Issue mkdocs/mkdocs #3224">#3224</a></p>
<h3 id="mkdocs-serve-no-longer-exits-after-build-errors"><code>mkdocs serve</code> no longer exits after build errors<a class="headerlink" href="#mkdocs-serve-no-longer-exits-after-build-errors" title="Permanent link"></a></h3>
<p>If there was an error (from the config or a plugin) during a site re-build, <code>mkdocs serve</code> used to exit after printing a stack trace. Now it will simply freeze the server until the author edits the files to fix the problem, and then will keep reloading.</p>
<p>But errors on the <em>first</em> build still cause <code>mkdocs serve</code> to exit, as before.</p>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3255" title="GitHub Issue mkdocs/mkdocs #3255">#3255</a></p>
<h3 id="page-titles-will-be-deduced-from-any-style-of-heading">Page titles will be deduced from any style of heading<a class="headerlink" href="#page-titles-will-be-deduced-from-any-style-of-heading" title="Permanent link"></a></h3>
<p>MkDocs always had the ability to infer the title of a page (if it's not specified in the <code>nav</code>) based on the first line of the document, if it had a <code>&lt;h1&gt;</code> heading that had to written starting with the exact character <code>#</code>. Now any style of Markdown heading is understood (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1886" title="GitHub Issue mkdocs/mkdocs #1886">#1886</a>). Due to the previous simplistic parsing, it was also impossible to use <code>attr_list</code> attributes in that first heading (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3136" title="GitHub Issue mkdocs/mkdocs #3136">#3136</a>). Now that is also fixed.</p>
<h3 id="markdown-extensions-can-use-paths-relative-to-the-current-document">Markdown extensions can use paths relative to the current document<a class="headerlink" href="#markdown-extensions-can-use-paths-relative-to-the-current-document" title="Permanent link"></a></h3>
<p>This is aimed at extensions such as <code>pymdownx.snippets</code> or <code>markdown_include.include</code>: you can now specify their include paths to be relative to the currently rendered Markdown document, or relative to the <code>docs_dir</code>. Any other extension can of course also make use of the new <code>!relative</code> YAML tag.</p>
<pre class="highlight"><code class="language-yaml">markdown_extensions:
- pymdownx.snippets:
base_path: !relative</code></pre>
<p>See <a href="../../user-guide/configuration/#paths-relative-to-the-current-file-or-site"><strong>documentation</strong></a>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2154" title="GitHub Issue mkdocs/mkdocs #2154">#2154</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3258" title="GitHub Issue mkdocs/mkdocs #3258">#3258</a></p>
<h3 id="script-tags-can-specify-typemodule-and-other-attributes"><code>&lt;script&gt;</code> tags can specify <code>type="module"</code> and other attributes<a class="headerlink" href="#script-tags-can-specify-typemodule-and-other-attributes" title="Permanent link"></a></h3>
<p>In <code>extra_javascript</code>, if you use the <code>.mjs</code> file extension or explicitly specify a <code>type: module</code> key, the script will be added with the <code>type="module"</code> attribute. <code>defer: true</code> and <code>async: true</code> keys are also available.</p>
<p>See <a href="../../user-guide/configuration/#extra_javascript">updated <strong>documentation</strong> for <code>extra_javascript</code></a>.</p>
<p><strong>At first this is only supported in built-in themes, other themes need to follow up, see below.</strong></p>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3237" title="GitHub Issue mkdocs/mkdocs #3237">#3237</a></p>
<h3 id="changes-for-theme-developers-action-required">Changes for theme developers (action required!)<a class="headerlink" href="#changes-for-theme-developers-action-required" title="Permanent link"></a></h3>
<p>Using the construct <code>{% for script in extra_javascript %}</code> is now fully obsolete because it cannot allow customizing the attributes of the <code>&lt;script&gt;</code> tag. It will keep working but blocks some of MkDocs' features.</p>
<p>Instead, you now need to use <code>config.extra_javascript</code> (which was already the case for a while) and couple it with the new <code>script_tag</code> filter:</p>
<pre class="highlight"><code class="language-django"> {%- for script in config.extra_javascript %}
{{ script | script_tag }}
{%- endfor %}</code></pre>
<p>See <a href="../../dev-guide/themes/#picking-up-css-and-javascript-from-the-config"><strong>documentation</strong></a>.</p>
<h3 id="upgrades-for-plugin-developers_1">Upgrades for plugin developers<a class="headerlink" href="#upgrades-for-plugin-developers_1" title="Permanent link"></a></h3>
<ul>
<li>
<p>Breaking change: <code>config.extra_javascript</code> is no longer a plain list of strings, but instead a list of <code>ExtraScriptValue</code> items. So you can no longer treat the list values as strings. If you want to keep compatibility with old versions, just always reference the items as <code>str(item)</code> instead. And you can still append plain strings to the list if you wish. See information about <code>&lt;script&gt;</code> tags above. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3237" title="GitHub Issue mkdocs/mkdocs #3237">#3237</a></p>
</li>
<li>
<p><code>File</code> has a new attribute <code>inclusion</code>. Its value is calculated from both the <code>exclude_docs</code> and <code>not_in_nav</code> configs, and implements their behavior. Plugins can read this value or write to it. New <code>File</code> instances by default follow whatever the configs say, but plugins can choose to make this decision explicitly, per file.</p>
</li>
<li>
<p>When creating a <code>File</code>, one can now set a <code>dest_uri</code> directly, rather than having to update it (and other dependent attributes) after creation. <a href="https://github.com/mkdocs/mkdocs/commit/d5af6426c52421f1113f6dcc591de1e01bea48bd">Context</a></p>
</li>
<li>
<p>A new config option was added - <code>DictOfItems</code>. Similarly to <code>ListOfItems</code>, it validates a mapping of config options that all have the same type. Keys are arbitrary but always strings. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3242" title="GitHub Issue mkdocs/mkdocs #3242">#3242</a></p>
</li>
<li>
<p>A new function <code>get_plugin_logger</code> was added. In order to opt into a standardized way for plugins to log messages, please use the idiom:</p>
<pre class="highlight"><code class="language-python">log = mkdocs.plugins.get_plugin_logger(__name__)
...
log.info("Hello, world")</code></pre>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3245" title="GitHub Issue mkdocs/mkdocs #3245">#3245</a></p>
</li>
<li>
<p><code>SubConfig</code> config option can be conveniently subclassed with a particular type of config specified. For example, <code>class ExtraScript(SubConfig[ExtraScriptValue]):</code>. To see how this is useful, search for this class in code. <a href="https://github.com/mkdocs/mkdocs/commit/73e503990e3e3504bfe1cb627d41a7e97970687e">Context</a></p>
</li>
<li>
<p>Bugfix: <code>SubConfig</code> had a bug where paths (from <code>FilesystemObject</code> options) were not made relative to the main config file as intended, because <code>config_file_path</code> was not properly inherited to it. This is now fixed. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3265" title="GitHub Issue mkdocs/mkdocs #3265">#3265</a></p>
</li>
<li>
<p><code>Config</code> members now have a way to avoid clashing with Python's reserved words. This is achieved by stripping a trailing underscore from each member's name.</p>
<p>Example of adding an <code>async</code> boolean option that can be set by the user as <code>async: true</code> and read programmatically as <code>config.async_</code>:</p>
<pre class="highlight"><code class="language-python">class ExampleConfig(Config):
async_ = Type(bool, default=False)</code></pre>
<p>Previously making a config key with a reserved name was impossible with new-style schemas. <a href="https://github.com/mkdocs/mkdocs/commit/1db8e884fa7135a49adf7740add5d875a16a18bc">Context</a></p>
</li>
<li>
<p><code>Theme</code> has its attributes properly declared and gained new attributes <code>theme.locale</code>, <code>theme.custom_dir</code>.</p>
</li>
<li>
<p>Some type annotations were made more precise. For example:</p>
<ul>
<li>The <code>context</code> parameter has gained the type <code>TemplateContext</code> (<code>TypedDict</code>). <a href="https://github.com/mkdocs/mkdocs/commit/0f793b9984c7e6a1d53ce874e7d17b6d27ebf4b2">Context</a></li>
<li>The classes <code>Page</code>, <code>Section</code>, <code>Link</code> now have a common base class <code>StructureItem</code>. <a href="https://github.com/mkdocs/mkdocs/commit/01be507e30b05db0a4c44ef05ba62b2098010653">Context</a></li>
<li>Some methods stopped accepting <code>Config</code> and only accept <code>MkDocsConfig</code> as was originally intended. <a href="https://github.com/mkdocs/mkdocs/commit/c459cd24fc0320333f51525e9cf681d4a8370f50">Context</a></li>
<li><code>config.mdx_configs</code> got a proper type. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3229" title="GitHub Issue mkdocs/mkdocs #3229">#3229</a></li>
</ul>
</li>
</ul>
<h3 id="theme-updates">Theme updates<a class="headerlink" href="#theme-updates" title="Permanent link"></a></h3>
<ul>
<li>
<p>Built-in themes mostly stopped relying on <code>&lt;script defer&gt;</code>. This may affect some usages of <code>extra_javascript</code>, mainly remove the need for custom handling of "has the page fully loaded yet". Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3237" title="GitHub Issue mkdocs/mkdocs #3237">#3237</a></p>
</li>
<li>
<p>"mkdocs" theme now has a styling for <code>&gt;</code> blockquotes, previously they were not distinguished at all. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3291" title="GitHub Issue mkdocs/mkdocs #3291">#3291</a></p>
</li>
<li>
<p>"readthedocs" theme was updated to v1.2.0 according to upstream, with improved styles for <code>&lt;kbd&gt;</code> and breadcrumb navigation. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3058" title="GitHub Issue mkdocs/mkdocs #3058">#3058</a></p>
</li>
<li>
<p>Both built-in themes had their version of highlight.js updated to 11.8.0, and jQuery updated to 3.6.0.</p>
</li>
</ul>
<h3 id="bug-fixes">Bug fixes<a class="headerlink" href="#bug-fixes" title="Permanent link"></a></h3>
<h4 id="relative-paths-in-the-nav-can-traverse-above-the-root">Relative paths in the nav can traverse above the root<a class="headerlink" href="#relative-paths-in-the-nav-can-traverse-above-the-root" title="Permanent link"></a></h4>
<p>Regression in 1.2 - relative paths in the nav could no longer traverse above the site's root and were truncated to the root. Although such traversal is discouraged and produces a warning, this was a documented behavior. The behavior is now restored.</p>
<p>Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2752" title="GitHub Issue mkdocs/mkdocs #2752">#2752</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3010" title="GitHub Issue mkdocs/mkdocs #3010">#3010</a></p>
<h4 id="mkdocs-can-accept-the-config-from-stdin">MkDocs can accept the config from stdin<a class="headerlink" href="#mkdocs-can-accept-the-config-from-stdin" title="Permanent link"></a></h4>
<p>This can be used for config overrides on the fly. See updated section at the bottom of <a href="../../user-guide/configuration/#configuration-inheritance">Configuration Inheritance</a>.</p>
<p>The command to use this is <code>mkdocs build -f -</code>. In previous versions doing this led to an error.</p>
<p><a href="https://github.com/mkdocs/mkdocs/commit/d5bb15fa108da86a8e53fb7d84109d8f8d9d6453">Context</a></p>
<h3 id="new-command-line-flags">New command line flags<a class="headerlink" href="#new-command-line-flags" title="Permanent link"></a></h3>
<ul>
<li><code>mkdocs --no-color build</code> disables color output and line wrapping. This option is also available through an environment variable <code>NO_COLOR=true</code>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3282" title="GitHub Issue mkdocs/mkdocs #3282">#3282</a></li>
<li><code>mkdocs build --no-strict</code> overrides the <code>strict</code> config to <code>false</code>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3254" title="GitHub Issue mkdocs/mkdocs #3254">#3254</a></li>
<li><code>mkdocs build -f -</code> (described directly above).</li>
<li><code>mkdocs serve --clean</code> (described above).</li>
<li><code>mkdocs serve --dirty</code> is the new name of <code>mkdocs serve --dirtyreload</code>.</li>
</ul>
<h3 id="deprecations_1">Deprecations<a class="headerlink" href="#deprecations_1" title="Permanent link"></a></h3>
<ul>
<li>
<p><code>extra_javascript</code> underwent a change that can break plugins in rare cases, and it requires attention from theme developers. See respective entries above.</p>
</li>
<li>
<p>Python-Markdown was unpinned from <code>&lt;3.4</code>. That version is known to remove functionality. If you are affected by those removals, you can still choose to pin the version for yourself: <code>Markdown &lt;3.4</code>. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3222" title="GitHub Issue mkdocs/mkdocs #3222">#3222</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2892" title="GitHub Issue mkdocs/mkdocs #2892">#2892</a></p>
</li>
<li>
<p><code>mkdocs.utils.warning_filter</code> now shows a warning about being deprecated. It does nothing since MkDocs 1.2. Consider <code>get_plugin_logger</code> or just logging under <code>mkdocs.plugins.*</code> instead. Context: <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3008" title="GitHub Issue mkdocs/mkdocs #3008">#3008</a></p>
</li>
<li>
<p>Accessing the <code>_vars</code> attribute of a <code>Theme</code> is deprecated - just access the keys directly.</p>
</li>
<li>
<p>Accessing the <code>user_configs</code> attribute of a <code>Config</code> is deprecated. Note: instead of <code>config.user_configs[*]['theme']['custom_dir']</code>, please use the new attribute <code>config.theme.custom_dir</code>.</p>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.4.3...1.5.0">commit log</a>.</p>
<h2 id="version-143-2023-05-02">Version 1.4.3 (2023-05-02)<a class="headerlink" href="#version-143-2023-05-02" title="Permanent link"></a></h2>
<ul>
<li>
<p>Bugfix: for the <code>hooks</code> feature, modules no longer fail to load if using some advanced Python features like dataclasses (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3193" title="GitHub Issue mkdocs/mkdocs #3193">#3193</a>)</p>
</li>
<li>
<p>Bugfix: Don't create <code>None</code> sitemap entries if the page has no populated URL - affects sites that exclude some files from navigation (<a href="https://github.com/mkdocs/mkdocs/commit/07a297b3b4de4a1b49469b1497ee34039b9f38fa"><code>07a297b</code></a>)</p>
</li>
<li>
<p>"readthedocs" theme:</p>
<ul>
<li>Accessibility: add aria labels to Home logo (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3129" title="GitHub Issue mkdocs/mkdocs #3129">#3129</a>) and search inputs (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3046" title="GitHub Issue mkdocs/mkdocs #3046">#3046</a>)</li>
<li>"readthedocs" theme now supports <code>hljs_style:</code> config, same as "mkdocs" theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3199" title="GitHub Issue mkdocs/mkdocs #3199">#3199</a>)</li>
</ul>
</li>
<li>
<p>Translations:</p>
<ul>
<li>Built-in themes now also support Indonesian language (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3154" title="GitHub Issue mkdocs/mkdocs #3154">#3154</a>)</li>
<li>Fixed <code>zh_CN</code> translation (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3125" title="GitHub Issue mkdocs/mkdocs #3125">#3125</a>)</li>
<li><code>tr_TR</code> translation becomes just <code>tr</code> - usage should remain unaffected (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3195" title="GitHub Issue mkdocs/mkdocs #3195">#3195</a>)</li>
</ul>
</li>
</ul>
<p>See <a href="https://github.com/mkdocs/mkdocs/compare/1.4.2...1.4.3">commit log</a>.</p>
<h2 id="version-142-2022-11-01">Version 1.4.2 (2022-11-01)<a class="headerlink" href="#version-142-2022-11-01" title="Permanent link"></a></h2>
<ul>
<li>
<p>Officially support Python 3.11 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3020" title="GitHub Issue mkdocs/mkdocs #3020">#3020</a>)</p>
<div class="admonition new">
<p class="admonition-title">Tip:</p>
<p> Simply upgrading to Python 3.11 can cut off 10-15% of your site's build time.</p>
</div>
</li>
<li>
<p>Support multiple instances of the same plugin (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3027" title="GitHub Issue mkdocs/mkdocs #3027">#3027</a>)</p>
<p>If a plugin is specified multiple times in the list under the <code>plugins:</code> config, that will create 2 (or more) instances of the plugin with their own config each.</p>
<p>Previously this case was unforeseen and, as such, bugged.</p>
<p>Now even though this works, by default a warning will appear from MkDocs anyway, unless the plugin adds a class variable <code>supports_multiple_instances = True</code>.</p>
</li>
<li>
<p>Bugfix (regression in 1.4.1): Don't error when a plugin puts a plain string into <code>warnings</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3016" title="GitHub Issue mkdocs/mkdocs #3016">#3016</a>)</p>
</li>
<li>
<p>Bugfix: Relative links will always render with a trailing slash (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3022" title="GitHub Issue mkdocs/mkdocs #3022">#3022</a>)</p>
<p>Previously under <code>use_directory_urls</code>, links <em>from</em> a sub-page <em>to</em> the main index page rendered as e.g. <code>&lt;a href="../.."&gt;</code> even though in all other cases the links look like <code>&lt;a href="../../"&gt;</code>. This caused unwanted behavior on some combinations of Web browsers and servers. Now this special-case bug was removed.</p>
</li>
<li>
<p>Built-in "mkdocs" theme now also supports Norwegian language (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3024" title="GitHub Issue mkdocs/mkdocs #3024">#3024</a>)</p>
</li>
<li>
<p>Plugin-related warnings look more readable (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3016" title="GitHub Issue mkdocs/mkdocs #3016">#3016</a>)</p>
</li>
</ul>
<p>See <a href="https://github.com/mkdocs/mkdocs/compare/1.4.1...1.4.2">commit log</a>.</p>
<h2 id="version-141-2022-10-15">Version 1.4.1 (2022-10-15)<a class="headerlink" href="#version-141-2022-10-15" title="Permanent link"></a></h2>
<ul>
<li>
<p>Support theme-namespaced plugin loading (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2998" title="GitHub Issue mkdocs/mkdocs #2998">#2998</a>)</p>
<p>Plugins' entry points can be named as 'sometheme/someplugin'. That will have the following outcome:</p>
<ul>
<li>If the current theme is 'sometheme', the plugin 'sometheme/someplugin' will always be preferred over 'someplugin'.</li>
<li>If the current theme <em>isn't</em> 'sometheme', the only way to use this plugin is by specifying <code>plugins: [sometheme/someplugin]</code>.</li>
</ul>
<p>One can also specify <code>plugins: ['/someplugin']</code> instead of <code>plugins: ['someplugin']</code> to definitely avoid the theme-namespaced plugin.</p>
</li>
<li>
<p>Bugfix: <code>mkdocs serve</code> will work correctly with non-ASCII paths and redirects (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/3001" title="GitHub Issue mkdocs/mkdocs #3001">#3001</a>)</p>
</li>
<li>
<p>Windows: 'colorama' is now a dependency of MkDocs, to ensure colorful log output (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2987" title="GitHub Issue mkdocs/mkdocs #2987">#2987</a>)</p>
</li>
<li>
<p>Plugin-related config options have more reliable validation and error reporting (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2997" title="GitHub Issue mkdocs/mkdocs #2997">#2997</a>)</p>
</li>
<li>
<p>Translation sub-commands of <code>setup.py</code> were completely dropped. See documentation <a href="../contributing/#submitting-changes-to-the-builtin-themes">[1]</a> <a href="../../dev-guide/translations/#updating-the-translation-catalogs">[2]</a> for their new replacements (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2990" title="GitHub Issue mkdocs/mkdocs #2990">#2990</a>)</p>
</li>
<li>
<p>The <a href="https://pypi.org/project/mkdocs/#files">'mkdocs' package</a> (wheel and source) is now produced by Hatch build system and pyproject.toml instead of setup.py (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2988" title="GitHub Issue mkdocs/mkdocs #2988">#2988</a>)</p>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.4.0...1.4.1">commit log</a>.</p>
<h2 id="version-140-2022-09-27">Version 1.4.0 (2022-09-27)<a class="headerlink" href="#version-140-2022-09-27" title="Permanent link"></a></h2>
<h3 id="feature-upgrades">Feature upgrades<a class="headerlink" href="#feature-upgrades" title="Permanent link"></a></h3>
<h4 id="hooks-2978">Hooks (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2978" title="GitHub Issue mkdocs/mkdocs #2978">#2978</a>)<a class="headerlink" href="#hooks-2978" title="Permanent link"></a></h4>
<p>The new <code>hooks:</code> config allows you to add plugin-like event handlers from local Python files, without needing to set up and install an actual plugin.</p>
<p>See <a href="../../user-guide/configuration/#hooks"><strong>documentation</strong></a>.</p>
<h4 id="edit_uri-flexibility-2927"><code>edit_uri</code> flexibility (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2927" title="GitHub Issue mkdocs/mkdocs #2927">#2927</a>)<a class="headerlink" href="#edit_uri-flexibility-2927" title="Permanent link"></a></h4>
<p>There is a new <code>edit_uri_template:</code> config.<br />
It works like <code>edit_uri</code> but more generally covers ways to construct an edit URL.<br />
See <a href="../../user-guide/configuration/#edit_uri_template"><strong>documentation</strong></a>.</p>
<p>Additionally, the <code>edit_uri</code> functionality will now fully work even if <code>repo_url</code> is omitted (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2928" title="GitHub Issue mkdocs/mkdocs #2928">#2928</a>)</p>
<h3 id="upgrades-for-plugin-developers_2">Upgrades for plugin developers<a class="headerlink" href="#upgrades-for-plugin-developers_2" title="Permanent link"></a></h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This release has big changes to the implementation of plugins and their configs. But, the intention is to have zero breaking changes in all reasonably common use cases. Or at the very least if a code fix is required, there should always be a way to stay compatible with older MkDocs versions. Please report if this release breaks something.</p>
</div>
<h4 id="customize-event-order-for-plugin-event-handlers-2973">Customize event order for plugin event handlers (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2973" title="GitHub Issue mkdocs/mkdocs #2973">#2973</a>)<a class="headerlink" href="#customize-event-order-for-plugin-event-handlers-2973" title="Permanent link"></a></h4>
<p>Plugins can now choose to set a priority value for their event handlers. This can override the old behavior where for each event type, the handlers are called in the order that their plugins appear in the <a href="../../user-guide/configuration/#plugins"><code>plugins</code> config</a>.</p>
<p>If this is set, events with higher priority are called first. Events without a chosen priority get a default of 0. Events that have the same priority are ordered as they appear in the config.</p>
<p>Recommended priority values: <code>100</code> "first", <code>50</code> "early", <code>0</code> "default", <code>-50</code> "late", <code>-100</code> "last".<br />
As different plugins discover more precise relations to each other, the values should be further tweaked.</p>
<p>See <a href="../../dev-guide/plugins/#event-priorities"><strong>documentation</strong></a>.</p>
<h4 id="new-events-that-persist-across-builds-in-mkdocs-serve-2972">New events that persist across builds in <code>mkdocs serve</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2972" title="GitHub Issue mkdocs/mkdocs #2972">#2972</a>)<a class="headerlink" href="#new-events-that-persist-across-builds-in-mkdocs-serve-2972" title="Permanent link"></a></h4>
<p>The new events are <code>on_startup</code> and <code>on_shutdown</code>. They run at the very beginning and very end of an <code>mkdocs</code> invocation.<br />
<code>on_startup</code> also receives information on how <code>mkdocs</code> was invoked (e.g. <code>serve</code> <code>--dirtyreload</code>).</p>
<p>See <a href="../../dev-guide/plugins/#events"><strong>documentation</strong></a>.</p>
<h4 id="replace-filesrc_path-to-not-deal-with-backslashes-2930">Replace <code>File.src_path</code> to not deal with backslashes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2930" title="GitHub Issue mkdocs/mkdocs #2930">#2930</a>)<a class="headerlink" href="#replace-filesrc_path-to-not-deal-with-backslashes-2930" title="Permanent link"></a></h4>
<p>The property <code>src_path</code> uses backslashes on Windows, which doesn't make sense as it's a virtual path.<br />
To not make a breaking change, there's no change to how <em>this</em> property is used, but now you should:</p>
<ul>
<li>Use <strong><code>File.src_uri</code></strong> instead of <code>File.src_path</code></li>
<li>and <strong><code>File.dest_uri</code></strong> instead of <code>File.dest_path</code>.</li>
</ul>
<p>These consistently use forward slashes, and are now the definitive source that MkDocs itself uses.</p>
<p>See <a href="https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/structure/files.py#L151">source code</a>.</p>
<p>As a related tip: you should also stop using <code>os.path.*</code> or <code>pathlib.Path()</code> to deal with these paths, and instead use <code>posixpath.*</code> or <code>pathlib.PurePosixPath()</code></p>
<h4 id="mkdocs-is-type-annotated-ready-for-use-with-mypy-2941-2970">MkDocs is type-annotated, ready for use with <a href="https://mypy.readthedocs.io/">mypy</a> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2941" title="GitHub Issue mkdocs/mkdocs #2941">#2941</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2970" title="GitHub Issue mkdocs/mkdocs #2970">#2970</a>)<a class="headerlink" href="#mkdocs-is-type-annotated-ready-for-use-with-mypy-2941-2970" title="Permanent link"></a></h4>
<h5 id="type-annotations-for-event-handler-methods-2931">Type annotations for event handler methods (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2931" title="GitHub Issue mkdocs/mkdocs #2931">#2931</a>)<a class="headerlink" href="#type-annotations-for-event-handler-methods-2931" title="Permanent link"></a></h5>
<p>MkDocs' plugin event methods now have type annotations. You might have been adding annotations to events already, but now they will be validated to match the original.</p>
<p>See <a href="https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/plugins.py#L165">source code</a> and <a href="../../dev-guide/plugins/#events">documentation</a>.</p>
<p>One big update is that now you should annotate method parameters more specifically as <code>config: defaults.MkDocsConfig</code> instead of <code>config: base.Config</code>. This not only makes it clear that it is the <a href="https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/config/defaults.py">main config of MkDocs itself</a>, but also provides type-safe access through attributes of the object (see next section).</p>
<p>See <a href="https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/config/defaults.py">source code</a> and <a href="../../dev-guide/plugins/#on_event_name">documentation</a>.</p>
<h4 id="rework-configoption-schemas-as-class-based-2962">Rework ConfigOption schemas as class-based (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2962" title="GitHub Issue mkdocs/mkdocs #2962">#2962</a>)<a class="headerlink" href="#rework-configoption-schemas-as-class-based-2962" title="Permanent link"></a></h4>
<p>When developing a plugin, the settings that it accepts used to be specified in the <code>config_scheme</code> variable on the plugin class.<br />
This approach is now soft-deprecated, and instead you should specify the config in a sub-class of <code>base.Config</code>.</p>
<p>Old example:</p>
<pre class="highlight"><code class="language-python">from mkdocs import plugins
from mkdocs.config import base, config_options
class MyPlugin(plugins.BasePlugin):
config_scheme = (
('foo', config_options.Type(int)),
('bar', config_options.Type(str, default='')),
)
def on_page_markdown(self, markdown: str, *, config: base.Config, **kwargs):
if self.config['foo'] &lt; 5:
if config['site_url'].startswith('http:'):
return markdown + self.config['baz']</code></pre>
<p>This code snippet actually has many mistakes but it will pass all type checks and silently run and even succeed in some cases.</p>
<p>So, on to the new equivalent example, changed to new-style schema and attribute-based access:<br />
(Complaints from "mypy" added inline)</p>
<pre class="highlight"><code class="language-python">from mkdocs import plugins
from mkdocs.config import base, config_options as c
class MyPluginConfig(base.Config):
foo = c.Optional(c.Type(int))
bar = c.Type(str, default='')
class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
if self.config.foo &lt; 5: # Error, `foo` might be `None`, need to check first.
if config.site_url.startswith('http:'): # Error, MkDocs' `site_url` also might be `None`.
return markdown + self.config.baz # Error, no such attribute `baz`!</code></pre>
<p>This lets you notice the errors from a static type checker before running the code and fix them as such:</p>
<pre class="highlight"><code class="language-python">class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
if self.config.foo is not None and self.config.foo &lt; 5: # OK, `int &lt; int` is valid.
if (config.site_url or '').startswith('http:'): # OK, `str.startswith(str)` is valid.
return markdown + self.config.bar # OK, `str + str` is valid.</code></pre>
<p>See <a href="../../dev-guide/plugins/#config_scheme"><strong>documentation</strong></a>.</p>
<p>Also notice that we had to explicitly mark the config attribute <code>foo</code> as <code>Optional</code>.<br />
The new-style config has all attributes marked as required by default, and specifying <code>required=False</code> or <code>required=True</code> is not allowed!</p>
<h5 id="new-config_optionsoptional-2962">New: <code>config_options.Optional</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2962" title="GitHub Issue mkdocs/mkdocs #2962">#2962</a>)<a class="headerlink" href="#new-config_optionsoptional-2962" title="Permanent link"></a></h5>
<p>Wrapping something into <code>Optional</code> is conceptually similar to "I want the default to be <code>None</code>" -- and you <em>have</em> to express it like that, because writing <code>default=None</code> doesn't actually work.</p>
<p>Breaking change: the method <code>BaseConfigOption.is_required()</code> was removed. Use <code>.required</code> instead. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2938" title="GitHub Issue mkdocs/mkdocs #2938">#2938</a>)<br />
And even the <code>required</code> property should be mostly unused now.<br />
For class-based configs, there's a new definition for whether an option is "required":</p>
<ul>
<li>It has no default, and</li>
<li>It is not wrapped into <code>config_options.Optional</code>.</li>
</ul>
<h5 id="new-config_optionslistofitems-2938">New: <code>config_options.ListOfItems</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2938" title="GitHub Issue mkdocs/mkdocs #2938">#2938</a>)<a class="headerlink" href="#new-config_optionslistofitems-2938" title="Permanent link"></a></h5>
<p>Defines a list of items that each must adhere to the same constraint. Kind of like a validated <code>Type(list)</code></p>
<p>Examples how to express a list of integers (with <code>from mkdocs.config import config_options as c</code>):</p>
<table>
<thead>
<tr>
<th>Description</th>
<th>Code entry</th>
</tr>
</thead>
<tbody>
<tr>
<td>Required to specify</td>
<td><code>foo = c.ListOfItems(c.Type(int))</code></td>
</tr>
<tr>
<td>Optional, default is []</td>
<td><code>foo = c.ListOfItems(c.Type(int), default=[])</code></td>
</tr>
<tr>
<td>Optional, default is None</td>
<td><code>foo = c.Optional(c.ListOfItems(c.Type(int)))</code></td>
</tr>
</tbody>
</table>
<p>See more <a href="../../dev-guide/plugins/#examples-of-config-definitions">examples in <strong>documentation</strong></a>.</p>
<h5 id="updated-config_optionssubconfig-2807">Updated: <code>config_options.SubConfig</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2807" title="GitHub Issue mkdocs/mkdocs #2807">#2807</a>)<a class="headerlink" href="#updated-config_optionssubconfig-2807" title="Permanent link"></a></h5>
<p><code>SubConfig</code> used to silently ignore all validation of its config options. Now you should pass <code>validate=True</code> to it or just use new class-based configs where this became the default.</p>
<p>So, it can be used to validate a nested sub-dict with all keys pre-defined and value types strictly validated.</p>
<p>See <a href="../../dev-guide/plugins/#examples-of-config-definitions">examples in <strong>documentation</strong></a>.</p>
<h4 id="other-changes-to-config-options">Other changes to config options<a class="headerlink" href="#other-changes-to-config-options" title="Permanent link"></a></h4>
<p><code>URL</code>'s default is now <code>None</code> instead of <code>''</code>. This can still be checked for truthiness in the same way - <code>if config.some_url:</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2962" title="GitHub Issue mkdocs/mkdocs #2962">#2962</a>)</p>
<p><code>FilesystemObject</code> is no longer abstract and can be used directly, standing for "file or directory" with optional existence checking (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2938" title="GitHub Issue mkdocs/mkdocs #2938">#2938</a>)</p>
<p>Bug fixes:</p>
<ul>
<li>Fix <code>SubConfig</code>, <code>ConfigItems</code>, <code>MarkdownExtensions</code> to not leak values across different instances (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2916" title="GitHub Issue mkdocs/mkdocs #2916">#2916</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2290" title="GitHub Issue mkdocs/mkdocs #2290">#2290</a>)</li>
<li><code>SubConfig</code> raises the correct kind of validation error without a stack trace (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2938" title="GitHub Issue mkdocs/mkdocs #2938">#2938</a>)</li>
<li>Fix dot-separated redirect in <code>config_options.Deprecated(moved_to)</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2963" title="GitHub Issue mkdocs/mkdocs #2963">#2963</a>)</li>
</ul>
<p>Tweaked logic for handling <code>ConfigOption.default</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2938" title="GitHub Issue mkdocs/mkdocs #2938">#2938</a>)</p>
<p>Deprecated config option classes: <code>ConfigItems</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2983" title="GitHub Issue mkdocs/mkdocs #2983">#2983</a>), <code>OptionallyRequired</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2962" title="GitHub Issue mkdocs/mkdocs #2962">#2962</a>), <code>RepoURL</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2927" title="GitHub Issue mkdocs/mkdocs #2927">#2927</a>)</p>
<h3 id="theme-updates_1">Theme updates<a class="headerlink" href="#theme-updates_1" title="Permanent link"></a></h3>
<ul>
<li>
<p>Styles of admonitions in "MkDocs" theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2981" title="GitHub Issue mkdocs/mkdocs #2981">#2981</a>):</p>
<ul>
<li>Update colors to increase contrast</li>
<li>Apply admonition styles also to <code>&lt;details&gt;</code> tag, to support Markdown extensions that provide it (<a href="https://facelessuser.github.io/pymdown-extensions/extensions/details/">pymdownx.details</a>, <a href="https://oprypin.github.io/markdown-callouts/#collapsible-blocks">callouts</a>)</li>
</ul>
</li>
<li>
<p>Built-in themes now also support these languages:</p>
<ul>
<li>Russian (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2976" title="GitHub Issue mkdocs/mkdocs #2976">#2976</a>)</li>
<li>Turkish (Turkey) (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2946" title="GitHub Issue mkdocs/mkdocs #2946">#2946</a>)</li>
<li>Ukrainian (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2980" title="GitHub Issue mkdocs/mkdocs #2980">#2980</a>)</li>
</ul>
</li>
</ul>
<h3 id="future-compatibility">Future compatibility<a class="headerlink" href="#future-compatibility" title="Permanent link"></a></h3>
<ul>
<li>
<p><code>extra_css:</code> and <code>extra_javascript:</code> warn if a backslash <code>\</code> is passed to them. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2930" title="GitHub Issue mkdocs/mkdocs #2930">#2930</a>, <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2984" title="GitHub Issue mkdocs/mkdocs #2984">#2984</a>)</p>
</li>
<li>
<p>Show <code>DeprecationWarning</code>s as INFO messages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2907" title="GitHub Issue mkdocs/mkdocs #2907">#2907</a>)</p>
<p>If any plugin or extension that you use relies on deprecated functionality of other libraries, it is at risk of breaking in the near future. Plugin developers should address these in a timely manner.</p>
</li>
<li>
<p>Avoid a dependency on <code>importlib_metadata</code> starting from Python 3.10 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2959" title="GitHub Issue mkdocs/mkdocs #2959">#2959</a>)</p>
</li>
<li>
<p>Drop support for Python 3.6 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2948" title="GitHub Issue mkdocs/mkdocs #2948">#2948</a>)</p>
</li>
</ul>
<h4 id="incompatible-changes-to-public-apis">Incompatible changes to public APIs<a class="headerlink" href="#incompatible-changes-to-public-apis" title="Permanent link"></a></h4>
<ul>
<li><code>mkdocs.utils</code>:<ul>
<li><code>create_media_urls</code> and <code>normalize_url</code> warn if a backslash <code>\</code> is passed to them. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2930" title="GitHub Issue mkdocs/mkdocs #2930">#2930</a>)</li>
<li><code>is_markdown_file</code> stops accepting case-insensitive variants such as <code>.MD</code>, which is how MkDocs build was already operating. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2912" title="GitHub Issue mkdocs/mkdocs #2912">#2912</a>)</li>
<li>Hard-deprecated: <code>modified_time</code>, <code>reduce_list</code>, <code>get_html_path</code>, <code>get_url_path</code>, <code>is_html_file</code>, <code>is_template_file</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2912" title="GitHub Issue mkdocs/mkdocs #2912">#2912</a>)</li>
</ul>
</li>
</ul>
<h3 id="miscellaneous">Miscellaneous<a class="headerlink" href="#miscellaneous" title="Permanent link"></a></h3>
<ul>
<li>
<p>If a plugin adds paths to <code>watch</code> in <code>LiveReloadServer</code>, it can now <code>unwatch</code> them. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2777" title="GitHub Issue mkdocs/mkdocs #2777">#2777</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.2): Support listening on an IPv6 address in <code>mkdocs serve</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2951" title="GitHub Issue mkdocs/mkdocs #2951">#2951</a>)</p>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.3.1...1.4.0">commit log</a>.</p>
<h2 id="version-131-2022-07-19">Version 1.3.1 (2022-07-19)<a class="headerlink" href="#version-131-2022-07-19" title="Permanent link"></a></h2>
<ul>
<li>
<p>Pin Python-Markdown version to &lt;3.4, thus excluding its latest release that breaks too many external extensions (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2893" title="GitHub Issue mkdocs/mkdocs #2893">#2893</a>)</p>
</li>
<li>
<p>When a Markdown extension fails to load, print its name and traceback (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2894" title="GitHub Issue mkdocs/mkdocs #2894">#2894</a>)</p>
</li>
<li>
<p>Bugfix for "readthedocs" theme (regression in 1.3.0): add missing space in breadcrumbs (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2810" title="GitHub Issue mkdocs/mkdocs #2810">#2810</a>)</p>
</li>
<li>
<p>Bugfix: don't complain when a file "readme.md" (lowercase) exists, it's not recognized otherwise (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2852" title="GitHub Issue mkdocs/mkdocs #2852">#2852</a>)</p>
</li>
<li>
<p>Built-in themes now also support these languages:</p>
<ul>
<li>Italian (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2860" title="GitHub Issue mkdocs/mkdocs #2860">#2860</a>)</li>
</ul>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.3.0...1.3.1">commit log</a>.</p>
<h2 id="version-130-2022-03-26">Version 1.3.0 (2022-03-26)<a class="headerlink" href="#version-130-2022-03-26" title="Permanent link"></a></h2>
<h3 id="feature-upgrades_1">Feature upgrades<a class="headerlink" href="#feature-upgrades_1" title="Permanent link"></a></h3>
<ul>
<li>
<p>ReadTheDocs theme updated from v0.4.1 to v1.0.0 according to upstream (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2585" title="GitHub Issue mkdocs/mkdocs #2585">#2585</a>)</p>
<p>The most notable changes:</p>
<ul>
<li>New option <code>logo</code>: Rather than displaying the <code>site_name</code> in the title, one can specify a path to an image to display instead.</li>
<li>New option <code>anonymize_ip</code> for Google Analytics.</li>
<li>Dependencies were upgraded: jQuery upgraded to 3.6.0, Modernizr.js dropped, and others.</li>
</ul>
<p>See <a href="https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs">documentation of config options for the theme</a></p>
</li>
<li>
<p>Built-in themes now also support these languages:</p>
<ul>
<li>German (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2633" title="GitHub Issue mkdocs/mkdocs #2633">#2633</a>)</li>
<li>Persian (Farsi) (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2787" title="GitHub Issue mkdocs/mkdocs #2787">#2787</a>)</li>
</ul>
</li>
<li>
<p>Support custom directories to watch when running <code>mkdocs serve</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2642" title="GitHub Issue mkdocs/mkdocs #2642">#2642</a>)</p>
<p>MkDocs by default watches the <em>docs</em> directory and the config file. Now there is a way to add more directories to watch for changes, either via the YAML <code>watch</code> key or the command line flag <code>--watch</code>.</p>
<p>Normally MkDocs never reaches into any other directories (so this feature shouldn't be necessary), but some plugins and extensions may do so.</p>
<p>See <a href="https://www.mkdocs.org/user-guide/configuration/#watch">documentation</a>.</p>
</li>
<li>
<p>New <code>--no-history</code> option for <code>gh_deploy</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2594" title="GitHub Issue mkdocs/mkdocs #2594">#2594</a>)</p>
<p>Allows to discard the history of commits when deploying, and instead replace it with one root commit</p>
</li>
</ul>
<h3 id="bug-fixes_1">Bug fixes<a class="headerlink" href="#bug-fixes_1" title="Permanent link"></a></h3>
<ul>
<li>
<p>An XSS vulnerability when using the search function in built-in themes was fixed (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2791" title="GitHub Issue mkdocs/mkdocs #2791">#2791</a>)</p>
</li>
<li>
<p>Setting the <code>edit_uri</code> option no longer erroneously adds a trailing slash to <code>repo_url</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2733" title="GitHub Issue mkdocs/mkdocs #2733">#2733</a>)</p>
</li>
</ul>
<h3 id="miscellaneous_1">Miscellaneous<a class="headerlink" href="#miscellaneous_1" title="Permanent link"></a></h3>
<ul>
<li>
<p>Breaking change: the <code>pages</code> config option that was deprecated for a very long time now causes an error when used (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2652" title="GitHub Issue mkdocs/mkdocs #2652">#2652</a>)</p>
<p>To fix the error, just change from <code>pages</code> to <code>nav</code>.</p>
</li>
<li>
<p>Performance optimization: during startup of MkDocs, code and dependencies of other commands will not be imported (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2714" title="GitHub Issue mkdocs/mkdocs #2714">#2714</a>)</p>
<p>The most visible effect of this is that dependencies of <code>mkdocs serve</code> will not be imported when <code>mkdocs build</code> is used.</p>
</li>
<li>
<p>Recursively validate <code>nav</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2680" title="GitHub Issue mkdocs/mkdocs #2680">#2680</a>)</p>
<p>Validation of the nested <code>nav</code> structure has been reworked to report errors early and reliably. Some <a href="https://github.com/mkdocs/mkdocs/blob/b7272150bbc9bf8f66c878f6517742de3528972b/mkdocs/tests/config/config_options_tests.py#L783">edge cases</a> have been declared invalid.</p>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.2.3...1.3.0">commit log</a>.</p>
<h2 id="version-124-2022-03-26">Version 1.2.4 (2022-03-26)<a class="headerlink" href="#version-124-2022-03-26" title="Permanent link"></a></h2>
<ul>
<li>
<p>Compatibility with Jinja2 3.1.0 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2800" title="GitHub Issue mkdocs/mkdocs #2800">#2800</a>)</p>
<p>Due to a breaking change in Jinja2, MkDocs would crash with the message
<code>AttributeError: module 'jinja2' has no attribute 'contextfilter'</code></p>
</li>
</ul>
<h2 id="version-123-2021-10-12">Version 1.2.3 (2021-10-12)<a class="headerlink" href="#version-123-2021-10-12" title="Permanent link"></a></h2>
<ul>
<li>
<p>Built-in themes now also support these languages:</p>
<ul>
<li>Simplified Chinese (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2497" title="GitHub Issue mkdocs/mkdocs #2497">#2497</a>)</li>
<li>Japanese (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2525" title="GitHub Issue mkdocs/mkdocs #2525">#2525</a>)</li>
<li>Brazilian Portuguese (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2535" title="GitHub Issue mkdocs/mkdocs #2535">#2535</a>)</li>
<li>Spanish (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2545" title="GitHub Issue mkdocs/mkdocs #2545">#2545</a>, previously <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2396" title="GitHub Issue mkdocs/mkdocs #2396">#2396</a>)</li>
</ul>
</li>
<li>
<p>Third-party plugins will take precedence over built-in plugins with the same name (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2591" title="GitHub Issue mkdocs/mkdocs #2591">#2591</a>)</p>
</li>
<li>
<p>Bugfix: Fix ability to load translations for some languages: core support (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2565" title="GitHub Issue mkdocs/mkdocs #2565">#2565</a>) and search plugin support with fallbacks (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2602" title="GitHub Issue mkdocs/mkdocs #2602">#2602</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.2): Prevent directory traversal in the dev server (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2604" title="GitHub Issue mkdocs/mkdocs #2604">#2604</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.2): Prevent webserver warnings from being treated as a build failure in strict mode (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2607" title="GitHub Issue mkdocs/mkdocs #2607">#2607</a>)</p>
</li>
<li>
<p>Bugfix: Correctly print colorful messages in the terminal on Windows (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2606" title="GitHub Issue mkdocs/mkdocs #2606">#2606</a>)</p>
</li>
<li>
<p>Bugfix: Python version 3.10 was displayed incorrectly in <code>--version</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2618" title="GitHub Issue mkdocs/mkdocs #2618">#2618</a>)</p>
</li>
</ul>
<p>Other small improvements; see <a href="https://github.com/mkdocs/mkdocs/compare/1.2.2...1.2.3">commit log</a>.</p>
<h2 id="version-122-2021-07-18">Version 1.2.2 (2021-07-18)<a class="headerlink" href="#version-122-2021-07-18" title="Permanent link"></a></h2>
<ul>
<li>
<p>Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2464" title="GitHub Issue mkdocs/mkdocs #2464">#2464</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.2): Revert livereload file watching to use polling observer (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2477" title="GitHub Issue mkdocs/mkdocs #2477">#2477</a>)</p>
<p>This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts.</p>
<p>This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage.</p>
</li>
<li>
<p>Revert from 1.2: Remove the requirement of a <code>site_url</code> config and the restriction on <code>use_directory_urls</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2490" title="GitHub Issue mkdocs/mkdocs #2490">#2490</a>)</p>
</li>
<li>
<p>Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in <code>mkdocs serve</code> server (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2507" title="GitHub Issue mkdocs/mkdocs #2507">#2507</a>)</p>
<p>Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before.</p>
</li>
<li>
<p>Bugfix: Fix <code>gh_deploy</code> with config-file in the current directory (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2481" title="GitHub Issue mkdocs/mkdocs #2481">#2481</a>)</p>
</li>
<li>
<p>Bugfix: Fix reversed breadcrumbs in "readthedocs" theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2179" title="GitHub Issue mkdocs/mkdocs #2179">#2179</a>)</p>
</li>
<li>
<p>Allow "mkdocs.yaml" as the file name when '--config' is not passed (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2478" title="GitHub Issue mkdocs/mkdocs #2478">#2478</a>)</p>
</li>
<li>
<p>Stop treating ";" as a special character in URLs: urlparse -&gt; urlsplit (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2502" title="GitHub Issue mkdocs/mkdocs #2502">#2502</a>)</p>
</li>
<li>
<p>Improve build performance for sites with many pages (partly already done in 1.2) (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2407" title="GitHub Issue mkdocs/mkdocs #2407">#2407</a>)</p>
</li>
</ul>
<h2 id="version-121-2021-06-09">Version 1.2.1 (2021-06-09)<a class="headerlink" href="#version-121-2021-06-09" title="Permanent link"></a></h2>
<ul>
<li>Bugfix (regression in 1.2): Ensure 'gh-deploy' always pushes.</li>
</ul>
<h2 id="version-12-2021-06-04">Version 1.2 (2021-06-04)<a class="headerlink" href="#version-12-2021-06-04" title="Permanent link"></a></h2>
<h3 id="major-additions-to-version-12">Major Additions to Version 1.2<a class="headerlink" href="#major-additions-to-version-12" title="Permanent link"></a></h3>
<h4 id="support-added-for-theme-localization-2299">Support added for Theme Localization (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2299" title="GitHub Issue mkdocs/mkdocs #2299">#2299</a>)<a class="headerlink" href="#support-added-for-theme-localization-2299" title="Permanent link"></a></h4>
<p>The <code>mkdocs</code> and <code>readthedocs</code> themes now support language localization using
the <code>theme.locale</code> parameter, which defaults to <code>en</code> (English). The only other
supported languages in this release are <code>fr</code> (French) and <code>es</code> (Spanish). For
details on using the provided translations, see the <a href="../../user-guide/localizing-your-theme/">user
guide</a>. Note that translation will not
happen by default. Users must first install the necessary dependencies with
the following command:</p>
<pre class="highlight"><code class="language-bash">pip install 'mkdocs[i18n]'</code></pre>
<p>Translation contributions are welcome and detailed in the <a href="../../dev-guide/translations/">Translation
Guide</a>.</p>
<p>Developers of third party themes may want to review the relevant section of
the <a href="../../dev-guide/themes/#supporting-theme-localizationtranslation">Theme Development
Guide</a>.</p>
<p>Contributors who are updating the templates to the built-in themes should
review the <a href="../contributing/#submitting-changes-to-the-builtin-themes">Contributing
Guide</a>.</p>
<p>The <code>lang</code> setting of the <code>search</code> plugin now defaults to the language
specified in <code>theme.locale</code>.</p>
<h4 id="support-added-for-environment-variables-in-the-configuration-file-1954">Support added for Environment Variables in the configuration file (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1954" title="GitHub Issue mkdocs/mkdocs #1954">#1954</a>)<a class="headerlink" href="#support-added-for-environment-variables-in-the-configuration-file-1954" title="Permanent link"></a></h4>
<p>Environments variables may now be specified in the configuration file with the
<code>!ENV</code> tag. The value of the variable will be parsed by the YAML parser and
converted to the appropriate type.</p>
<pre class="highlight"><code class="language-yaml">somekey: !ENV VAR_NAME
otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value']</code></pre>
<p>See <a href="../../user-guide/configuration/#environment-variables">Environment Variables</a>
in the Configuration documentation for details.</p>
<h4 id="support-added-for-configuration-inheritance-2218">Support added for Configuration Inheritance (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2218" title="GitHub Issue mkdocs/mkdocs #2218">#2218</a>)<a class="headerlink" href="#support-added-for-configuration-inheritance-2218" title="Permanent link"></a></h4>
<p>A configuration file may now inherit from a parent configuration file. In the
primary file set the <code>INHERIT</code> key to the relative path of the parent file.</p>
<pre class="highlight"><code class="language-yaml">INHERIT: path/to/base.yml</code></pre>
<p>The two files will then be deep merged. See
<a href="../../user-guide/configuration/#configuration-inheritance">Configuration Inheritance</a>
for details.</p>
<h4 id="update-gh-deploy-command-2170">Update <code>gh-deploy</code> command (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2170" title="GitHub Issue mkdocs/mkdocs #2170">#2170</a>)<a class="headerlink" href="#update-gh-deploy-command-2170" title="Permanent link"></a></h4>
<p>The vendored (and modified) copy of ghp_import has been replaced with a
dependency on the upstream library. As of version 1.0.0, <a href="https://github.com/c-w/ghp-import/">ghp-import</a> includes a
Python API which makes it possible to call directly.</p>
<p>MkDocs can now benefit from recent bug fixes and new features, including the following:</p>
<ul>
<li>A <code>.nojekyll</code> file is automatically included when deploying to GitHub Pages.</li>
<li>The <code>--shell</code> flag is now available, which reportedly works better on Windows.</li>
<li>Git author and committer environment variables should be respected (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1383" title="GitHub Issue mkdocs/mkdocs #1383">#1383</a>).</li>
</ul>
<h4 id="rework-auto-reload-and-http-server-for-mkdocs-serve-2385">Rework auto-reload and HTTP server for <code>mkdocs serve</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2385" title="GitHub Issue mkdocs/mkdocs #2385">#2385</a>)<a class="headerlink" href="#rework-auto-reload-and-http-server-for-mkdocs-serve-2385" title="Permanent link"></a></h4>
<p><code>mkdocs serve</code> now uses a new underlying server + file watcher implementation,
based on <a href="https://docs.python.org/3/library/http.server.html">http.server</a> from standard library and <a href="https://pypi.org/project/watchdog/">watchdog</a>. It provides similar
functionality to the previously used <a href="https://pypi.org/project/livereload/">livereload</a> library (which is now dropped
from dependencies, along with <a href="https://pypi.org/project/tornado/">tornado</a>).</p>
<p>This makes reloads more responsive and consistent in terms of timing. Multiple
rapid file changes no longer cause the site to repeatedly rebuild (issue <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2061" title="GitHub Issue mkdocs/mkdocs #2061">#2061</a>).</p>
<p>Almost every aspect of the server is slightly different, but actual visible
changes are minor. The logging outputs are only <em>similar</em> to the old ones.
Degradations in behavior are not expected, and should be reported if found.</p>
<h5 id="offset-the-local-site-root-according-to-the-sub-path-of-the-site_url-2424">Offset the local site root according to the sub-path of the <code>site_url</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2424" title="GitHub Issue mkdocs/mkdocs #2424">#2424</a>)<a class="headerlink" href="#offset-the-local-site-root-according-to-the-sub-path-of-the-site_url-2424" title="Permanent link"></a></h5>
<p>When using <code>mkdocs serve</code> and having the <code>site_url</code> specified as e.g.
<code>http://example.org/sub/path/</code>, now the root of the locally served site
becomes <code>http://127.0.0.1:8000/sub/path/</code> and all document paths are offset
accordingly.</p>
<h4 id="a-build_error-event-was-added-2103">A <code>build_error</code> event was added (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2103" title="GitHub Issue mkdocs/mkdocs #2103">#2103</a>)<a class="headerlink" href="#a-build_error-event-was-added-2103" title="Permanent link"></a></h4>
<p>Plugin developers can now use the <code>on_build_error</code> hook
to execute code when an exception is raised while building the site.</p>
<p>See <a href="../../dev-guide/plugins/#on_build_error"><code>on_build_error</code></a>
in the Plugins documentation for details.</p>
<h4 id="three-new-exceptions-builderror-pluginerror-and-abort-2103">Three new exceptions: BuildError PluginError and Abort (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2103" title="GitHub Issue mkdocs/mkdocs #2103">#2103</a>)<a class="headerlink" href="#three-new-exceptions-builderror-pluginerror-and-abort-2103" title="Permanent link"></a></h4>
<p>MkDocs now has tree new exceptions defined in <code>mkdocs.exceptions</code>:
<code>BuildError</code>, <code>PluginError</code>, and <code>Abort</code>:</p>
<ul>
<li><code>PluginError</code> can be raised from a plugin to stop the build and log an error message <em>without traceback</em>.</li>
<li><code>BuildError</code> should not be used by third-party plugins developers and is reserved for internal use only.</li>
<li><code>Abort</code> is used internally to abort the build and display an error without a traceback.</li>
</ul>
<p>See <a href="../../dev-guide/plugins/#handling-errors"><code>Handling errors</code></a>
in the Plugins documentation for details.</p>
<h4 id="search-indexing-strategy-configuration">Search Indexing Strategy configuration<a class="headerlink" href="#search-indexing-strategy-configuration" title="Permanent link"></a></h4>
<p>Users can now specify which strategy they wish to use when indexing
their site for search. A user can select between the following options:</p>
<ul>
<li><strong>full</strong>: Adds page title, section headings, and full page text to the search index.</li>
<li><strong>sections</strong>: Adds page titles and section headings only to the search index.</li>
<li><strong>titles</strong>: Adds only the page titles to the search index.</li>
</ul>
<p>See <a href="../../user-guide/configuration/#indexing"><code>Search Indexing</code></a> in the
configuration documentation for details.</p>
<h3 id="backward-incompatible-changes-in-12">Backward Incompatible Changes in 1.2<a class="headerlink" href="#backward-incompatible-changes-in-12" title="Permanent link"></a></h3>
<ul>
<li>
<p>The <a href="../../user-guide/configuration/#site_url">site_url</a> configuration option
is now <strong>required</strong>. If it is not set, a warning will be issued. In a future
release an error will be raised (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2189" title="GitHub Issue mkdocs/mkdocs #2189">#2189</a>).</p>
<p>The <a href="../../user-guide/configuration/#use_directory_urls">use_directory_urls</a>
configuration option will be forced to <code>false</code> if
<a href="../../user-guide/configuration/#site_url">site_url</a> is set to an empty
string. In that case, if <code>use_directory_urls</code> is not explicitly set to
<code>false</code>, a warning will be issued (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2189" title="GitHub Issue mkdocs/mkdocs #2189">#2189</a>).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This was reverted in release 1.2.2</p>
</div>
</li>
<li>
<p>The <code>google_analytics</code> configuration option is deprecated as Google appears to
be phasing it out in favor of its new Google Analytics 4 property. See the
documentation for your theme for alternatives which can be configured as part
of your theme configuration. For example, the <a href="../../user-guide/choosing-your-theme/#mkdocs">mkdocs</a> and
<a href="../../user-guide/choosing-your-theme/#readthedocs">readthedocs</a> themes have each added a new <code>theme.analytics.gtag</code>
configuration option which uses the new Google Analytics 4 property. See
Google's documentation on how to <a href="https://support.google.com/analytics/answer/9744165?hl=en">Upgrade to a Google Analytics 4
property</a>. Then set <code>theme.analytics.gtag</code> to the "G-" ID and delete the
<code>google_analytics</code> configuration option which contains a "UA-" ID. So long
as the old "UA-" ID and new "G-" ID are properly linked in your Google
account, and you are using the "G-" ID, the data will be made available in
both the old and new formats by Google Analytics. See <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2252" title="GitHub Issue mkdocs/mkdocs #2252">#2252</a>.</p>
</li>
<li>
<p>A theme's files are now excluded from the list of watched files by default
when using the <code>--livereload</code> server. This new default behavior is what most
users need and provides better performance when editing site content.
Theme developers can enable the old behavior with the <code>--watch-theme</code>
option. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2092" title="GitHub Issue mkdocs/mkdocs #2092">#2092</a>).</p>
</li>
<li>
<p>The <code>mkdocs</code> theme now removes the sidebar when printing a page. This frees
up horizontal space for better rendering of content like tables (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2193" title="GitHub Issue mkdocs/mkdocs #2193">#2193</a>).</p>
</li>
<li>
<p>The <code>mkdocs.config.DEFAULT_SCHEMA</code> global variable has been replaced with the
function <code>mkdocs.config.defaults.get_schema()</code>, which ensures that each
instance of the configuration is unique (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2289" title="GitHub Issue mkdocs/mkdocs #2289">#2289</a>).</p>
</li>
<li>
<p>The <code>mkdocs.utils.warning_filter</code> is deprecated and now does nothing. Plugins
should remove any reference to is as it may be deleted in a future release.
To ensure any warnings get counted, simply log them to the <code>mkdocs</code> log (i.e.:
<code>mkdocs.plugins.pluginname</code>).</p>
</li>
<li>
<p>The <code>on_serve</code> event (which receives the <code>server</code> object and the <code>builder</code>
function) is affected by the server rewrite. <code>server</code> is now a
<code>mkdocs.livereload.LiveReloadServer</code> instead of <code>livereload.server.Server</code>.
The typical action that plugins can do with these is to call
<code>server.watch(some_dir, builder)</code>, which basically adds that directory to
watched directories, causing the site to be rebuilt on file changes. That
still works, but passing any other function to <code>watch</code> is deprecated and shows
a warning. This 2nd parameter is already optional, and will accept only this
exact <code>builder</code> function just for compatibility.</p>
</li>
<li>
<p>The <code>python</code> method of the <code>plugins.search.prebuild_index</code> configuration
option is pending deprecation as of version 1.2. It is expected that in
version 1.3 it will raise a warning if used and in version 1.4 it will raise
an error. Users are encouraged to use an alternate method to generate a
prebuilt index for search.</p>
</li>
<li>
<p>The <code>lunr</code> and <code>lunr[languages]</code> dependencies are no longer installed by
default. The dependencies are only needed for the rare user who pre-builds the
search index and uses the <code>python</code> option, which is now pending deprecation.
If you use this feature, then you will need to manually install <code>lunr</code> and
<code>lunr[languages]</code>. A warning is issued if the dependencies are needed but not
installed.</p>
</li>
</ul>
<h3 id="other-changes-and-additions-to-version-12">Other Changes and Additions to Version 1.2<a class="headerlink" href="#other-changes-and-additions-to-version-12" title="Permanent link"></a></h3>
<ul>
<li>Bugfix: Properly process navigation child items in <code>_get_by_type</code> when filtering for sections (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2203" title="GitHub Issue mkdocs/mkdocs #2203">#2203</a>).</li>
<li>Official support for Python 3.9 has been added and support for Python 3.5 has been dropped.</li>
<li>Bugfix: Fixes an issue that would result in a partially cut-off navigation item in the ReadTheDocs theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2297" title="GitHub Issue mkdocs/mkdocs #2297">#2297</a>).</li>
<li>Structure Files object now has a <code>remove</code> method to help plugin developers manipulate the Files tree. The corresponding <code>src_paths</code> has become a property to accommodate this possible dynamic behavior. See <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2305" title="GitHub Issue mkdocs/mkdocs #2305">#2305</a>.</li>
<li>Updated highlight.js to 10.5.0. See <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2313" title="GitHub Issue mkdocs/mkdocs #2313">#2313</a>.</li>
<li>Bugfix: Search plugin now works with Japanese language. See <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2178" title="GitHub Issue mkdocs/mkdocs #2178">#2178</a>.</li>
<li>Documentation has been refactored (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1629" title="GitHub Issue mkdocs/mkdocs #1629">#1629</a>).</li>
<li>Restore styling of tables in the <code>readthedocs</code> theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2028" title="GitHub Issue mkdocs/mkdocs #2028">#2028</a>).</li>
<li>Ensure <code>site_url</code> ends with a slash (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1785" title="GitHub Issue mkdocs/mkdocs #1785">#1785</a>).</li>
<li>Correct documentation of <code>pages</code> template context variable (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1736" title="GitHub Issue mkdocs/mkdocs #1736">#1736</a>).</li>
<li>The <code>lunr</code> dependency has been updated to 0.5.9, and <code>lunr.js</code> to the corresponding 2.3.9 version (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2306" title="GitHub Issue mkdocs/mkdocs #2306">#2306</a>).</li>
<li>Color is now used in log messages to identify errors, warnings and debug messages.</li>
<li>Bugfix: Identify homepage when <code>use_directory_urls</code> is <code>False</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2362" title="GitHub Issue mkdocs/mkdocs #2362">#2362</a>).</li>
</ul>
<h2 id="version-112-2020-05-14">Version 1.1.2 (2020-05-14)<a class="headerlink" href="#version-112-2020-05-14" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Normalize IP addresses and change unsupported address error to a warning (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2108" title="GitHub Issue mkdocs/mkdocs #2108">#2108</a>).</li>
</ul>
<h2 id="version-111-2020-05-12">Version 1.1.1 (2020-05-12)<a class="headerlink" href="#version-111-2020-05-12" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Allow compressed sitemap to be deterministic by supporting the <code>SOURCE_DATE_EPOCH</code> environment variable (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2100" title="GitHub Issue mkdocs/mkdocs #2100">#2100</a>).</li>
<li>Bugfix: Use <code>README.md</code> as <code>index.html</code> even if <code>use_directory_urls</code> is false (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2081" title="GitHub Issue mkdocs/mkdocs #2081">#2081</a>).</li>
<li>Bugfix: Ignore links which start with a backslash (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1680" title="GitHub Issue mkdocs/mkdocs #1680">#1680</a>).</li>
<li>Bugfix: Pass <code>builder</code> to the <code>on_serve</code> event so that it can be passed to <code>server.watch</code> by plugins (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1952" title="GitHub Issue mkdocs/mkdocs #1952">#1952</a>).</li>
<li>Bugfix: Use <code>lunr[languages]==0.5.8</code> to avoid <code>nltk</code> incompatibilities (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2062" title="GitHub Issue mkdocs/mkdocs #2062">#2062</a>).</li>
<li>Bugfix: Ensure wheel is Python 3 only (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2021" title="GitHub Issue mkdocs/mkdocs #2021">#2021</a>).</li>
<li>Bugfix: Clean up <code>dev_addr</code> validation and disallow <code>0.0.0.0</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2022" title="GitHub Issue mkdocs/mkdocs #2022">#2022</a>).</li>
<li>Add support for <code>min_search_length</code> parameter for search plugin (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2014" title="GitHub Issue mkdocs/mkdocs #2014">#2014</a>).</li>
<li>Bugfix: <code>readthedocs</code> theme <code>code</code> colors (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/2027" title="GitHub Issue mkdocs/mkdocs #2027">#2027</a>).</li>
</ul>
<h2 id="version-11-2020-02-22">Version 1.1 (2020-02-22)<a class="headerlink" href="#version-11-2020-02-22" title="Permanent link"></a></h2>
<h3 id="major-additions-to-version-11">Major Additions to Version 1.1<a class="headerlink" href="#major-additions-to-version-11" title="Permanent link"></a></h3>
<h4 id="support-for-lunrpy-as-prebuild_index-engine">Support for Lunr.py as <code>prebuild_index</code> engine<a class="headerlink" href="#support-for-lunrpy-as-prebuild_index-engine" title="Permanent link"></a></h4>
<p>Mkdocs now supports pre-building indices using <a href="http://lunr.readthedocs.io/">Lunr.py</a>, a pure
Python implementation of Lunr.js, allowing the user to avoid installing a
NodeJS environment if so desired. For more information please read the
<a href="../../user-guide/configuration/#prebuild_index"><code>prebuild_index</code> documentation</a>.</p>
<h4 id="readthedocs-theme-updated-with-upstream-588-and-1374"><code>readthedocs</code> theme updated with upstream (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/588" title="GitHub Issue mkdocs/mkdocs #588">#588</a> and <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1374" title="GitHub Issue mkdocs/mkdocs #1374">#1374</a>)<a class="headerlink" href="#readthedocs-theme-updated-with-upstream-588-and-1374" title="Permanent link"></a></h4>
<p>The <code>readthedocs</code> theme now more closely matches the <a href="https://github.com/rtfd/sphinx_rtd_theme/">upstream</a> Sphinx theme
(version 0.4.1). A number of new theme configuration settings were added which
mirror the upstream configuration options. See the <a href="../../user-guide/choosing-your-theme/#readthedocs">theme
documentation</a> for details.</p>
<h4 id="update-mkdocs-theme-to-bootswatch-413-1563">Update <code>mkdocs</code> theme to Bootswatch 4.1.3 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1563" title="GitHub Issue mkdocs/mkdocs #1563">#1563</a>)<a class="headerlink" href="#update-mkdocs-theme-to-bootswatch-413-1563" title="Permanent link"></a></h4>
<p>The <code>mkdocs</code> theme now supports all the features of <a href="https://getbootstrap.com/docs/4.1/getting-started/introduction/">Bootswatch 4.1</a>.
Additionally, 2 filenames were changed in this update. If you are using a theme
which inherits from the <code>mkdocs</code> theme, the theme developer may need to update
these filenames as follows.</p>
<pre class="highlight"><code class="language-text">css/bootstrap-custom.min.css =&gt; css/bootstrap.min.css
js/bootstrap-3.0.3.min.js =&gt; js/bootstrap.min.js</code></pre>
<h4 id="improved-configuration-support-on-the-command-line-1401">Improved configuration support on the command line (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1401" title="GitHub Issue mkdocs/mkdocs #1401">#1401</a>)<a class="headerlink" href="#improved-configuration-support-on-the-command-line-1401" title="Permanent link"></a></h4>
<p>The <code>build</code>, <code>serve</code>, and <code>gh-deploy</code> subcommands now support flags to control
whether <a href="../../user-guide/configuration/#use_directory_urls">directory URLs</a> should be created:
<code>--use-directory-urls</code> / <code>--no-directory-urls</code>. In addition, the <code>gh-deploy</code>
subcommand now supports all the configuration options that <code>build</code> and <code>serve</code>
do, adding <code>--strict</code>, <code>--theme</code>, <code>--theme-dir</code>, and <code>--site-dir</code>.</p>
<h4 id="updated-lunr-languages-support-1729">Updated lunr-languages support (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1729" title="GitHub Issue mkdocs/mkdocs #1729">#1729</a>)<a class="headerlink" href="#updated-lunr-languages-support-1729" title="Permanent link"></a></h4>
<p>The <code>lunr-languages</code> plugin has been updated to 1.4.0, adding support for
Arabic (<code>ar</code>) and Vietnamese (<code>vi</code>) languages. In addition, the Dutch and
Japanese language codes have been changed to their standard values: <code>nl</code> and
<code>ja</code>, respectively. The old language codes (<code>du</code> and <code>jp</code>) remain as aliases but
may be removed in a future version of MkDocs.</p>
<h3 id="other-changes-and-additions-to-version-11">Other Changes and Additions to Version 1.1<a class="headerlink" href="#other-changes-and-additions-to-version-11" title="Permanent link"></a></h3>
<ul>
<li>Bugfix: Ensure nested dot files in themes are ignored and document behavior (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1981" title="GitHub Issue mkdocs/mkdocs #1981">#1981</a>).</li>
<li>Update minimum dependency to Markdown 3.2.1.</li>
<li>Updated minimum dependency to Jinja 2.10.1 to address security concerns (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1780" title="GitHub Issue mkdocs/mkdocs #1780">#1780</a>).</li>
<li>Update to lunr.js 2.3.8 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1989" title="GitHub Issue mkdocs/mkdocs #1989">#1989</a>).</li>
<li>Add support for Python 3.8.</li>
<li>Drop support for Python 3.4.</li>
<li>Drop support for Python 2.7. MkDocs is PY3 only now (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1926" title="GitHub Issue mkdocs/mkdocs #1926">#1926</a>).</li>
<li>Bugfix: Select appropriate asyncio event loop on Windows for Python 3.8+ (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1885" title="GitHub Issue mkdocs/mkdocs #1885">#1885</a>).</li>
<li>Bugfix: Ensure nested index pages do not get identified as the homepage (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1919" title="GitHub Issue mkdocs/mkdocs #1919">#1919</a>).</li>
<li>Bugfix: Properly identify deployment version (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1879" title="GitHub Issue mkdocs/mkdocs #1879">#1879</a>).</li>
<li>Bugfix: Properly build <code>ValidationError</code> message for <code>custom_dir</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1849" title="GitHub Issue mkdocs/mkdocs #1849">#1849</a>).</li>
<li>Bugfix: Exclude Markdown files and READMEs from theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1766" title="GitHub Issue mkdocs/mkdocs #1766">#1766</a>).</li>
<li>Bugfix: Account for encoded URLs (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1670" title="GitHub Issue mkdocs/mkdocs #1670">#1670</a>).</li>
<li>Bugfix: Ensure theme files do not override <code>docs_dir</code> files (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1671" title="GitHub Issue mkdocs/mkdocs #1671">#1671</a>).</li>
<li>Bugfix: Do not normalize URL fragments (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1655" title="GitHub Issue mkdocs/mkdocs #1655">#1655</a>).</li>
<li>Bugfix: Skip external URLs in sitemap.xml (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1742" title="GitHub Issue mkdocs/mkdocs #1742">#1742</a>).</li>
<li>Bugfix: Ensure theme files do not override docs_dir files on Windows (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1876" title="GitHub Issue mkdocs/mkdocs #1876">#1876</a>)</li>
<li>Add canonical tag to <code>readthedocs</code> theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1669" title="GitHub Issue mkdocs/mkdocs #1669">#1669</a>).</li>
<li>Improved error message for when <code>git</code> is not available.</li>
<li>Add support for <code>nav_style</code> theme option for the <code>mkdocs</code> theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1930" title="GitHub Issue mkdocs/mkdocs #1930">#1930</a>).</li>
<li>Bugfix: Long/nested dropdowns now behave more consistently for the <code>mkdocs</code> theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1234" title="GitHub Issue mkdocs/mkdocs #1234">#1234</a>).</li>
<li>Bugfix: Multi-row nav headers in the <code>mkdocs</code> theme no longer obscure the document content (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/716" title="GitHub Issue mkdocs/mkdocs #716">#716</a>).</li>
<li>Add support for <code>navigation_depth</code> theme option for the <code>mkdocs</code> theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1970" title="GitHub Issue mkdocs/mkdocs #1970">#1970</a>).</li>
<li><code>level</code> attribute in <code>page.toc</code> items is now 1-indexed to match the level in <code>&lt;hN&gt;</code> tags (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1970" title="GitHub Issue mkdocs/mkdocs #1970">#1970</a>).</li>
</ul>
<h2 id="version-104-2018-09-07">Version 1.0.4 (2018-09-07)<a class="headerlink" href="#version-104-2018-09-07" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Ignore absolute links in Markdown (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1621" title="GitHub Issue mkdocs/mkdocs #1621">#1621</a>).</li>
</ul>
<h2 id="version-103-2018-08-29">Version 1.0.3 (2018-08-29)<a class="headerlink" href="#version-103-2018-08-29" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Warn on relative paths in navigation (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1604" title="GitHub Issue mkdocs/mkdocs #1604">#1604</a>).</li>
<li>Bugfix: Handle empty <code>theme_config.yml</code> files correctly (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1602" title="GitHub Issue mkdocs/mkdocs #1602">#1602</a>).</li>
</ul>
<h2 id="version-102-2018-08-22">Version 1.0.2 (2018-08-22)<a class="headerlink" href="#version-102-2018-08-22" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Provide absolute <code>base_url</code> to error templates (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1598" title="GitHub Issue mkdocs/mkdocs #1598">#1598</a>).</li>
</ul>
<h2 id="version-101-2018-08-13">Version 1.0.1 (2018-08-13)<a class="headerlink" href="#version-101-2018-08-13" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Prevent page reload when [Enter] is pressed in search box (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1589" title="GitHub Issue mkdocs/mkdocs #1589">#1589</a>).</li>
<li>Bugfix: Avoid calling <code>search</code> until all assets are ready (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1584" title="GitHub Issue mkdocs/mkdocs #1584">#1584</a>).</li>
<li>Bugfix: Exclude <code>README.md</code> if <code>index.md</code> is present (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1580" title="GitHub Issue mkdocs/mkdocs #1580">#1580</a>).</li>
<li>Bugfix: Fix <code>readthedocs</code> theme navigation bug with homepage (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1576" title="GitHub Issue mkdocs/mkdocs #1576">#1576</a>).</li>
</ul>
<h2 id="version-10-2018-08-03">Version 1.0 (2018-08-03)<a class="headerlink" href="#version-10-2018-08-03" title="Permanent link"></a></h2>
<h3 id="major-additions-to-version-10">Major Additions to Version 1.0<a class="headerlink" href="#major-additions-to-version-10" title="Permanent link"></a></h3>
<h4 id="internal-refactor-of-pages-files-and-navigation">Internal Refactor of Pages, Files, and Navigation<a class="headerlink" href="#internal-refactor-of-pages-files-and-navigation" title="Permanent link"></a></h4>
<p>Internal handling of pages, files and navigation has been completely refactored.
The changes included in the refactor are summarized below.</p>
<ul>
<li>Support for hidden pages. All Markdown pages are now included in the build
regardless of whether they are included in the navigation configuration
(<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/699" title="GitHub Issue mkdocs/mkdocs #699">#699</a>).</li>
<li>The navigation can now include links to external sites (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/989" title="GitHub Issue mkdocs/mkdocs #989">#989</a> <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1373" title="GitHub Issue mkdocs/mkdocs #1373">#1373</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1406" title="GitHub Issue mkdocs/mkdocs #1406">#1406</a>).</li>
<li>Page data (including titles) is properly determined for all pages before any
page is rendered (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1347" title="GitHub Issue mkdocs/mkdocs #1347">#1347</a>).</li>
<li>Automatically populated navigation now sorts index pages to the top. In other
words, The index page will be listed as the first child of a directory, while
all other documents are sorted alphanumerically by file name after the index
page (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/73" title="GitHub Issue mkdocs/mkdocs #73">#73</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1042" title="GitHub Issue mkdocs/mkdocs #1042">#1042</a>).</li>
<li>A <code>README.md</code> file is now treated as an index file within a directory and
will be rendered to <code>index.html</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/608" title="GitHub Issue mkdocs/mkdocs #608">#608</a>).</li>
<li>The URLs for all files are computed once and stored in a files collection.
This ensures all internal links are always computed correctly regardless of
the configuration. This also allows all internal links to be validated, not
just links to other Markdown pages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/842" title="GitHub Issue mkdocs/mkdocs #842">#842</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/872" title="GitHub Issue mkdocs/mkdocs #872">#872</a>).</li>
<li>A new <a href="../../dev-guide/themes/#url">url</a> template filter smartly ensures all URLs are relative to the
current page (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1526" title="GitHub Issue mkdocs/mkdocs #1526">#1526</a>).</li>
<li>An <a href="../../dev-guide/plugins/#on_files">on_files</a> plugin event has been added, which could be used to include
files not in the <code>docs_dir</code>, exclude files, redefine page URLs (i.e.
implement extensionless URLs), or to manipulate files in various other ways.</li>
</ul>
<h5 id="backward-incompatible-changes">Backward Incompatible Changes<a class="headerlink" href="#backward-incompatible-changes" title="Permanent link"></a></h5>
<p>As part of the internal refactor, a number of backward incompatible changes have
been introduced, which are summarized below.</p>
<h6 id="urls-have-changed-when-use_directory_urls-is-false">URLs have changed when <code>use_directory_urls</code> is <code>False</code><a class="headerlink" href="#urls-have-changed-when-use_directory_urls-is-false" title="Permanent link"></a></h6>
<p>Previously, all Markdown pages would be have their filenames altered to be index
pages regardless of how the <a href="../../user-guide/configuration/#use_directory_urls">use_directory_urls</a> setting was configured.
However, the path munging is only needed when <code>use_directory_urls</code> is set to
<code>True</code> (the default). The path mangling no longer happens when
<code>use_directory_urls</code> is set to <code>False</code>, which will result in different URLs for
all pages that were not already index files. As this behavior only effects a
non-default configuration, and the most common user-case for setting the option
to <code>False</code> is for local file system (<code>file://</code>) browsing, its not likely to
effect most users. However, if you have <code>use_directory_urls</code> set to <code>False</code>
for a MkDocs site hosted on a web server, most of your URLs will now be broken.
As you can see below, the new URLs are much more sensible.</p>
<table>
<thead>
<tr>
<th>Markdown file</th>
<th>Old URL</th>
<th>New URL</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>index.md</code></td>
<td><code>index.html</code></td>
<td><code>index.html</code></td>
</tr>
<tr>
<td><code>foo.md</code></td>
<td><code>foo/index.html</code></td>
<td><code>foo.html</code></td>
</tr>
<tr>
<td><code>foo/bar.md</code></td>
<td><code>foo/bar/index.html</code></td>
<td><code>foo/bar.html</code></td>
</tr>
</tbody>
</table>
<p>Note that there has been no change to URLs or file paths when
<code>use_directory_urls</code> is set to <code>True</code> (the default), except that MkDocs more
consistently includes an ending slash on all internally generated URLs.</p>
<h6 id="the-pages-configuration-setting-has-been-renamed-to-nav">The <code>pages</code> configuration setting has been renamed to <code>nav</code><a class="headerlink" href="#the-pages-configuration-setting-has-been-renamed-to-nav" title="Permanent link"></a></h6>
<p>The <code>pages</code> configuration setting is deprecated and will issue a warning if set
in the configuration file. The setting has been renamed <code>nav</code>. To update your
configuration, simply rename the setting to <code>nav</code>. In other words, if your
configuration looked like this:</p>
<pre class="highlight"><code class="language-yaml">pages:
- Home: index.md
- User Guide: user-guide.md</code></pre>
<p>Simply edit the configuration as follows:</p>
<pre class="highlight"><code class="language-yaml">nav:
- Home: index.md
- User Guide: user-guide.md</code></pre>
<p>In the current release, any configuration which includes a <code>pages</code> setting, but
no <code>nav</code> setting, the <code>pages</code> configuration will be copied to <code>nav</code> and a
warning will be issued. However, in a future release, that may no longer happen.
If both <code>pages</code> and <code>nav</code> are defined, the <code>pages</code> setting will be ignored.</p>
<h6 id="template-variables-and-base_url">Template variables and <code>base_url</code><a class="headerlink" href="#template-variables-and-base_url" title="Permanent link"></a></h6>
<p>In previous versions of MkDocs some URLs expected the <a href="../../dev-guide/themes/#base_url">base_url</a> template
variable to be prepended to the URL and others did not. That inconsistency has
been removed in that no URLs are modified before being added to the template
context.</p>
<p>For example, a theme template might have previously included a link to
the <code>site_name</code> as:</p>
<pre class="highlight"><code class="language-django">&lt;a href="{{ nav.homepage.url }}"&gt;{{ config.site_name }}&lt;/a&gt;</code></pre>
<p>And MkDocs would magically return a URL for the homepage which was relative to
the current page. That "magic" has been removed and the <a href="../../dev-guide/themes/#url">url</a> template filter
should be used:</p>
<pre class="highlight"><code class="language-django">&lt;a href="{{ nav.homepage.url|url }}"&gt;{{ config.site_name }}&lt;/a&gt;</code></pre>
<p>This change applies to any navigation items and pages, as well as the
<code>page.next_page</code> and <code>page.previous_page</code> attributes. For the time being, the
<code>extra_javascript</code> and <code>extra_css</code> variables continue to work as previously
(without the <code>url</code> template filter), but they have been deprecated and the
corresponding configuration values (<code>config.extra_javascript</code> and
<code>config.extra_css</code> respectively) should be used with the filter instead.</p>
<pre class="highlight"><code class="language-django">{% for path in config.extra_css %}
&lt;link href="{{ path|url }}" rel="stylesheet"&gt;
{% endfor %}</code></pre>
<p>Note that navigation can now include links to external sites. Obviously, the
<code>base_url</code> should not be prepended to these items. However, the <code>url</code> template
filter is smart enough to recognize the URL is absolute and does not alter it.
Therefore, all navigation items can be passed to the filter and only those that
need to will be altered.</p>
<pre class="highlight"><code class="language-django">{% for nav_item in nav %}
&lt;a href="{{ nav_item.url|url }}"&gt;{{ nav_item.title }}&lt;/a&gt;
{% endfor %}</code></pre>
<h4 id="path-based-settings-are-relative-to-configuration-file-543">Path Based Settings are Relative to Configuration File (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/543" title="GitHub Issue mkdocs/mkdocs #543">#543</a>)<a class="headerlink" href="#path-based-settings-are-relative-to-configuration-file-543" title="Permanent link"></a></h4>
<p>Previously any relative paths in the various configuration options were
resolved relative to the current working directory. They are now resolved
relative to the configuration file. As the documentation has always encouraged
running the various MkDocs commands from the directory that contains the
configuration file (project root), this change will not affect most users.
However, it will make it much easier to implement automated builds or otherwise
run commands from a location other than the project root.</p>
<p>Simply use the <code>-f/--config-file</code> option and point it at the configuration file:</p>
<pre class="highlight"><code class="language-sh">mkdocs build --config-file /path/to/my/config/file.yml</code></pre>
<p>As previously, if no file is specified, MkDocs looks for a file named
<code>mkdocs.yml</code> in the current working directory.</p>
<h4 id="added-support-for-yaml-meta-data-1542">Added support for YAML Meta-Data (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1542" title="GitHub Issue mkdocs/mkdocs #1542">#1542</a>)<a class="headerlink" href="#added-support-for-yaml-meta-data-1542" title="Permanent link"></a></h4>
<p>Previously, MkDocs only supported MultiMarkdown style meta-data, which does not
recognize different data types and is rather limited. MkDocs now also supports
YAML style meta-data in Markdown documents. MkDocs relies on the the presence or
absence of the deliminators (<code>---</code> or <code>...</code>) to determine whether YAML style
meta-data or MultiMarkdown style meta-data is being used.</p>
<p>Previously MkDocs would recognize MultiMarkdown style meta-data between the
deliminators. Now, if the deliminators are detected, but the content between the
deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the
content as MultiMarkdown style meta-data. Therefore, MultiMarkdown's style
meta-data must not include the deliminators. See the <a href="../../user-guide/writing-your-docs/#multimarkdown-style-meta-data">MultiMarkdown style
meta-data documentation</a> for details.</p>
<p>Prior to version 0.17, MkDocs returned all meta-data values as a list of strings
(even a single line would return a list of one string). In version 0.17, that
behavior was changed to return each value as a single string (multiple lines
were joined), which some users found limiting (see <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1471" title="GitHub Issue mkdocs/mkdocs #1471">#1471</a>). That behavior
continues for MultiMarkdown style meta-data in the current version. However,
YAML style meta-data supports the full range of "safe" YAML data types.
Therefore, it is recommended that any complex meta-data make use of the YAML
style (see the <a href="../../user-guide/writing-your-docs/#yaml-style-meta-data">YAML style meta-data documentation</a> for details). In fact, a
future version of MkDocs may deprecate support for MultiMarkdown style
meta-data.</p>
<h4 id="refactor-search-plugin">Refactor Search Plugin<a class="headerlink" href="#refactor-search-plugin" title="Permanent link"></a></h4>
<p>The search plugin has been completely refactored to include support for the
following features:</p>
<ul>
<li>Use a web worker in the browser with a fallback (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1396" title="GitHub Issue mkdocs/mkdocs #1396">#1396</a>).</li>
<li>Optionally pre-build search index locally (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/859" title="GitHub Issue mkdocs/mkdocs #859">#859</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1061" title="GitHub Issue mkdocs/mkdocs #1061">#1061</a>).</li>
<li>Upgrade to lunr.js 2.x (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1319" title="GitHub Issue mkdocs/mkdocs #1319">#1319</a>).</li>
<li>Support search in languages other than English (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/826" title="GitHub Issue mkdocs/mkdocs #826">#826</a>).</li>
<li>Allow the user to define the word separators (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/867" title="GitHub Issue mkdocs/mkdocs #867">#867</a>).</li>
<li>Only run searches for queries of length &gt; 2 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1127" title="GitHub Issue mkdocs/mkdocs #1127">#1127</a>).</li>
<li>Remove dependency on require.js (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1218" title="GitHub Issue mkdocs/mkdocs #1218">#1218</a>).</li>
<li>Compress the search index (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1128" title="GitHub Issue mkdocs/mkdocs #1128">#1128</a>).</li>
</ul>
<p>Users can review the <a href="../../user-guide/configuration/#search">configuration options</a> available and theme
authors should review how <a href="../../dev-guide/themes/#search-and-themes">search and themes</a> interact.</p>
<h4 id="theme_dir-configuration-option-fully-deprecated"><code>theme_dir</code> Configuration Option fully Deprecated<a class="headerlink" href="#theme_dir-configuration-option-fully-deprecated" title="Permanent link"></a></h4>
<p>As of version 0.17, the <a href="../../user-guide/configuration/#custom_dir">custom_dir</a> option replaced the deprecated <code>theme_dir</code>
option. If users had set the <code>theme_dir</code> option, MkDocs version 0.17 copied the
value to the <code>theme.custom_dir</code> option and a warning was issued. As of version
1.0, the value is no longer copied and an error is raised.</p>
<h3 id="other-changes-and-additions-to-version-10">Other Changes and Additions to Version 1.0<a class="headerlink" href="#other-changes-and-additions-to-version-10" title="Permanent link"></a></h3>
<ul>
<li>Keyboard shortcuts changed to not conflict with commonly used accessibility shortcuts (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1502" title="GitHub Issue mkdocs/mkdocs #1502">#1502</a>.)</li>
<li>User friendly YAML parse errors (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1543" title="GitHub Issue mkdocs/mkdocs #1543">#1543</a>).</li>
<li>Officially support Python 3.7.</li>
<li>A missing theme configuration file now raises an error.</li>
<li>Empty <code>extra_css</code> and <code>extra_javascript</code> settings no longer raise a warning.</li>
<li>Add highlight.js configuration settings to built-in themes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1284" title="GitHub Issue mkdocs/mkdocs #1284">#1284</a>).</li>
<li>Close search modal when result is selected (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1527" title="GitHub Issue mkdocs/mkdocs #1527">#1527</a>).</li>
<li>Add a level attribute to AnchorLinks (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1272" title="GitHub Issue mkdocs/mkdocs #1272">#1272</a>).</li>
<li>Add MkDocs version check to gh-deploy script (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/640" title="GitHub Issue mkdocs/mkdocs #640">#640</a>).</li>
<li>Improve Markdown extension error messages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/782" title="GitHub Issue mkdocs/mkdocs #782">#782</a>).</li>
<li>Drop official support for Python 3.3 and set <code>tornado&gt;=5.0</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1427" title="GitHub Issue mkdocs/mkdocs #1427">#1427</a>).</li>
<li>Add support for GitLab edit links (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1435" title="GitHub Issue mkdocs/mkdocs #1435">#1435</a>).</li>
<li>Link to GitHub issues from release notes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/644" title="GitHub Issue mkdocs/mkdocs #644">#644</a>).</li>
<li>Expand {sha} and {version} in gh-deploy commit message (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1410" title="GitHub Issue mkdocs/mkdocs #1410">#1410</a>).</li>
<li>Compress <code>sitemap.xml</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1130" title="GitHub Issue mkdocs/mkdocs #1130">#1130</a>).</li>
<li>Defer loading JS scripts (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1380" title="GitHub Issue mkdocs/mkdocs #1380">#1380</a>).</li>
<li>Add a title attribute to the search input (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1379" title="GitHub Issue mkdocs/mkdocs #1379">#1379</a>).</li>
<li>Update RespondJS to latest version (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1398" title="GitHub Issue mkdocs/mkdocs #1398">#1398</a>).</li>
<li>Always load Google Analytics over HTTPS (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1397" title="GitHub Issue mkdocs/mkdocs #1397">#1397</a>).</li>
<li>Improve scrolling frame rate (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1394" title="GitHub Issue mkdocs/mkdocs #1394">#1394</a>).</li>
<li>Provide more version info. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1393" title="GitHub Issue mkdocs/mkdocs #1393">#1393</a>).</li>
<li>Refactor <code>writing-your-docs.md</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1392" title="GitHub Issue mkdocs/mkdocs #1392">#1392</a>).</li>
<li>Workaround Safari bug when zooming to &lt; 100% (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1389" title="GitHub Issue mkdocs/mkdocs #1389">#1389</a>).</li>
<li>Remove addition of <code>clicky</code> class to body and animations. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1387" title="GitHub Issue mkdocs/mkdocs #1387">#1387</a>).</li>
<li>Prevent search plugin from re-injecting <code>extra_javascript</code> files (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1388" title="GitHub Issue mkdocs/mkdocs #1388">#1388</a>).</li>
<li>Refactor <code>copy_media_files</code> util function for more flexibility (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1370" title="GitHub Issue mkdocs/mkdocs #1370">#1370</a>).</li>
<li>Remove PyPI Deployment Docs (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1360" title="GitHub Issue mkdocs/mkdocs #1360">#1360</a>).</li>
<li>Update links to Python-Markdown library (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1360" title="GitHub Issue mkdocs/mkdocs #1360">#1360</a>).</li>
<li>Document how to generate manpages for MkDocs commands (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/686" title="GitHub Issue mkdocs/mkdocs #686">#686</a>).</li>
</ul>
<h2 id="version-0175-2018-07-06">Version 0.17.5 (2018-07-06)<a class="headerlink" href="#version-0175-2018-07-06" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Fix Python 3.7 and PEP 479 incompatibility (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1518" title="GitHub Issue mkdocs/mkdocs #1518">#1518</a>).</li>
</ul>
<h2 id="version-0174-2018-06-08">Version 0.17.4 (2018-06-08)<a class="headerlink" href="#version-0174-2018-06-08" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Add multi-level nesting support to sitemap.xml (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1482" title="GitHub Issue mkdocs/mkdocs #1482">#1482</a>).</li>
</ul>
<h2 id="version-0173-2018-03-07">Version 0.17.3 (2018-03-07)<a class="headerlink" href="#version-0173-2018-03-07" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Set dependency <code>tornado&gt;=4.1,&lt;5.0</code> due to changes in 5.0 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1428" title="GitHub Issue mkdocs/mkdocs #1428">#1428</a>).</li>
</ul>
<h2 id="version-0172-2017-11-15">Version 0.17.2 (2017-11-15)<a class="headerlink" href="#version-0172-2017-11-15" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Correct <code>extra_*</code> config setting regressions (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1335" title="GitHub Issue mkdocs/mkdocs #1335">#1335</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1336" title="GitHub Issue mkdocs/mkdocs #1336">#1336</a>).</li>
</ul>
<h2 id="version-0171-2017-10-30">Version 0.17.1 (2017-10-30)<a class="headerlink" href="#version-0171-2017-10-30" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Support <code>repo_url</code> with missing ending slash. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1321" title="GitHub Issue mkdocs/mkdocs #1321">#1321</a>).</li>
<li>Bugfix: Add length support to <code>mkdocs.toc.TableOfContext</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1325" title="GitHub Issue mkdocs/mkdocs #1325">#1325</a>).</li>
<li>Bugfix: Add some theme specific settings to the search plugin for third party themes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1316" title="GitHub Issue mkdocs/mkdocs #1316">#1316</a>).</li>
<li>Bugfix: Override <code>site_url</code> with <code>dev_addr</code> on local server (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1317" title="GitHub Issue mkdocs/mkdocs #1317">#1317</a>).</li>
</ul>
<h2 id="version-0170-2017-10-19">Version 0.17.0 (2017-10-19)<a class="headerlink" href="#version-0170-2017-10-19" title="Permanent link"></a></h2>
<h3 id="major-additions-to-version-0170">Major Additions to Version 0.17.0<a class="headerlink" href="#major-additions-to-version-0170" title="Permanent link"></a></h3>
<h4 id="plugin-api-206">Plugin API. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/206" title="GitHub Issue mkdocs/mkdocs #206">#206</a>)<a class="headerlink" href="#plugin-api-206" title="Permanent link"></a></h4>
<p>A new <a href="../../dev-guide/plugins/">Plugin API</a> has been added to MkDocs which allows users to define their
own custom behaviors. See the included documentation for a full explanation of
the API.</p>
<p>The previously built-in search functionality has been removed and wrapped in a
plugin (named "search") with no changes in behavior. When MkDocs builds, the
search index is now written to <code>search/search_index.json</code> instead of
<code>mkdocs/search_index.json</code>. If no plugins setting is defined in the config,
then the <code>search</code> plugin will be included by default. See the
<a href="../../user-guide/configuration/#plugins">configuration</a> documentation for information on overriding the
default.</p>
<h4 id="theme-customization-1164">Theme Customization. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1164" title="GitHub Issue mkdocs/mkdocs #1164">#1164</a>)<a class="headerlink" href="#theme-customization-1164" title="Permanent link"></a></h4>
<p>Support had been added to provide theme specific customizations. Theme authors
can define default options as documented in <a href="../../dev-guide/themes/#theme-configuration">Theme Configuration</a>. A theme can
now inherit from another theme, define various static templates to be rendered,
and define arbitrary default variables to control behavior in the templates.
The theme configuration is defined in a configuration file named
<code>mkdocs_theme.yml</code> which should be placed at the root of your template files. A
warning will be raised if no configuration file is found and an error will be
raised in a future release.</p>
<p>Users can override those defaults under the <a href="../../user-guide/configuration/#theme">theme</a> configuration option of
their <code>mkdocs.yml</code> configuration file, which now accepts nested options. One
such nested option is the <a href="../../user-guide/configuration/#custom_dir">custom_dir</a> option, which replaces the now deprecated
<code>theme_dir</code> option. If users had previously set the <code>theme_dir</code> option, a
warning will be issued, with an error expected in a future release.</p>
<p>If a configuration previously defined a <code>theme_dir</code> like this:</p>
<pre class="highlight"><code class="language-yaml">theme: mkdocs
theme_dir: custom</code></pre>
<p>Then the configuration should be adjusted as follows:</p>
<pre class="highlight"><code class="language-yaml">theme:
name: mkdocs
custom_dir: custom</code></pre>
<p>See the <a href="../../user-guide/configuration/#theme">theme</a> configuration option documentation for details.</p>
<h4 id="previously-deprecated-template-variables-removed-1168">Previously deprecated Template variables removed. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1168" title="GitHub Issue mkdocs/mkdocs #1168">#1168</a>)<a class="headerlink" href="#previously-deprecated-template-variables-removed-1168" title="Permanent link"></a></h4>
<h5 id="page-template">Page Template<a class="headerlink" href="#page-template" title="Permanent link"></a></h5>
<p>The primary entry point for page templates has been changed from <code>base.html</code> to
<code>main.html</code>. This allows <code>base.html</code> to continue to exist while allowing users
to override <code>main.html</code> and extend <code>base.html</code>. For version 0.16, <code>base.html</code>
continued to work if no <code>main.html</code> template existed, but it raised a
deprecation warning. In version 1.0, a build will fail if no <code>main.html</code>
template exists.</p>
<h5 id="context-variables">Context Variables<a class="headerlink" href="#context-variables" title="Permanent link"></a></h5>
<p>Page specific variable names in the template context have been refactored as
defined in <a href="../../dev-guide/themes/#page">Custom Themes</a>. The
old variable names issued a warning in version 0.16, but have been removed in
version 1.0.</p>
<p>Any of the following old page variables should be updated to the new ones in
user created and third-party templates:</p>
<table>
<thead>
<tr>
<th>Old Variable Name</th>
<th>New Variable Name</th>
</tr>
</thead>
<tbody>
<tr>
<td>current_page</td>
<td><a href="../../dev-guide/themes/#page">page</a></td>
</tr>
<tr>
<td>page_title</td>
<td>page.title</td>
</tr>
<tr>
<td>content</td>
<td>page.content</td>
</tr>
<tr>
<td>toc</td>
<td>page.toc</td>
</tr>
<tr>
<td>meta</td>
<td>page.meta</td>
</tr>
<tr>
<td>canonical_url</td>
<td>page.canonical_url</td>
</tr>
<tr>
<td>previous_page</td>
<td>page.previous_page</td>
</tr>
<tr>
<td>next_page</td>
<td>page.next_page</td>
</tr>
</tbody>
</table>
<p>Additionally, a number of global variables have been altered and/or removed
and user created and third-party templates should be updated as outlined below:</p>
<table>
<thead>
<tr>
<th>Old Variable Name</th>
<th>New Variable Name or Expression</th>
</tr>
</thead>
<tbody>
<tr>
<td>current_page</td>
<td>page</td>
</tr>
<tr>
<td>include_nav</td>
<td>nav&#124;length&gt;1</td>
</tr>
<tr>
<td>include_next_prev</td>
<td>(page.next_page or page.previous_page)</td>
</tr>
<tr>
<td>site_name</td>
<td>config.site_name</td>
</tr>
<tr>
<td>site_author</td>
<td>config.site_author</td>
</tr>
<tr>
<td>page_description</td>
<td>config.site_description</td>
</tr>
<tr>
<td>repo_url</td>
<td>config.repo_url</td>
</tr>
<tr>
<td>repo_name</td>
<td>config.repo_name</td>
</tr>
<tr>
<td>site_url</td>
<td>config.site_url</td>
</tr>
<tr>
<td>copyright</td>
<td>config.copyright</td>
</tr>
<tr>
<td>google_analytics</td>
<td>config.google_analytics</td>
</tr>
<tr>
<td>homepage_url</td>
<td>nav.homepage.url</td>
</tr>
<tr>
<td>favicon</td>
<td>{{ base_url }}/img/favicon.ico</td>
</tr>
</tbody>
</table>
<h4 id="auto-populated-extra_css-and-extra_javascript-fully-deprecated-986">Auto-Populated extra_css and extra_javascript Fully Deprecated. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/986" title="GitHub Issue mkdocs/mkdocs #986">#986</a>)<a class="headerlink" href="#auto-populated-extra_css-and-extra_javascript-fully-deprecated-986" title="Permanent link"></a></h4>
<p>In previous versions of MkDocs, if the <code>extra_css</code> or <code>extra_javascript</code> config
settings were empty, MkDocs would scan the <code>docs_dir</code> and auto-populate each
setting with all of the CSS and JavaScript files found. On version 0.16 this
behavior was deprecated and a warning was issued. In 0.17 any unlisted CSS and
JavaScript files will not be included in the HTML templates, however, a warning
will be issued. In other words, they will still be copied to the <code>site-dir</code>, but
they will not have any effect on the theme if they are not explicitly listed.</p>
<p>All CSS and JavaScript files in the <code>docs_dir</code> should be explicitly listed in
the <code>extra_css</code> or <code>extra_javascript</code> config settings going forward.</p>
<h3 id="other-changes-and-additions-to-version-0170">Other Changes and Additions to Version 0.17.0<a class="headerlink" href="#other-changes-and-additions-to-version-0170" title="Permanent link"></a></h3>
<ul>
<li>Add "edit Link" support to MkDocs theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1129" title="GitHub Issue mkdocs/mkdocs #1129">#1129</a>)</li>
<li>Open files with <code>utf-8-sig</code> to account for BOM (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1186" title="GitHub Issue mkdocs/mkdocs #1186">#1186</a>)</li>
<li>Symbolic links are now followed consistently (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1134" title="GitHub Issue mkdocs/mkdocs #1134">#1134</a>)</li>
<li>Support for keyboard navigation shortcuts added to included themes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1095" title="GitHub Issue mkdocs/mkdocs #1095">#1095</a>)</li>
<li>Some refactoring and improvements to config_options (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1296" title="GitHub Issue mkdocs/mkdocs #1296">#1296</a>)</li>
<li>Officially added support for Python 3.6 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1296" title="GitHub Issue mkdocs/mkdocs #1296">#1296</a>)</li>
<li>404 Error page added to readthedocs theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1296" title="GitHub Issue mkdocs/mkdocs #1296">#1296</a>))</li>
<li>Internal refactor of Markdown processing (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/713" title="GitHub Issue mkdocs/mkdocs #713">#713</a>)</li>
<li>Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch themes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1168" title="GitHub Issue mkdocs/mkdocs #1168">#1168</a>)</li>
<li>The legacy pages config is no longer supported (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1168" title="GitHub Issue mkdocs/mkdocs #1168">#1168</a>)</li>
<li>The deprecated <code>json</code> command has been removed (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/481" title="GitHub Issue mkdocs/mkdocs #481">#481</a>)</li>
<li>Support for Python 2.6 has been dropped (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/165" title="GitHub Issue mkdocs/mkdocs #165">#165</a>)</li>
<li>File permissions are no longer copied during build (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1292" title="GitHub Issue mkdocs/mkdocs #1292">#1292</a>)</li>
<li>Support query and fragment strings in <code>edit_uri</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1224" title="GitHub Issue mkdocs/mkdocs #1224">#1224</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1273" title="GitHub Issue mkdocs/mkdocs #1273">#1273</a>)</li>
</ul>
<h2 id="version-0163-2017-04-04">Version 0.16.3 (2017-04-04)<a class="headerlink" href="#version-0163-2017-04-04" title="Permanent link"></a></h2>
<ul>
<li>Fix error raised by autoscrolling in the readthedocs theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1177" title="GitHub Issue mkdocs/mkdocs #1177">#1177</a>)</li>
<li>Fix a few documentation typos (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1181" title="GitHub Issue mkdocs/mkdocs #1181">#1181</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1185" title="GitHub Issue mkdocs/mkdocs #1185">#1185</a>)</li>
<li>Fix a regression to livereload server introduced in 0.16.2 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1174" title="GitHub Issue mkdocs/mkdocs #1174">#1174</a>)</li>
</ul>
<h2 id="version-0162-2017-03-13">Version 0.16.2 (2017-03-13)<a class="headerlink" href="#version-0162-2017-03-13" title="Permanent link"></a></h2>
<ul>
<li>System root (<code>/</code>) is not a valid path for site_dir or docs_dir (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1161" title="GitHub Issue mkdocs/mkdocs #1161">#1161</a>)</li>
<li>Refactor readthedocs theme navigation (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1155" title="GitHub Issue mkdocs/mkdocs #1155">#1155</a> &amp; <a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1156" title="GitHub Issue mkdocs/mkdocs #1156">#1156</a>)</li>
<li>Add support to dev server to serve custom error pages (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1040" title="GitHub Issue mkdocs/mkdocs #1040">#1040</a>)</li>
<li>Ensure nav.homepage.url is not blank on error pages (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1131" title="GitHub Issue mkdocs/mkdocs #1131">#1131</a>)</li>
<li>Increase livereload dependency to 2.5.1 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1106" title="GitHub Issue mkdocs/mkdocs #1106">#1106</a>)</li>
</ul>
<h2 id="version-0161-2016-12-22">Version 0.16.1 (2016-12-22)<a class="headerlink" href="#version-0161-2016-12-22" title="Permanent link"></a></h2>
<ul>
<li>Ensure scrollspy behavior does not affect nav bar (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1094" title="GitHub Issue mkdocs/mkdocs #1094">#1094</a>)</li>
<li>Only "load" a theme when it is explicitly requested by the user (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1105" title="GitHub Issue mkdocs/mkdocs #1105">#1105</a>)</li>
</ul>
<h2 id="version-016-2016-11-04">Version 0.16 (2016-11-04)<a class="headerlink" href="#version-016-2016-11-04" title="Permanent link"></a></h2>
<h3 id="major-additions-to-version-0160">Major Additions to Version 0.16.0<a class="headerlink" href="#major-additions-to-version-0160" title="Permanent link"></a></h3>
<h4 id="template-variables-refactored-874">Template variables refactored. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/874" title="GitHub Issue mkdocs/mkdocs #874">#874</a>)<a class="headerlink" href="#template-variables-refactored-874" title="Permanent link"></a></h4>
<h5 id="page-context">Page Context<a class="headerlink" href="#page-context" title="Permanent link"></a></h5>
<p>Page specific variable names in the template context have been refactored as
defined in <a href="../../dev-guide/themes/#page">Custom Themes</a>. The
old variable names will issue a warning but continue to work for version 0.16,
but may be removed in a future version.</p>
<p>Any of the following old page variables should be updated to the new ones in
user created and third-party templates:</p>
<table>
<thead>
<tr>
<th>Old Variable Name</th>
<th>New Variable Name</th>
</tr>
</thead>
<tbody>
<tr>
<td>current_page</td>
<td><a href="../../dev-guide/themes/#page">page</a></td>
</tr>
<tr>
<td>page_title</td>
<td>page.title</td>
</tr>
<tr>
<td>content</td>
<td>page.content</td>
</tr>
<tr>
<td>toc</td>
<td>page.toc</td>
</tr>
<tr>
<td>meta</td>
<td>page.meta</td>
</tr>
<tr>
<td>canonical_url</td>
<td>page.canonical_url</td>
</tr>
<tr>
<td>previous_page</td>
<td>page.previous_page</td>
</tr>
<tr>
<td>next_page</td>
<td>page.next_page</td>
</tr>
</tbody>
</table>
<h5 id="global-context">Global Context<a class="headerlink" href="#global-context" title="Permanent link"></a></h5>
<p>Additionally, a number of global variables have been altered and/or deprecated
and user created and third-party templates should be updated as outlined below:</p>
<p>Previously, the global variable <code>include_nav</code> was altered programmatically based
on the number of pages in the nav. The variable will issue a warning but
continue to work for version 0.16, but may be removed in a future version. Use
<code>{% if nav|length&gt;1 %}</code> instead.</p>
<p>Previously, the global variable <code>include_next_prev</code> was altered programmatically
based on the number of pages in the nav. The variable will issue a warning but
continue to work for version 0.16, but may be removed in a future version. Use
<code>{% if page.next_page or page.previous_page %}</code> instead.</p>
<p>Previously the global variable <code>page_description</code> was altered programmatically
based on whether the current page was the homepage. Now it simply maps to
<code>config['site_description']</code>. Use <code>{% if page.is_homepage %}</code> in the template to
conditionally change the description.</p>
<p>The global variable <code>homepage_url</code> maps directly to <code>nav.homepage.url</code> and is
being deprecated. The variable will issue a warning but continue to work for
version 0.16, but may be removed in a future version. Use <code>nav.homepage.url</code>
instead.</p>
<p>The global variable <code>favicon</code> maps to the configuration setting <code>site_favicon</code>.
Both the template variable and the configuration setting are being deprecated
and will issue a warning but continue to work for version 0.16, and may be
removed in a future version. Use <code>{{ base_url }}/img/favicon.ico</code> in your
template instead. Users can simply save a copy of their custom favicon icon to
<code>img/favicon.ico</code> in either their <code>docs_dir</code> or <code>theme_dir</code>.</p>
<p>A number of variables map directly to similarly named variables in the <code>config</code>.
Those variables are being deprecated and will issue a warning but continue to
work for version 0.16, but may be removed in a future version. Use
<code>config.var_name</code> instead, where <code>var_name</code> is the name of one of the
<a href="../../user-guide/configuration/">configuration</a> variables.</p>
<p>Below is a summary of all of the changes made to the global context:</p>
<table>
<thead>
<tr>
<th>Old Variable Name</th>
<th>New Variable Name or Expression</th>
</tr>
</thead>
<tbody>
<tr>
<td>current_page</td>
<td>page</td>
</tr>
<tr>
<td>include_nav</td>
<td>nav&#124;length&gt;1</td>
</tr>
<tr>
<td>include_next_prev</td>
<td>(page.next_page or page.previous_page)</td>
</tr>
<tr>
<td>site_name</td>
<td>config.site_name</td>
</tr>
<tr>
<td>site_author</td>
<td>config.site_author</td>
</tr>
<tr>
<td>page_description</td>
<td>config.site_description</td>
</tr>
<tr>
<td>repo_url</td>
<td>config.repo_url</td>
</tr>
<tr>
<td>repo_name</td>
<td>config.repo_name</td>
</tr>
<tr>
<td>site_url</td>
<td>config.site_url</td>
</tr>
<tr>
<td>copyright</td>
<td>config.copyright</td>
</tr>
<tr>
<td>google_analytics</td>
<td>config.google_analytics</td>
</tr>
<tr>
<td>homepage_url</td>
<td>nav.homepage.url</td>
</tr>
<tr>
<td>favicon</td>
<td>{{ base_url }}/img/favicon.ico</td>
</tr>
</tbody>
</table>
<h4 id="increased-template-customization-607">Increased Template Customization. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/607" title="GitHub Issue mkdocs/mkdocs #607">#607</a>)<a class="headerlink" href="#increased-template-customization-607" title="Permanent link"></a></h4>
<p>The built-in themes have been updated by having each of their many parts wrapped
in template blocks which allow each individual block to be easily overridden
using the <code>theme_dir</code> config setting. Without any new settings, you can use a
different analytics service, replace the default search function, or alter the
behavior of the navigation, among other things. See the relevant
<a href="../../user-guide/customizing-your-theme/#overriding-template-blocks">documentation</a> for more details.</p>
<p>To enable this feature, the primary entry point for page templates has been
changed from <code>base.html</code> to <code>main.html</code>. This allows <code>base.html</code> to continue to
exist while allowing users to override <code>main.html</code> and extend <code>base.html</code>. For
version 0.16, <code>base.html</code> will continue to work if no <code>main.html</code> template
exists, but it is deprecated and will raise a warning. In version 1.0, a build
will fail if no <code>main.html</code> template exists. Any custom and third party
templates should be updated accordingly.</p>
<p>The easiest way for a third party theme to be updated would be to simply add a
<code>main.html</code> file which only contains the following line:</p>
<pre class="highlight"><code class="language-django">{% extends "base.html" %}</code></pre>
<p>That way, the theme contains the <code>main.html</code> entry point, and also supports
overriding blocks in the same manner as the built-in themes. Third party themes
are encouraged to wrap the various pieces of their templates in blocks in order
to support such customization.</p>
<h4 id="auto-populated-extra_css-and-extra_javascript-deprecated-986">Auto-Populated <code>extra_css</code> and <code>extra_javascript</code> Deprecated. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/986" title="GitHub Issue mkdocs/mkdocs #986">#986</a>)<a class="headerlink" href="#auto-populated-extra_css-and-extra_javascript-deprecated-986" title="Permanent link"></a></h4>
<p>In previous versions of MkDocs, if the <code>extra_css</code> or <code>extra_javascript</code> config
settings were empty, MkDocs would scan the <code>docs_dir</code> and auto-populate each
setting with all of the CSS and JavaScript files found. This behavior is
deprecated and a warning will be issued. In the next release, the auto-populate
feature will stop working and any unlisted CSS and JavaScript files will not be
included in the HTML templates. In other words, they will still be copied to the
<code>site-dir</code>, but they will not have any effect on the theme if they are not
explicitly listed.</p>
<p>All CSS and JavaScript files in the <code>docs_dir</code> should be explicitly listed in
the <code>extra_css</code> or <code>extra_javascript</code> config settings going forward.</p>
<h4 id="support-for-dirty-builds-990">Support for dirty builds. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/990" title="GitHub Issue mkdocs/mkdocs #990">#990</a>)<a class="headerlink" href="#support-for-dirty-builds-990" title="Permanent link"></a></h4>
<p>For large sites the build time required to create the pages can become problematic,
thus a "dirty" build mode was created. This mode simply compares the modified time
of the generated HTML and source markdown. If the markdown has changed since the
HTML then the page is re-constructed. Otherwise, the page remains as is. This mode
may be invoked in both the <code>mkdocs serve</code> and <code>mkdocs build</code> commands:</p>
<pre class="highlight"><code class="language-text">mkdocs serve --dirtyreload</code></pre>
<pre class="highlight"><code class="language-text">mkdocs build --dirty</code></pre>
<p>It is important to note that this method for building the pages is for development
of content only, since the navigation and other links do not get updated on other
pages.</p>
<h4 id="stricter-directory-validation">Stricter Directory Validation<a class="headerlink" href="#stricter-directory-validation" title="Permanent link"></a></h4>
<p>Previously, a warning was issued if the <code>site_dir</code> was a child directory of the
<code>docs_dir</code>. This now raises an error. Additionally, an error is now raised if
the <code>docs_dir</code> is set to the directory which contains your config file rather
than a child directory. You will need to rearrange you directory structure to
better conform with the documented <a href="../../user-guide/writing-your-docs/#file-layout">layout</a>.</p>
<h3 id="other-changes-and-additions-to-version-0160">Other Changes and Additions to Version 0.16.0<a class="headerlink" href="#other-changes-and-additions-to-version-0160" title="Permanent link"></a></h3>
<ul>
<li>Bugfix: Support <code>gh-deploy</code> command on Windows with Python 3 (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/722" title="GitHub Issue mkdocs/mkdocs #722">#722</a>)</li>
<li>Bugfix: Include .woff2 font files in Python package build (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/894" title="GitHub Issue mkdocs/mkdocs #894">#894</a>)</li>
<li>Various updates and improvements to Documentation Home Page/Tutorial (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/870" title="GitHub Issue mkdocs/mkdocs #870">#870</a>)</li>
<li>Bugfix: Support livereload for config file changes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/735" title="GitHub Issue mkdocs/mkdocs #735">#735</a>)</li>
<li>Bugfix: Non-media template files are no longer copied with media files (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/807" title="GitHub Issue mkdocs/mkdocs #807">#807</a>)</li>
<li>Add a flag (-e/--theme-dir) to specify theme directory with the commands <code>mkdocs build</code> and <code>mkdocs serve</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/832" title="GitHub Issue mkdocs/mkdocs #832">#832</a>)</li>
<li>Fixed issues with Unicode file names under Windows and Python 2. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/833" title="GitHub Issue mkdocs/mkdocs #833">#833</a>)</li>
<li>Improved the styling of in-line code in the MkDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/718" title="GitHub Issue mkdocs/mkdocs #718">#718</a>)</li>
<li>Bugfix: convert variables to JSON when being passed to JavaScript (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/850" title="GitHub Issue mkdocs/mkdocs #850">#850</a>)</li>
<li>Updated the ReadTheDocs theme to match the upstream font sizes and colors more closely. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/857" title="GitHub Issue mkdocs/mkdocs #857">#857</a>)</li>
<li>Fixes an issue with permalink markers showing when the mouse was far above them (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/843" title="GitHub Issue mkdocs/mkdocs #843">#843</a>)</li>
<li>Bugfix: Handle periods in directory name when automatically creating the pages config. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/728" title="GitHub Issue mkdocs/mkdocs #728">#728</a>)</li>
<li>Update searching to Lunr 0.7, which comes with some performance enhancements for larger documents (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/859" title="GitHub Issue mkdocs/mkdocs #859">#859</a>)</li>
<li>Bugfix: Support SOURCE_DATE_EPOCH environment variable for "reproducible" builds (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/938" title="GitHub Issue mkdocs/mkdocs #938">#938</a>)</li>
<li>Follow links when copying media files (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/869" title="GitHub Issue mkdocs/mkdocs #869">#869</a>).</li>
<li>Change "Edit on..." links to point directly to the file in the source repository, rather than to the root of the repository (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/975" title="GitHub Issue mkdocs/mkdocs #975">#975</a>), configurable via the new <a href="../../user-guide/configuration/#edit_uri"><code>edit_uri</code></a> setting.</li>
<li>Bugfix: Don't override config value for strict mode if not specified on CLI (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/738" title="GitHub Issue mkdocs/mkdocs #738">#738</a>).</li>
<li>Add a <code>--force</code> flag to the <code>gh-deploy</code> command to force the push to the repository (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/973" title="GitHub Issue mkdocs/mkdocs #973">#973</a>).</li>
<li>Improve alignment for current selected menu item in readthedocs theme (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/888" title="GitHub Issue mkdocs/mkdocs #888">#888</a>).</li>
<li><code>http://user.github.io/repo</code> =&gt; <code>https://user.github.io/repo/</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1029" title="GitHub Issue mkdocs/mkdocs #1029">#1029</a>).</li>
<li>Improve installation instructions (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1028" title="GitHub Issue mkdocs/mkdocs #1028">#1028</a>).</li>
<li>Account for wide tables and consistently wrap inline code spans (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/834" title="GitHub Issue mkdocs/mkdocs #834">#834</a>).</li>
<li>Bugfix: Use absolute URLs in nav &amp; media links from error templates (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/77" title="GitHub Issue mkdocs/mkdocs #77">#77</a>).</li>
</ul>
<h2 id="version-0153-2016-02-18">Version 0.15.3 (2016-02-18)<a class="headerlink" href="#version-0153-2016-02-18" title="Permanent link"></a></h2>
<ul>
<li>Improve the error message the given theme can't be found.</li>
<li>Fix an issue with relative symlinks (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/639" title="GitHub Issue mkdocs/mkdocs #639">#639</a>)</li>
</ul>
<h2 id="version-0152-2016-02-08">Version 0.15.2 (2016-02-08)<a class="headerlink" href="#version-0152-2016-02-08" title="Permanent link"></a></h2>
<ul>
<li>Fix an incorrect warning that states external themes <a href="#add-support-for-installable-themes">will be removed from MkDocs</a>.</li>
</ul>
<h2 id="version-0151-2016-01-30">Version 0.15.1 (2016-01-30)<a class="headerlink" href="#version-0151-2016-01-30" title="Permanent link"></a></h2>
<ul>
<li>Lower the minimum supported Click version to 3.3 for package maintainers. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/763" title="GitHub Issue mkdocs/mkdocs #763">#763</a>)</li>
</ul>
<h2 id="version-0150-2016-01-21">Version 0.15.0 (2016-01-21)<a class="headerlink" href="#version-0150-2016-01-21" title="Permanent link"></a></h2>
<h3 id="major-additions-to-version-0150">Major Additions to Version 0.15.0<a class="headerlink" href="#major-additions-to-version-0150" title="Permanent link"></a></h3>
<h4 id="add-support-for-installable-themes">Add support for installable themes<a class="headerlink" href="#add-support-for-installable-themes" title="Permanent link"></a></h4>
<p>MkDocs now supports themes that are distributed via Python packages. With this
addition, the Bootstrap and Bootswatch themes have been moved to external git
repositories and python packages. See their individual documentation for more
details about these specific themes.</p>
<ul>
<li><a href="https://mkdocs.github.io/mkdocs-bootstrap/">MkDocs Bootstrap</a></li>
<li><a href="https://mkdocs.github.io/mkdocs-bootswatch/">MkDocs Bootswatch</a></li>
</ul>
<p>They will be included with MkDocs by default until a future release. After that
they will be installable with pip: <code>pip install mkdocs-bootstrap</code> and <code>pip
install mkdocs-bootswatch</code></p>
<p>See the documentation for <a href="../../user-guide/customizing-your-theme/">Customizing Your Theme</a> for more information about using
and customizing themes and <a href="../../dev-guide/themes/">Custom themes</a> for creating and distributing new
themes</p>
<h3 id="other-changes-and-additions-to-version-0150">Other Changes and Additions to Version 0.15.0<a class="headerlink" href="#other-changes-and-additions-to-version-0150" title="Permanent link"></a></h3>
<ul>
<li>Fix issues when using absolute links to Markdown files. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/628" title="GitHub Issue mkdocs/mkdocs #628">#628</a>)</li>
<li>Deprecate support of Python 2.6, pending removal in 1.0.0. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/165" title="GitHub Issue mkdocs/mkdocs #165">#165</a>)</li>
<li>Add official support for Python version 3.5.</li>
<li>Add support for <a href="../../user-guide/configuration/#site_description">site_description</a> and <a href="../../user-guide/configuration/#site_author">site_author</a> to the <a href="../../user-guide/choosing-your-theme/#readthedocs">ReadTheDocs</a> theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/631" title="GitHub Issue mkdocs/mkdocs #631">#631</a>)</li>
<li>Update FontAwesome to 4.5.0. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/789" title="GitHub Issue mkdocs/mkdocs #789">#789</a>)</li>
<li>Increase IE support with X-UA-Compatible. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/785" title="GitHub Issue mkdocs/mkdocs #785">#785</a>)</li>
<li>Added support for Python's <code>-m</code> flag. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/706" title="GitHub Issue mkdocs/mkdocs #706">#706</a>)</li>
<li>Bugfix: Ensure consistent ordering of auto-populated pages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/638" title="GitHub Issue mkdocs/mkdocs #638">#638</a>)</li>
<li>Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long for the page. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/204" title="GitHub Issue mkdocs/mkdocs #204">#204</a>)</li>
<li>Bugfix: Add all ancestors to the page attribute <code>ancestors</code> rather than just the initial one. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/693" title="GitHub Issue mkdocs/mkdocs #693">#693</a>)</li>
<li>Bugfix: Include HTML in the build output again. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/691" title="GitHub Issue mkdocs/mkdocs #691">#691</a>)</li>
<li>Bugfix: Provide filename to Read the Docs. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/721" title="GitHub Issue mkdocs/mkdocs #721">#721</a> and RTD<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/1480" title="GitHub Issue mkdocs/mkdocs #1480">#1480</a>)</li>
<li>Bugfix: Silence Click's unicode_literals warning. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/708" title="GitHub Issue mkdocs/mkdocs #708">#708</a>)</li>
</ul>
<h2 id="version-0140-2015-06-09">Version 0.14.0 (2015-06-09)<a class="headerlink" href="#version-0140-2015-06-09" title="Permanent link"></a></h2>
<ul>
<li>Improve Unicode handling by ensuring that all config strings are loaded as Unicode. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/592" title="GitHub Issue mkdocs/mkdocs #592">#592</a>)</li>
<li>Remove dependency on the six library. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/583" title="GitHub Issue mkdocs/mkdocs #583">#583</a>)</li>
<li>Remove dependency on the ghp-import library. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/547" title="GitHub Issue mkdocs/mkdocs #547">#547</a>)</li>
<li>Add <code>--quiet</code> and <code>--verbose</code> options to all sub-commands. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/579" title="GitHub Issue mkdocs/mkdocs #579">#579</a>)</li>
<li>Add short options (<code>-a</code>) to most command line options. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/579" title="GitHub Issue mkdocs/mkdocs #579">#579</a>)</li>
<li>Add copyright footer for readthedocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/568" title="GitHub Issue mkdocs/mkdocs #568">#568</a>)</li>
<li>If the requested port in <code>mkdocs serve</code> is already in use, don't show the user a full stack trace. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/596" title="GitHub Issue mkdocs/mkdocs #596">#596</a>)</li>
<li>Bugfix: Fix a JavaScript encoding problem when searching with spaces. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/586" title="GitHub Issue mkdocs/mkdocs #586">#586</a>)</li>
<li>Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/578" title="GitHub Issue mkdocs/mkdocs #578">#578</a>)</li>
<li>Bugfix: Handle (pass-through instead of dropping) HTML entities while parsing TOC. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/612" title="GitHub Issue mkdocs/mkdocs #612">#612</a>)</li>
<li>Bugfix: Default extra_templates to an empty list, don't automatically discover them. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/616" title="GitHub Issue mkdocs/mkdocs #616">#616</a>)</li>
</ul>
<h2 id="version-0133-2015-06-02">Version 0.13.3 (2015-06-02)<a class="headerlink" href="#version-0133-2015-06-02" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Reduce validation error to a warning if the site_dir is within the docs_dir as this shouldn't cause any problems with building but will inconvenience users building multiple times. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/580" title="GitHub Issue mkdocs/mkdocs #580">#580</a>)</li>
</ul>
<h2 id="version-0132-2015-05-30">Version 0.13.2 (2015-05-30)<a class="headerlink" href="#version-0132-2015-05-30" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Ensure all errors and warnings are logged before exiting. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/536" title="GitHub Issue mkdocs/mkdocs #536">#536</a>)</li>
<li>Bugfix: Fix compatibility issues with ReadTheDocs. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/554" title="GitHub Issue mkdocs/mkdocs #554">#554</a>)</li>
</ul>
<h2 id="version-0131-2015-05-27">Version 0.13.1 (2015-05-27)<a class="headerlink" href="#version-0131-2015-05-27" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Fix a problem with minimal configurations which only contain a list of paths in the pages config. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/562" title="GitHub Issue mkdocs/mkdocs #562">#562</a>)</li>
</ul>
<h2 id="version-0130-2015-05-26">Version 0.13.0 (2015-05-26)<a class="headerlink" href="#version-0130-2015-05-26" title="Permanent link"></a></h2>
<h3 id="deprecations-to-version-0130">Deprecations to Version 0.13.0<a class="headerlink" href="#deprecations-to-version-0130" title="Permanent link"></a></h3>
<h4 id="deprecate-the-json-command">Deprecate the JSON command<a class="headerlink" href="#deprecate-the-json-command" title="Permanent link"></a></h4>
<p>In this release the <code>mkdocs json</code> command has been marked as deprecated and
when used a deprecation warning will be shown. It will be removed in a <a href="https://github.com/mkdocs/mkdocs/pull/481">future
release</a> of MkDocs, version 1.0 at the latest. The <code>mkdocs json</code> command
provided a convenient way for users to output the documentation contents as
JSON files but with the additions of search to MkDocs this functionality is
duplicated.</p>
<p>A new index with all the contents from a MkDocs build is created in the
<a href="../../user-guide/configuration/#site_dir">site_dir</a>, so with the default value for the <code>site_dir</code> It can be found in
<code>site/mkdocs/search_index.json</code>.</p>
<p>This new file is created on every MkDocs build (with <code>mkdocs build</code>) and
no configuration is needed to enable it.</p>
<h4 id="change-the-pages-configuration">Change the pages configuration<a class="headerlink" href="#change-the-pages-configuration" title="Permanent link"></a></h4>
<p>Provide a <a href="../../user-guide/writing-your-docs/#configure-pages-and-navigation">new way</a> to define pages, and specifically nested pages, in the
mkdocs.yml file and deprecate the existing approach, support will be removed
with MkDocs 1.0.</p>
<h4 id="warn-users-about-the-removal-of-builtin-themes">Warn users about the removal of builtin themes<a class="headerlink" href="#warn-users-about-the-removal-of-builtin-themes" title="Permanent link"></a></h4>
<p>All themes other than mkdocs and readthedocs will be moved into external
packages in a future release of MkDocs. This will enable them to be more easily
supported and updates outside MkDocs releases.</p>
<h3 id="major-additions-to-version-0130">Major Additions to Version 0.13.0<a class="headerlink" href="#major-additions-to-version-0130" title="Permanent link"></a></h3>
<h4 id="search">Search<a class="headerlink" href="#search" title="Permanent link"></a></h4>
<p>Support for search has now been added to MkDocs. This is based on the
JavaScript library <a href="https://lunrjs.com/">lunr.js</a>. It has been added to both the <code>mkdocs</code> and
<code>readthedocs</code> themes. See the custom theme documentation on <a href="../../dev-guide/themes/#search-and-themes">supporting search</a>
for adding it to your own themes.</p>
<h4 id="new-command-line-interface">New Command Line Interface<a class="headerlink" href="#new-command-line-interface" title="Permanent link"></a></h4>
<p>The command line interface for MkDocs has been re-written with the Python
library <a href="https://click.palletsprojects.com/">Click</a>. This means that MkDocs now has an easier to use interface
with better help output.</p>
<p>This change is partially backwards incompatible as while undocumented it was
possible to pass any configuration option to the different commands. Now only
a small subset of the configuration options can be passed to the commands. To
see in full commands and available arguments use <code>mkdocs --help</code> and
<code>mkdocs build --help</code> to have them displayed.</p>
<h4 id="support-extra-html-and-xml-files">Support Extra HTML and XML files<a class="headerlink" href="#support-extra-html-and-xml-files" title="Permanent link"></a></h4>
<p>Like the <a href="../../user-guide/configuration/#extra_javascript">extra_javascript</a> and <a href="../../user-guide/configuration/#extra_css">extra_css</a> configuration options, a new
option named <a href="../../user-guide/configuration/#extra_templates">extra_templates</a> has been added. This will automatically be
populated with any <code>.html</code> or <code>.xml</code> files in the project docs directory.</p>
<p>Users can place static HTML and XML files and they will be copied over, or they
can also use Jinja2 syntax and take advantage of the <a href="../../dev-guide/themes/#global-context">global variables</a>.</p>
<p>By default MkDocs will use this approach to create a sitemap for the
documentation.</p>
<h3 id="other-changes-and-additions-to-version-0130">Other Changes and Additions to Version 0.13.0<a class="headerlink" href="#other-changes-and-additions-to-version-0130" title="Permanent link"></a></h3>
<ul>
<li>Add support for <a href="../../user-guide/configuration/#markdown_extensions">Markdown extension configuration options</a>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/435" title="GitHub Issue mkdocs/mkdocs #435">#435</a>)</li>
<li>MkDocs now ships Python <a href="https://pythonwheels.com/">wheels</a>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/486" title="GitHub Issue mkdocs/mkdocs #486">#486</a>)</li>
<li>Only include the build date and MkDocs version on the homepage. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/490" title="GitHub Issue mkdocs/mkdocs #490">#490</a>)</li>
<li>Generate sitemaps for documentation builds. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/436" title="GitHub Issue mkdocs/mkdocs #436">#436</a>)</li>
<li>Add a clearer way to define nested pages in the configuration. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/482" title="GitHub Issue mkdocs/mkdocs #482">#482</a>)</li>
<li>Add an <a href="../../user-guide/configuration/#extra">extra config</a> option for passing arbitrary variables to the template. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/510" title="GitHub Issue mkdocs/mkdocs #510">#510</a>)</li>
<li>Add <code>--no-livereload</code> to <code>mkdocs serve</code> for a simpler development server. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/511" title="GitHub Issue mkdocs/mkdocs #511">#511</a>)</li>
<li>Add copyright display support to all themes (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/549" title="GitHub Issue mkdocs/mkdocs #549">#549</a>)</li>
<li>Add support for custom commit messages in a <code>mkdocs gh-deploy</code> (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/516" title="GitHub Issue mkdocs/mkdocs #516">#516</a>)</li>
<li>Bugfix: Fix linking to media within the same directory as a markdown file called index.md (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/535" title="GitHub Issue mkdocs/mkdocs #535">#535</a>)</li>
<li>Bugfix: Fix errors with Unicode filenames (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/542" title="GitHub Issue mkdocs/mkdocs #542">#542</a>).</li>
</ul>
<h2 id="version-0122-2015-04-22">Version 0.12.2 (2015-04-22)<a class="headerlink" href="#version-0122-2015-04-22" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Fix a regression where there would be an error if some child titles were missing but others were provided in the pages config. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/464" title="GitHub Issue mkdocs/mkdocs #464">#464</a>)</li>
</ul>
<h2 id="version-0121-2015-04-14">Version 0.12.1 (2015-04-14)<a class="headerlink" href="#version-0121-2015-04-14" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Fixed a CSS bug in the table of contents on some browsers where the bottom item was not clickable.</li>
</ul>
<h2 id="version-0120-2015-04-14">Version 0.12.0 (2015-04-14)<a class="headerlink" href="#version-0120-2015-04-14" title="Permanent link"></a></h2>
<ul>
<li>Display the current MkDocs version in the CLI output. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/258" title="GitHub Issue mkdocs/mkdocs #258">#258</a>)</li>
<li>Check for CNAME file when using gh-deploy. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/285" title="GitHub Issue mkdocs/mkdocs #285">#285</a>)</li>
<li>Add the homepage back to the navigation on all themes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/271" title="GitHub Issue mkdocs/mkdocs #271">#271</a>)</li>
<li>Add a strict more for local link checking. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/279" title="GitHub Issue mkdocs/mkdocs #279">#279</a>)</li>
<li>Add Google analytics support to all themes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/333" title="GitHub Issue mkdocs/mkdocs #333">#333</a>)</li>
<li>Add build date and MkDocs version to the ReadTheDocs and MkDocs theme outputs. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/382" title="GitHub Issue mkdocs/mkdocs #382">#382</a>)</li>
<li>Standardize highlighting across all themes and add missing languages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/387" title="GitHub Issue mkdocs/mkdocs #387">#387</a>)</li>
<li>Add a verbose flag. (-v) to show more details about what the build. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/147" title="GitHub Issue mkdocs/mkdocs #147">#147</a>)</li>
<li>Add the option to specify a remote branch when deploying to GitHub. This enables deploying to GitHub pages on personal and repo sites. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/354" title="GitHub Issue mkdocs/mkdocs #354">#354</a>)</li>
<li>Add favicon support to the ReadTheDocs theme HTML. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/422" title="GitHub Issue mkdocs/mkdocs #422">#422</a>)</li>
<li>Automatically refresh the browser when files are edited. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/163" title="GitHub Issue mkdocs/mkdocs #163">#163</a>)</li>
<li>Bugfix: Never re-write URLs in code blocks. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/240" title="GitHub Issue mkdocs/mkdocs #240">#240</a>)</li>
<li>Bugfix: Don't copy dotfiles when copying media from the <code>docs_dir</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/254" title="GitHub Issue mkdocs/mkdocs #254">#254</a>)</li>
<li>Bugfix: Fix the rendering of tables in the ReadTheDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/106" title="GitHub Issue mkdocs/mkdocs #106">#106</a>)</li>
<li>Bugfix: Add padding to the bottom of all bootstrap themes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/255" title="GitHub Issue mkdocs/mkdocs #255">#255</a>)</li>
<li>Bugfix: Fix issues with nested Markdown pages and the automatic pages configuration. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/276" title="GitHub Issue mkdocs/mkdocs #276">#276</a>)</li>
<li>Bugfix: Fix a URL parsing error with GitHub enterprise. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/284" title="GitHub Issue mkdocs/mkdocs #284">#284</a>)</li>
<li>Bugfix: Don't error if the mkdocs.yml is completely empty. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/288" title="GitHub Issue mkdocs/mkdocs #288">#288</a>)</li>
<li>Bugfix: Fix a number of problems with relative URLs and Markdown files. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/292" title="GitHub Issue mkdocs/mkdocs #292">#292</a>)</li>
<li>Bugfix: Don't stop the build if a page can't be found, continue with other pages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/150" title="GitHub Issue mkdocs/mkdocs #150">#150</a>)</li>
<li>Bugfix: Remove the site_name from the page title, this needs to be added manually. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/299" title="GitHub Issue mkdocs/mkdocs #299">#299</a>)</li>
<li>Bugfix: Fix an issue with table of contents cutting off Markdown. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/294" title="GitHub Issue mkdocs/mkdocs #294">#294</a>)</li>
<li>Bugfix: Fix hostname for BitBucket. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/339" title="GitHub Issue mkdocs/mkdocs #339">#339</a>)</li>
<li>Bugfix: Ensure all links end with a slash. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/344" title="GitHub Issue mkdocs/mkdocs #344">#344</a>)</li>
<li>Bugfix: Fix repo links in the readthedocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/365" title="GitHub Issue mkdocs/mkdocs #365">#365</a>)</li>
<li>Bugfix: Include jQuery locally to avoid problems using MkDocs offline. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/143" title="GitHub Issue mkdocs/mkdocs #143">#143</a>)</li>
<li>Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/384" title="GitHub Issue mkdocs/mkdocs #384">#384</a>)</li>
<li>Bugfix: Remove inline CSS in the ReadTheDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/393" title="GitHub Issue mkdocs/mkdocs #393">#393</a>)</li>
<li>Bugfix: Fix problems with the child titles due to the order the pages config was processed. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/395" title="GitHub Issue mkdocs/mkdocs #395">#395</a>)</li>
<li>Bugfix: Don't error during live reload when the theme doesn't exist. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/373" title="GitHub Issue mkdocs/mkdocs #373">#373</a>)</li>
<li>Bugfix: Fix problems with the Meta extension when it may not exist. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/398" title="GitHub Issue mkdocs/mkdocs #398">#398</a>)</li>
<li>Bugfix: Wrap long inline code otherwise they will run off the screen. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/313" title="GitHub Issue mkdocs/mkdocs #313">#313</a>)</li>
<li>Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to fix problems with titles containing code. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/367" title="GitHub Issue mkdocs/mkdocs #367">#367</a>)</li>
<li>Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden under the navigation. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/7" title="GitHub Issue mkdocs/mkdocs #7">#7</a>)</li>
<li>Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/295" title="GitHub Issue mkdocs/mkdocs #295">#295</a>)</li>
<li>Bugfix: Fix an error when passing in a specific config file with <code>mkdocs serve</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/341" title="GitHub Issue mkdocs/mkdocs #341">#341</a>)</li>
<li>Bugfix: Don't overwrite index.md files with the <code>mkdocs new</code> command. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/412" title="GitHub Issue mkdocs/mkdocs #412">#412</a>)</li>
<li>Bugfix: Remove bold and italic from code in the ReadTheDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/411" title="GitHub Issue mkdocs/mkdocs #411">#411</a>)</li>
<li>Bugfix: Display images inline in the MkDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/415" title="GitHub Issue mkdocs/mkdocs #415">#415</a>)</li>
<li>Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/319" title="GitHub Issue mkdocs/mkdocs #319">#319</a>)</li>
<li>Bugfix: Don't delete hidden files when using <code>mkdocs build --clean</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/346" title="GitHub Issue mkdocs/mkdocs #346">#346</a>)</li>
<li>Bugfix: Don't block newer versions of Python-markdown on Python &gt;= 2.7. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/376" title="GitHub Issue mkdocs/mkdocs #376">#376</a>)</li>
<li>Bugfix: Fix encoding issues when opening files across platforms. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/428" title="GitHub Issue mkdocs/mkdocs #428">#428</a>)</li>
</ul>
<h2 id="version-0111-2014-11-20">Version 0.11.1 (2014-11-20)<a class="headerlink" href="#version-0111-2014-11-20" title="Permanent link"></a></h2>
<ul>
<li>Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/233" title="GitHub Issue mkdocs/mkdocs #233">#233</a>)</li>
</ul>
<h2 id="version-0110-2014-11-18">Version 0.11.0 (2014-11-18)<a class="headerlink" href="#version-0110-2014-11-18" title="Permanent link"></a></h2>
<ul>
<li>Render 404.html files if they exist for the current theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/194" title="GitHub Issue mkdocs/mkdocs #194">#194</a>)</li>
<li>Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs and ReadTheDocs themes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/225" title="GitHub Issue mkdocs/mkdocs #225">#225</a>)</li>
<li>Bugfix: Fix an issue with the google_analytics code. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/219" title="GitHub Issue mkdocs/mkdocs #219">#219</a>)</li>
<li>Bugfix: Remove <code>__pycache__</code> from the package tar. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/196" title="GitHub Issue mkdocs/mkdocs #196">#196</a>)</li>
<li>Bugfix: Fix markdown links that go to an anchor on the current page. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/197" title="GitHub Issue mkdocs/mkdocs #197">#197</a>)</li>
<li>Bugfix: Don't add <code>prettyprint well</code> CSS classes to all HTML, only add it in the MkDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/183" title="GitHub Issue mkdocs/mkdocs #183">#183</a>)</li>
<li>Bugfix: Display section titles in the ReadTheDocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/175" title="GitHub Issue mkdocs/mkdocs #175">#175</a>)</li>
<li>Bugfix: Use the polling observer in watchdog so rebuilding works on filesystems without inotify. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/184" title="GitHub Issue mkdocs/mkdocs #184">#184</a>)</li>
<li>Bugfix: Improve error output for common configuration related errors. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/176" title="GitHub Issue mkdocs/mkdocs #176">#176</a>)</li>
</ul>
<h2 id="version-0100-2014-10-29">Version 0.10.0 (2014-10-29)<a class="headerlink" href="#version-0100-2014-10-29" title="Permanent link"></a></h2>
<ul>
<li>Added support for Python 3.3 and 3.4. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/103" title="GitHub Issue mkdocs/mkdocs #103">#103</a>)</li>
<li>Configurable Python-Markdown extensions with the config setting <code>markdown_extensions</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/74" title="GitHub Issue mkdocs/mkdocs #74">#74</a>)</li>
<li>Added <code>mkdocs json</code> command to output your rendered documentation as json files. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/128" title="GitHub Issue mkdocs/mkdocs #128">#128</a>)</li>
<li>Added <code>--clean</code> switch to <code>build</code>, <code>json</code> and <code>gh-deploy</code> commands to remove stale files from the output directory. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/157" title="GitHub Issue mkdocs/mkdocs #157">#157</a>)</li>
<li>Support multiple theme directories to allow replacement of individual templates rather than copying the full theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/129" title="GitHub Issue mkdocs/mkdocs #129">#129</a>)</li>
<li>Bugfix: Fix <code>&lt;ul&gt;</code> rendering in readthedocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/171" title="GitHub Issue mkdocs/mkdocs #171">#171</a>)</li>
<li>Bugfix: Improve the readthedocs theme on smaller displays. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/168" title="GitHub Issue mkdocs/mkdocs #168">#168</a>)</li>
<li>Bugfix: Relaxed required python package versions to avoid clashes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/104" title="GitHub Issue mkdocs/mkdocs #104">#104</a>)</li>
<li>Bugfix: Fix issue rendering the table of contents with some configs. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/146" title="GitHub Issue mkdocs/mkdocs #146">#146</a>)</li>
<li>Bugfix: Fix path for embedded images in sub pages. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/138" title="GitHub Issue mkdocs/mkdocs #138">#138</a>)</li>
<li>Bugfix: Fix <code>use_directory_urls</code> config behavior. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/63" title="GitHub Issue mkdocs/mkdocs #63">#63</a>)</li>
<li>Bugfix: Support <code>extra_javascript</code> and <code>extra_css</code> in all themes. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/90" title="GitHub Issue mkdocs/mkdocs #90">#90</a>)</li>
<li>Bugfix: Fix path-handling under Windows. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/121" title="GitHub Issue mkdocs/mkdocs #121">#121</a>)</li>
<li>Bugfix: Fix the menu generation in the readthedocs theme. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/110" title="GitHub Issue mkdocs/mkdocs #110">#110</a>)</li>
<li>Bugfix: Fix the mkdocs command creation under Windows. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/122" title="GitHub Issue mkdocs/mkdocs #122">#122</a>)</li>
<li>Bugfix: Correctly handle external <code>extra_javascript</code> and <code>extra_css</code>. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/92" title="GitHub Issue mkdocs/mkdocs #92">#92</a>)</li>
<li>Bugfix: Fixed favicon support. (<a class="gh-link gh-issue" href="https://github.com/mkdocs/mkdocs/issues/87" title="GitHub Issue mkdocs/mkdocs #87">#87</a>)</li>
</ul></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Copyright &copy; 2014 <a href="https://twitter.com/starletdreaming">Tom Christie</a>, Maintained by the <a href="/about/release-notes/#maintenance-team">MkDocs Team</a>.</p>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="../../js/jquery-3.6.0.min.js"></script>
<script src="../../js/bootstrap.min.js"></script>
<script>
var base_url = "../..",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="../../js/base.js"></script>
<script src="../../search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink