mirror of
https://github.com/mkdocs/mkdocs.git
synced 2026-03-27 18:08:31 +07:00
410 lines
23 KiB
HTML
410 lines
23 KiB
HTML
<!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/contributing/">
|
|
<link rel="shortcut icon" href="../../img/favicon.ico">
|
|
<title>Contributing - 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="../release-notes/" class="dropdown-item">Release Notes</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="./" class="dropdown-item active">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="../release-notes/" class="nav-link">
|
|
<i class="fa fa-arrow-left"></i> Previous
|
|
</a>
|
|
</li>
|
|
<li class="nav-item">
|
|
<a rel="next" href="../license/" 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/contributing.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="#contributing-to-mkdocs" class="nav-link">Contributing to MkDocs</a>
|
|
<ul class="nav flex-column">
|
|
<li class="nav-item" data-level="2"><a href="#reporting-an-issue" class="nav-link">Reporting an Issue</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#trying-out-the-development-version" class="nav-link">Trying out the Development Version</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#installing-for-development" class="nav-link">Installing for Development</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#installing-hatch" class="nav-link">Installing Hatch</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#running-all-checks" class="nav-link">Running all checks</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#translating-themes" class="nav-link">Translating themes</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#submitting-pull-requests" class="nav-link">Submitting Pull Requests</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
<li class="nav-item" data-level="2"><a href="#code-of-conduct" class="nav-link">Code of Conduct</a>
|
|
<ul class="nav flex-column">
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div></div>
|
|
<div class="col-md-9" role="main">
|
|
|
|
<h1 id="contributing-to-mkdocs">Contributing to MkDocs<a class="headerlink" href="#contributing-to-mkdocs" title="Permanent link"></a></h1>
|
|
<p>An introduction to contributing to the MkDocs project.</p>
|
|
<p>The MkDocs project welcomes contributions from developers and
|
|
users in the open source community. Contributions can be made in a number of
|
|
ways, a few examples are:</p>
|
|
<ul>
|
|
<li>Code patches via pull requests</li>
|
|
<li>Documentation improvements</li>
|
|
<li>Bug reports and patch reviews</li>
|
|
</ul>
|
|
<p>For information about available communication channels please refer to the
|
|
<a href="https://github.com/mkdocs/mkdocs#readme">README</a> file in our
|
|
GitHub repository.</p>
|
|
<h2 id="reporting-an-issue">Reporting an Issue<a class="headerlink" href="#reporting-an-issue" title="Permanent link"></a></h2>
|
|
<p>Please include as much detail as you can. Let us know your platform and MkDocs
|
|
version. If the problem is visual (for example a theme or design issue), please
|
|
add a screenshot. If you get an error, please include the full error message and
|
|
traceback.</p>
|
|
<p>It is particularly helpful if an issue report touches on all of these aspects:</p>
|
|
<ol>
|
|
<li>
|
|
<p>What are you trying to achieve?</p>
|
|
</li>
|
|
<li>
|
|
<p>What is your <code>mkdocs.yml</code> configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example.</p>
|
|
</li>
|
|
<li>
|
|
<p>What did you expect to happen when applying this setup?</p>
|
|
</li>
|
|
<li>
|
|
<p>What happened instead and how didn't it match your expectation?</p>
|
|
</li>
|
|
</ol>
|
|
<h2 id="trying-out-the-development-version">Trying out the Development Version<a class="headerlink" href="#trying-out-the-development-version" title="Permanent link"></a></h2>
|
|
<p>If you want to just install and try out the latest development version of
|
|
MkDocs (in case it already contains a fix for your issue),
|
|
you can do so with the following command. This can be useful if you
|
|
want to provide feedback for a new feature or want to confirm if a bug you
|
|
have encountered is fixed in the git master. It is <strong>strongly</strong> recommended
|
|
that you do this within a <a href="https://virtualenv.pypa.io/en/latest/user_guide.html">virtualenv</a>.</p>
|
|
<pre class="highlight"><code class="language-bash">pip install git+https://github.com/mkdocs/mkdocs.git</code></pre>
|
|
<h2 id="installing-for-development">Installing for Development<a class="headerlink" href="#installing-for-development" title="Permanent link"></a></h2>
|
|
<p>Note that for development you can just use <a href="https://hatch.pypa.io/">Hatch</a> directly as described below. If you wish to install a local clone of MkDocs anyway, you can run <code>pip install --editable .</code>. It is <strong>strongly</strong> recommended that you do this within a <a href="https://virtualenv.pypa.io/en/latest/user_guide.html">virtualenv</a>.</p>
|
|
<h2 id="installing-hatch">Installing Hatch<a class="headerlink" href="#installing-hatch" title="Permanent link"></a></h2>
|
|
<p>The main tool that is used for development is <a href="https://hatch.pypa.io/">Hatch</a>. It manages dependencies (in a virtualenv that is created on the fly) and is also the command runner.</p>
|
|
<p>So first, <a href="https://hatch.pypa.io/latest/install/#pip">install it</a>. Ideally in an isolated way with <strong><code>pipx install hatch</code></strong> (after [installing <code>pipx</code>]), or just <code>pip install hatch</code> as a more well-known way.</p>
|
|
<h2 id="running-all-checks">Running all checks<a class="headerlink" href="#running-all-checks" title="Permanent link"></a></h2>
|
|
<p>To run <strong>all</strong> checks that are required for MkDocs, just run the following command in the cloned MkDocs repository:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run all</code></pre>
|
|
<p><strong>This will encompass all of the checks mentioned below.</strong></p>
|
|
<p>All checks need to pass.</p>
|
|
<h3 id="running-tests">Running tests<a class="headerlink" href="#running-tests" title="Permanent link"></a></h3>
|
|
<p>To run the test suite for MkDocs, run the following commands:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run test:test
|
|
hatch run integration:test</code></pre>
|
|
<p>It will attempt to run the tests against all of the Python versions we
|
|
support. So don't be concerned if you are missing some. The rest
|
|
will be verified by <a href="https://docs.github.com/actions">GitHub Actions</a> when you submit a pull request.</p>
|
|
<h3 id="python-code-style">Python code style<a class="headerlink" href="#python-code-style" title="Permanent link"></a></h3>
|
|
<p>Python code within MkDocs' code base is formatted using <a href="https://black.readthedocs.io/">Black</a> and <a href="https://pycqa.github.io/isort/">Isort</a> and lint-checked using <a href="https://docs.astral.sh/ruff/">Ruff</a>, all of which are configured in <code>pyproject.toml</code>.</p>
|
|
<p>You can automatically check and format the code according to these tools with the following command:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run style:fix</code></pre>
|
|
<p>The code is also type-checked using <a href="https://mypy-lang.org/">mypy</a> - also configured in <code>pyproject.toml</code>, it can be run like this:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run types:check</code></pre>
|
|
<h3 id="other-style-checks">Other style checks<a class="headerlink" href="#other-style-checks" title="Permanent link"></a></h3>
|
|
<p>There are several other checks, such as spelling and JS style. To run all of them, use this command:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run lint:check</code></pre>
|
|
<h3 id="documentation-of-mkdocs-itself">Documentation of MkDocs itself<a class="headerlink" href="#documentation-of-mkdocs-itself" title="Permanent link"></a></h3>
|
|
<p>After making edits to files under the <code>docs/</code> dir, you can preview the site locally using the following command:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run docs:serve</code></pre>
|
|
<p>Note that any 'WARNING' should be resolved before submitting a contribution.</p>
|
|
<p>Documentation files are also checked by markdownlint, so you should run this as well:</p>
|
|
<pre class="highlight"><code class="language-bash">hatch run lint:check</code></pre>
|
|
<p>If you add a new plugin to mkdocs.yml, you don't need to add it to any "requirements" file, because that is managed automatically.</p>
|
|
<div class="admonition info">
|
|
<p class="admonition-title">Info</p>
|
|
<p>If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with <code>.venv</code> being the virtualenv directory):</p>
|
|
<pre class="highlight"><code class="language-bash">.venv/bin/pip install -r requirements/requirements-docs.txt # Exact versions of dependencies.
|
|
.venv/bin/pip install -r $(mkdocs get-deps) # Latest versions of all dependencies.</code></pre>
|
|
</div>
|
|
<h2 id="translating-themes">Translating themes<a class="headerlink" href="#translating-themes" title="Permanent link"></a></h2>
|
|
<p>To localize a theme to your favorite language, follow the guide on <a href="https://www.mkdocs.org/dev-guide/translations/">Translating Themes</a>. We welcome translation pull requests!</p>
|
|
<h2 id="submitting-pull-requests">Submitting Pull Requests<a class="headerlink" href="#submitting-pull-requests" title="Permanent link"></a></h2>
|
|
<p>If you're considering a large code contribution to MkDocs, please prefer to
|
|
open an issue first to get early feedback on the idea.</p>
|
|
<p>Once you think the code is ready to be reviewed, push
|
|
it to your fork and send a pull request. For a change to be accepted it will
|
|
most likely need to have tests and documentation if it is a new feature.</p>
|
|
<p>When working with a pull request branch:<br />
|
|
Unless otherwise agreed, prefer <code>commit</code> over <code>amend</code>, and <code>merge</code> over <code>rebase</code>. Avoid force-pushes, otherwise review history is much harder to navigate. For the end result, the "unclean" history is fine because most pull requests are squash-merged on GitHub.</p>
|
|
<p>Do <em>not</em> add to <em>release-notes.md</em>, this will be written later.</p>
|
|
<h3 id="submitting-changes-to-the-builtin-themes">Submitting changes to the builtin themes<a class="headerlink" href="#submitting-changes-to-the-builtin-themes" title="Permanent link"></a></h3>
|
|
<p>When installed with <code>i18n</code> support (<code>pip install 'mkdocs[i18n]'</code>), MkDocs allows
|
|
themes to support being translated into various languages (referred to as
|
|
locales) if they respect <a href="https://jinja.palletsprojects.com/en/latest/extensions/#i18n-extension">Jinja's i18n extension</a> by wrapping text placeholders
|
|
with <code>{% trans %}</code> and <code>{% endtrans %}</code> tags.</p>
|
|
<p>Each time a translatable text placeholder is added, removed or changed in a
|
|
theme template, the theme's Portable Object Template (<code>pot</code>) file needs to be
|
|
updated by running the <code>extract_messages</code> command. To update the
|
|
<code>pot</code> file for both built-in themes, run these commands:</p>
|
|
<pre class="highlight"><code class="language-bash">pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs
|
|
pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs</code></pre>
|
|
<p>The updated <code>pot</code> file should be included in a PR with the updated template.
|
|
The updated <code>pot</code> file will allow translation contributors to propose the
|
|
translations needed for their preferred language. See the guide on <a href="https://www.mkdocs.org/dev-guide/translations/">Translating
|
|
Themes</a> for details.</p>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>
|
|
Contributors are not expected to provide translations with their changes to
|
|
a theme's templates. However, they are expected to include an updated <code>pot</code>
|
|
file so that everything is ready for translators to do their job.</p>
|
|
</div>
|
|
<h2 id="code-of-conduct">Code of Conduct<a class="headerlink" href="#code-of-conduct" title="Permanent link"></a></h2>
|
|
<p>Everyone interacting in the MkDocs project's codebases, issue trackers, chat
|
|
rooms, and mailing lists is expected to follow the <a href="https://www.pypa.io/en/latest/code-of-conduct/">PyPA Code of Conduct</a>.</p></div>
|
|
</div>
|
|
</div>
|
|
|
|
<footer class="col-md-12">
|
|
<hr>
|
|
<p>Copyright © 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">×</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">×</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>
|