diff --git a/.csslintrc b/.csslintrc deleted file mode 100644 index 8877d0eac5..0000000000 --- a/.csslintrc +++ /dev/null @@ -1,42 +0,0 @@ ---exclude-list = mkdocs/themes/mkdocs/css/bootstrap.min.css, - mkdocs/themes/mkdocs/css/font-awesome.min.css, - mkdocs/themes/mkdocs/css/highlight.css, - mkdocs/themes/readthedocs/css/theme.css ---errors = known-properties, - box-sizing, - outline-none, - bulletproof-font-face, - compatible-vendor-prefixes, - errors, - duplicate-background-images, - duplicate-properties, - empty-rules, - selector-max-approaching, - gradients, - floats, - font-faces, - font-sizes, - shorthand, - import, - import-ie-limit, - text-indent, - rules-count, - regex-selectors, - selector-max, - selector-newline, - star-property-hack, - underscore-property-hack, - universal-selector, - unqualified-attributes, - vendor-prefix, - zero-units, - overqualified-elements, - unique-headings, - qualified-headings, - ids, - display-property-grouping, - fallback-colors, - box-model, - important, - adjoining-classes ---ignore = order-alphabetical diff --git a/.flake8 b/.flake8 deleted file mode 100644 index 564a578cf1..0000000000 --- a/.flake8 +++ /dev/null @@ -1,3 +0,0 @@ -[flake8] -max-line-length = 119 -extend-ignore = E203 diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml new file mode 100644 index 0000000000..6bcd262533 --- /dev/null +++ b/.github/workflows/autofix.yml @@ -0,0 +1,23 @@ +name: Auto-fix +on: + push: + pull_request: +jobs: + style: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install Python dependencies + run: | + python -m pip install --upgrade hatch + - name: Fix code style + run: hatch run style:fix --fix-only + - name: Check if any edits are necessary + run: git diff --color --exit-code + - name: Apply automatic fixes using pre-commit-ci-lite + if: failure() && github.event_name == 'pull_request' + uses: pre-commit-ci/lite-action@v1.0.1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7c4321d723..bf93e0d2e9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,38 +1,36 @@ name: CI - -on: [push, pull_request] - +on: + push: + pull_request: + schedule: + - cron: '0 6 * * 6' jobs: test: strategy: fail-fast: false matrix: - python-version: [3.7, 3.8, 3.9, '3.10', pypy-3.7-v7.x] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', 'pypy-3.9-v7.x'] os: [ubuntu-latest, windows-latest, macos-latest] include: - - python-version: 3.7 - py: py37 - - python-version: 3.8 - py: py38 - - python-version: 3.9 - py: py39 - - python-version: '3.10' - py: py310 - - python-version: pypy-3.7-v7.x + - python-version: pypy-3.9-v7.x py: pypy3 # Just to slim down the test matrix: exclude: - - python-version: 3.8 + - python-version: '3.9' os: macos-latest - - python-version: 3.8 + - python-version: '3.9' os: windows-latest - - python-version: 3.9 + - python-version: '3.10' os: ubuntu-latest + - python-version: '3.11' + os: macos-latest + - python-version: '3.11' + os: windows-latest runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Setup Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - name: Install dependencies @@ -40,39 +38,36 @@ jobs: python -m pip install --upgrade hatch - name: Run tests run: | - hatch run +py=${{ matrix.py }} +type= test:with-coverage + hatch run +py=${{ matrix.py || matrix.python-version }} test:with-coverage - name: Run integration tests run: | - hatch run +py=${{ matrix.py }} +type= integration:test + hatch run +py=${{ matrix.py || matrix.python-version }} integration:test shell: bash - name: Upload Codecov Results if: success() - uses: codecov/codecov-action@v1 + uses: codecov/codecov-action@v3 with: file: ./coverage.xml flags: unittests - name: ${{ matrix.os }}/${{ matrix.py }} + name: ${{ matrix.os }}/${{ matrix.python-version }} fail_ci_if_error: false lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: - python-version: '3.10' + python-version: '3.11' - name: Install Python dependencies run: | python -m pip install --upgrade hatch - name: Setup Node - uses: actions/setup-node@v1 + uses: actions/setup-node@v4 with: - node-version: 16 - - name: Check with black + isort - if: always() - run: hatch run style:format && git diff --exit-code - - name: Check with flake8 + node-version: 20 + - name: Check with ruff if: always() run: hatch run style:lint - name: Check with mypy @@ -84,9 +79,6 @@ jobs: - name: Check JS style if: always() run: hatch run lint:js - - name: Check CSS style - if: always() - run: hatch run lint:css - name: Check spelling if: always() run: hatch run lint:spelling @@ -94,17 +86,15 @@ jobs: package: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: - python-version: 3.9 - - name: Install Hatch - run: | - python -m pip install -U hatch + python-version: '3.11' + - name: Install dependencies + run: pip install -U build - name: Build package - run: | - hatch build + run: python -m build - name: Check packaged files shell: bash -e -x {0} run: | diff --git a/.github/workflows/deploy-release.yml b/.github/workflows/deploy-release.yml index ee1dcc5a74..7db41a5c50 100644 --- a/.github/workflows/deploy-release.yml +++ b/.github/workflows/deploy-release.yml @@ -1,28 +1,22 @@ -name: deploy-release - +name: Deploy release on: push: tags: - - '*' - + - '*' jobs: pypi: + permissions: + id-token: write runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: - python-version: 3.9 - - name: Install Hatch - run: | - python -m pip install -U hatch + python-version: '3.11' + - name: Install dependencies + run: pip install -U build - name: Build package - run: | - hatch build - - name: Publish - run: | - hatch publish - env: - HATCH_INDEX_USER: __token__ - HATCH_INDEX_AUTH: ${{ secrets.PYPI_PASSWORD }} + run: python -m build + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..16d74e520a --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,20 @@ +name: Docs +on: + push: + pull_request: + schedule: + - cron: '0 6 * * 6' +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Download source + uses: actions/checkout@v4 + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install dependencies + run: pip install --no-deps -r requirements/requirements-docs.txt + - name: Build site + run: mkdocs build --strict diff --git a/.jshintignore b/.jshintignore index 72344b0aa5..8b54bdfa26 100644 --- a/.jshintignore +++ b/.jshintignore @@ -1,6 +1,6 @@ mkdocs/themes/**/js/jquery-**.min.js mkdocs/themes/mkdocs/js/highlight.pack.js -mkdocs/themes/mkdocs/js/bootstrap.min.js +mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js mkdocs/themes/mkdocs/js/modernizr-**.min.js mkdocs/themes/readthedocs/js/theme.js mkdocs/themes/readthedocs/js/html5shiv.min.js diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000000..f6df6137a5 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,147 @@ +default: false + +# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md001.md +MD001: true + +# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md003.md +MD003: + style: "consistent" + +# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md004.md +MD004: + style: "consistent" + +# MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md005.md +MD005: true + +# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md007.md +MD007: + indent: 4 + +# MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md009.md +MD009: true + +# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md010.md +MD010: true + +# MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md011.md +MD011: true + +# MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md012.md +MD012: true + +# MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md014.md +MD014: true + +# MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md018.md +MD018: true + +# MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md019.md +MD019: true + +# MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md020.md +MD020: true + +# MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md021.md +MD021: true + +# MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md022.md +MD022: true + +# MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md023.md +MD023: true + +# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md024.md +MD024: + siblings_only: true + +# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md025.md +MD025: true + +# MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md026.md +MD026: true + +# MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md027.md +MD027: true + +# MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md028.md +MD028: true + +# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md029.md +MD029: + style: "ordered" + +# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md030.md +MD030: + ul_single: 1 + ol_single: 1 + ul_multi: 3 + ol_multi: 2 + +# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md031.md +MD031: true + +# MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md032.md +MD032: true + +# MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md034.md +MD034: true + +# MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md035.md +MD035: true + +# MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md036.md +MD036: true + +# MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md037.md +MD037: true + +# MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md038.md +MD038: true + +# MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md039.md +MD039: true + +# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md040.md +MD040: true + +# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md042.md +MD042: true + +# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md045.md +MD045: true + +# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md046.md +MD046: + style: "fenced" + +# MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md047.md +MD047: true + +# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md048.md +MD048: + style: "backtick" + +# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md049.md +MD049: + style: "asterisk" + +# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md050.md +MD050: + style: "consistent" + +# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md051.md +MD051: true + +# MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md053.md +MD053: true + +# MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md054.md +MD054: true + +# MD055/table-pipe-style : Table pipe style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md055.md +MD055: + style: "no_leading_or_trailing" + +# MD056/table-column-count : Table column count : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md056.md +MD056: true diff --git a/.markdownlintrc b/.markdownlintrc deleted file mode 100644 index aa9fc26c74..0000000000 --- a/.markdownlintrc +++ /dev/null @@ -1,24 +0,0 @@ -{ - // Enable all markdownlint rules - "default": true, - - // Disable line length check - "MD013": false, - - // Set Ordered list item prefix to "ordered" (use 1. 2. 3. not 1. 1. 1.) - "MD029": { "style": "ordered" }, - - "MD030": { "ul_multi": 3, "ol_multi": 2 }, - - // Set list indent level to 4 which Python-Markdown requires - "MD007": { "indent": 4 }, - - // Code block style - "MD046": { "style": "fenced" }, - - // Multiple headings with the same title - "MD024": { "siblings_only": true }, - - // Allow inline HTML - "MD033": false -} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 527abf61f6..510ef6f6be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,192 @@ # Contributing to MkDocs -See the contributing guide in the documentation for an -introduction to contributing to MkDocs. +An introduction to contributing to the MkDocs project. - +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: + +- Code patches via pull requests +- Documentation improvements +- Bug reports and patch reviews + +For information about available communication channels please refer to the +[README](https://github.com/mkdocs/mkdocs#readme) file in our +GitHub repository. + +## Reporting an Issue + +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. + +It is particularly helpful if an issue report touches on all of these aspects: + +1. What are you trying to achieve? + +2. What is your `mkdocs.yml` configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example. + +3. What did you expect to happen when applying this setup? + +4. What happened instead and how didn't it match your expectation? + +## Trying out the Development Version + +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 **strongly** recommended +that you do this within a [virtualenv]. + +```bash +pip install git+https://github.com/mkdocs/mkdocs.git +``` + +## Installing for Development + +Note that for development you can just use [Hatch] directly as described below. If you wish to install a local clone of MkDocs anyway, you can run `pip install --editable .`. It is **strongly** recommended that you do this within a [virtualenv]. + +## Installing Hatch + +The main tool that is used for development is [Hatch]. It manages dependencies (in a virtualenv that is created on the fly) and is also the command runner. + +So first, [install it][install Hatch]. Ideally in an isolated way with **`pipx install hatch`** (after [installing `pipx`]), or just `pip install hatch` as a more well-known way. + +## Running all checks + +To run **all** checks that are required for MkDocs, just run the following command in the cloned MkDocs repository: + +```bash +hatch run all +``` + +**This will encompass all of the checks mentioned below.** + +All checks need to pass. + +### Running tests + +To run the test suite for MkDocs, run the following commands: + +```bash +hatch run test:test +hatch run integration:test +``` + +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 [GitHub Actions] when you submit a pull request. + +### Python code style + +Python code within MkDocs' code base is formatted using [Black] and [Isort] and lint-checked using [Ruff], all of which are configured in `pyproject.toml`. + +You can automatically check and format the code according to these tools with the following command: + +```bash +hatch run style:fix +``` + +The code is also type-checked using [mypy] - also configured in `pyproject.toml`, it can be run like this: + +```bash +hatch run types:check +``` + +### Other style checks + +There are several other checks, such as spelling and JS style. To run all of them, use this command: + +```bash +hatch run lint:check +``` + +### Documentation of MkDocs itself + +After making edits to files under the `docs/` dir, you can preview the site locally using the following command: + +```bash +hatch run docs:serve +``` + +Note that any 'WARNING' should be resolved before submitting a contribution. + +Documentation files are also checked by markdownlint, so you should run this as well: + +```bash +hatch run lint:check +``` + +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. + +> INFO: If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with `.venv` being the virtualenv directory): +> +> ```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. +> ``` + +## Translating themes + +To localize a theme to your favorite language, follow the guide on [Translating Themes]. We welcome translation pull requests! + +## Submitting Pull Requests + +If you're considering a large code contribution to MkDocs, please prefer to +open an issue first to get early feedback on the idea. + +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. + +When working with a pull request branch: +Unless otherwise agreed, prefer `commit` over `amend`, and `merge` over `rebase`. 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. + +Do *not* add to *release-notes.md*, this will be written later. + +### Submitting changes to the builtin themes + +When installed with `i18n` support (`pip install 'mkdocs[i18n]'`), MkDocs allows +themes to support being translated into various languages (referred to as +locales) if they respect [Jinja's i18n extension] by wrapping text placeholders +with `{% trans %}` and `{% endtrans %}` tags. + +Each time a translatable text placeholder is added, removed or changed in a +theme template, the theme's Portable Object Template (`pot`) file needs to be +updated by running the `extract_messages` command. To update the +`pot` file for both built-in themes, run these commands: + +```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 +``` + +The updated `pot` file should be included in a PR with the updated template. +The updated `pot` file will allow translation contributors to propose the +translations needed for their preferred language. See the guide on [Translating +Themes] for details. + +NOTE: +Contributors are not expected to provide translations with their changes to +a theme's templates. However, they are expected to include an updated `pot` +file so that everything is ready for translators to do their job. + +## Code of Conduct + +Everyone interacting in the MkDocs project's codebases, issue trackers, chat +rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. + +[virtualenv]: https://virtualenv.pypa.io/en/latest/user_guide.html +[Hatch]: https://hatch.pypa.io/ +[install Hatch]: https://hatch.pypa.io/latest/install/#pip +[installing `pipx`]: https://pypa.github.io/pipx/installation/ +[GitHub Actions]: https://docs.github.com/actions +[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ +[Translating Themes]: https://www.mkdocs.org/dev-guide/translations/ +[Jinja's i18n extension]: https://jinja.palletsprojects.com/en/latest/extensions/#i18n-extension +[Ruff]: https://docs.astral.sh/ruff/ +[Black]: https://black.readthedocs.io/ +[Isort]: https://pycqa.github.io/isort/ +[mypy]: https://mypy-lang.org/ diff --git a/FUNDING.yml b/FUNDING.yml new file mode 100644 index 0000000000..2e9b9627cb --- /dev/null +++ b/FUNDING.yml @@ -0,0 +1 @@ +github: mkdocs diff --git a/README.md b/README.md index e63d11e6fc..7b665a23ab 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ If you need help with MkDocs, do not hesitate to get in contact with us! - For questions and high-level discussions, use **[Discussions]** on GitHub. - For small questions, a good alternative is the **[Chat room]** on - Gitter/Matrix (**new!**) + Gitter/Matrix. - To report a bug or make a feature request, open an **[Issue]** on GitHub. Please note that we may only provide @@ -44,8 +44,7 @@ Make sure to stick around to answer some questions as well! - [Official Documentation][mkdocs] - [Latest Release Notes][release-notes] -- [MkDocs Wiki][wiki] (Third-party themes, recipes, plugins and more) -- [Best-of-MkDocs][best-of] (Curated list of themes, plugins and more) +- [Catalog of third-party plugins, themes and recipes][catalog] ## Contributing to MkDocs @@ -63,18 +62,17 @@ discussion forums is expected to follow the [PyPA Code of Conduct]. [codecov-link]: https://codecov.io/github/mkdocs/mkdocs?branch=master [pypi-v-image]: https://img.shields.io/pypi/v/mkdocs.svg [pypi-v-link]: https://pypi.org/project/mkdocs/ -[GHAction-image]: https://github.com/mkdocs/mkdocs/workflows/CI/badge.svg?branch=master&event=push -[GHAction-link]: https://github.com/mkdocs/mkdocs/actions?query=event%3Apush+branch%3Amaster +[GHAction-image]: https://github.com/mkdocs/mkdocs/actions/workflows/ci.yml/badge.svg +[GHAction-link]: https://github.com/mkdocs/mkdocs/actions/workflows/ci.yml [mkdocs]: https://www.mkdocs.org [Issue]: https://github.com/mkdocs/mkdocs/issues [Discussions]: https://github.com/mkdocs/mkdocs/discussions [Chat room]: https://gitter.im/mkdocs/community [release-notes]: https://www.mkdocs.org/about/release-notes/ -[wiki]: https://github.com/mkdocs/mkdocs/wiki [Contributing Guide]: https://www.mkdocs.org/about/contributing/ [PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ -[best-of]: https://github.com/pawamoy/best-of-mkdocs +[catalog]: https://github.com/mkdocs/catalog ## License diff --git a/docs/about/contributing.md b/docs/about/contributing.md index 22648415b4..ea38c9bff4 100644 --- a/docs/about/contributing.md +++ b/docs/about/contributing.md @@ -1,112 +1 @@ -# Contributing to MkDocs - -An introduction to contributing to the MkDocs project. - -The MkDocs project welcomes, and depends, on contributions from developers and -users in the open source community. Contributions can be made in a number of -ways, a few examples are: - -- Code patches via pull requests -- Documentation improvements -- Bug reports and patch reviews - -For information about available communication channels please refer to the -[README](https://github.com/mkdocs/mkdocs/blob/master/README.md) file in our -GitHub repository. - -## Code of Conduct - -Everyone interacting in the MkDocs project's codebases, issue trackers, chat -rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. - -## Reporting an Issue - -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 and if you get an error please include the full error and -traceback. - -## Testing the Development Version - -If you want to just install and try out the latest development version of -MkDocs 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 **strongly** recommended -that you do this within a [virtualenv]. - -```bash -pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz -``` - -## Installing for Development - -First you'll need to fork and clone the repository. Once you have a local -copy, run the following command. It is **strongly** recommended that you do -this within a [virtualenv]. - -```bash -pip install --editable . -``` - -This will install MkDocs in development mode which binds the `mkdocs` command -to the git repository. - -## Running the tests - -To run the tests, it is recommended that you use [Hatch]. - -Install Hatch using [pip] by running the command `pip install hatch`. -Then the test suite can be run for MkDocs by running the command `hatch run all` in the -root of your MkDocs repository. - -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 [GitHub Actions] when you submit a pull request. - -## Translating themes - -To localize a theme to your favorite language, follow the guide on [Translating -Themes]. We welcome translation Pull Requests! - -## Submitting Pull Requests - -If you're considering a large code contribution to MkDocs, please prefer to -open an issue first to get early feedback on the idea. - -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. - -### Submitting changes to the builtin themes - -When installed with `i18n` support (`pip install mkdocs[i18n]`), MkDocs allows -themes to support being translated into various languages (referred to as -locales) if they respect [Jinja's i18n extension] by wrapping text placeholders -with `{% trans %}` and `{% endtrans %}` tags. - -Each time a translatable text placeholder is added, removed or changed in a -theme template, the theme's Portable Object Template (`pot`) file needs to be -updated by running the `extract_messages` command. For example, to update the -`pot` file of the `mkdocs` theme, run the following command: - -```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 -``` - -The updated `pot` file should be included in a PR with the updated template. -The updated `pot` file will allow translation contributors to propose the -translations needed for their preferred language. See the guide on [Translating -Themes] for details. - -NOTE: -Contributors are not expected to provide translations with their changes to -a theme's templates. However, they are expected to include an updated `pot` -file so that everything is ready for translators to do their job. - -[virtualenv]: https://virtualenv.pypa.io/en/latest/user_guide.html -[pip]: https://pip.pypa.io/en/stable/ -[Hatch]: https://hatch.pypa.io/ -[GitHub Actions]: https://docs.github.com/actions -[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ -[Translating Themes]: ../dev-guide/translations.md -[Jinja's i18n extension]: https://jinja.palletsprojects.com/en/latest/extensions/#i18n-extension +--8<-- "CONTRIBUTING.md" diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 96a2166c6d..4fd81c15cd 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -14,7 +14,7 @@ You can determine your currently installed version using `mkdocs --version`: ```console $ mkdocs --version -mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6) +mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10) ``` ## Maintenance team @@ -27,6 +27,593 @@ The current and past members of the MkDocs team. * [@oprypin](https://github.com/oprypin/) * [@ultrabug](https://github.com/ultrabug/) +## Version 1.6.1 (2024-08-30) + +### Fixed + +* Fix build error when environment variable `SOURCE_DATE_EPOCH=0` is set. #3795 +* Fix build error when `mkdocs_theme.yml` config is empty. #3700 +* Support `python -W` and `PYTHONWARNINGS` instead of overriding the configuration. #3809 +* Support running with Docker under strict mode, by removing `0.0.0.0` dev server warning. #3784 +* Drop unnecessary `changefreq` from `sitemap.xml`. #3629 +* Fix JavaScript console error when closing menu dropdown. #3774 +* Fix JavaScript console error that occur on repeated clicks. #3730 +* Fix JavaScript console error that can occur on dropdown selections. #3694 + +### Added + +* Added translations for Dutch. #3804 +* Added and updated translations for Chinese (Simplified). #3684 + +## Version 1.6.0 (2024-04-20) + +### Local preview + +* `mkdocs serve` 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: #3391 + +* New flag `serve --open` to open the site in a browser. + 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. + Context: #3500 + +#### Drafts + +> DANGER: **Changed from version 1.5.** + +**The `exclude_docs` config was split up into two separate concepts.** + +The `exclude_docs` config no longer has any special behavior for `mkdocs serve` - it now always completely excludes the listed documents from the site. + +If you wish to use the "drafts" functionality like the `exclude_docs` key used to do in MkDocs 1.5, please switch to the **new config key `draft_docs`**. + +See [documentation](../user-guide/configuration.md#exclude_docs). + +Other changes: + +* Reduce warning levels when a "draft" page has a link to a non-existent file. Context: #3449 + +### Update to deduction of page titles + +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. + +Now tags are always fully sanitized from the title. Though it still remains the case that [`Page.title`][mkdocs.structure.pages.Page.title] is expected to contain HTML entities and is passed directly to the themes. + +Images (notably, emojis in some extensions) get preserved in the title only through their `alt` attribute's value. + +Context: #3564, #3578 + +### Themes + +* Built-in themes now also support Polish language (#3613) + +#### "readthedocs" theme + +* Fix: "readthedocs" theme can now correctly handle deeply nested nav configurations (over 2 levels deep), without confusedly expanding all sections and jumping around vertically. (#3464) + +* Fix: "readthedocs" theme now shows a link to the repository (with a generic logo) even when isn't one of the 3 known hosters. (#3435) + +* "readthedocs" theme now also has translation for the word "theme" in the footer that mistakenly always remained in English. (#3613, #3625) + +#### "mkdocs" theme + +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. + +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 **not** enabled by default and need to be configured explicitly. +See `color_mode`, `user_color_mode_toggle` in [**documentation**](../user-guide/choosing-your-theme.md#mkdocs). + +> WARNING: **Possible breaking change.** +> +> 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: +> +> ```yaml +> extra_javascript: +> - https://code.jquery.com/jquery-3.7.1.min.js +> ``` +> +> Or even better if the script file is copied and included from your docs dir. + +Context: #3493, #3649 + +### Configuration + +#### New "`enabled`" setting for all plugins + +You may have seen some plugins take up the convention of having a setting `enabled: false` (or usually controlled through an environment variable) to make the plugin do nothing. + +Now *every* plugin has this setting. Plugins can still *choose* 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. + +See [**documentation**](../user-guide/configuration.md/#enabled-option). Context: #3395 + +### Validation + +#### Validation of hyperlinks between pages + +##### Absolute links + +> Historically, within Markdown, MkDocs only recognized **relative** links that lead to another physical `*.md` 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). + +If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly. + +If you set the setting `validation.links.absolute_links` to the new value `relative_to_docs`, all Markdown links starting with `/` will be understood as being relative to the `docs_dir` 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. + +So, now any document (e.g. "dir1/foo.md") can link to the document "dir2/bar.md" as `[link](/dir2/bar.md)`, in addition to the previously only correct way `[link](../dir2/bar.md)`. + +You have to enable the setting, though. The default is still to just skip any processing of such links. + +See [**documentation**](../user-guide/configuration.md#validation-of-absolute-links). Context: #3485 + +###### Absolute links within nav + +Absolute links within the `nav:` config were also always skipped. It is now possible to also validate them in the same way with `validation.nav.absolute_links`. Though it makes a bit less sense because then the syntax is simply redundant with the syntax that comes without the leading slash. + +##### Anchors + +There is a new config setting that is recommended to enable warnings for: + +```yaml +validation: + anchors: warn +``` + +Example of a warning that this can produce: + +```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'. +``` + +Any of the below methods of declaring an anchor will be detected by MkDocs: + +```markdown +## Heading producing an anchor + +## Another heading {#custom-anchor-for-heading-using-attr-list} + + + +[](){#markdown-anchor-using-attr-list} +``` + +Plugins and extensions that insert anchors, in order to be compatible with this, need to be developed as treeprocessors that insert `etree` elements as their mode of operation, rather than raw HTML which is undetectable for this purpose. + +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 `ignore` (and they are at INFO level by default anyway). + +See [**documentation**](../user-guide/configuration.md#validation). Context: #3463 + +Other changes: + +* When the `nav` config is not specified at all, the `not_in_nav` setting (originally added in 1.5.0) gains an additional behavior: documents covered by `not_in_nav` will not be part of the automatically deduced navigation. Context: #3443 + +* Fix: the `!relative` YAML tag for `markdown_extensions` (originally added in 1.5.0) - it was broken in many typical use cases. + + See [**documentation**](../user-guide/configuration.md#paths-relative-to-the-current-file-or-site). Context: #3466 + +* Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: #3437 + +* 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: #3445 + +### Upgrades for plugin developers + +#### Plugins can add multiple handlers for the same event type, at multiple priorities + +See [`mkdocs.plugins.CombinedEvent`][] in [**documentation**](../dev-guide/plugins.md#event-priorities). Context: #3448 + +#### Enabling true generated files and expanding the [`File`][mkdocs.structure.files.File] API + +See [**documentation**][mkdocs.structure.files.File]. + +* There is a new pair of attributes [`File.content_string`][mkdocs.structure.files.File.content_string]/[`content_bytes`][mkdocs.structure.files.File.content_bytes] that becomes the official API for obtaining the content of a file and is used by MkDocs itself. + + This replaces the old approach where one had to manually read the file located at [`File.abs_src_path`][mkdocs.structure.files.File.abs_src_path], although that is still the primary action that these new attributes do under the hood. + +* The content of a `File` can be backed by a string and no longer has to be a real existing file at `abs_src_path`. + + It is possible to **set** the attribute `File.content_string` or `File.content_bytes` and it will take precedence over `abs_src_path`. + + Further, `abs_src_path` is no longer guaranteed to be present and can be `None` instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute. + +* There is a new constructor [`File.generated()`][mkdocs.structure.files.File.generated] that should be used by plugins instead of the `File()` constructor. It is much more convenient because one doesn't need to manually look up the values such as `docs_dir` and `use_directory_urls`. Its signature is one of: + + ```python + f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes) + f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str) + ``` + + This way, it is now extremely easy to add a virtual file even from a hook: + + ```python + def on_files(files: Files, config: MkDocsConfig): + files.append(File.generated(config, 'fake/path.md', content="Hello, world!")) + ``` + + 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 `docs_dir`. + +* There is a new attribute [`File.generated_by`][mkdocs.structure.files.File.generated_by] that arose by convention - for generated files it should be set to the name of the plugin (the key in the `plugins:` collection) that produced this file. This attribute is populated automatically when using the `File.generated()` constructor. + +* It is possible to set the [`edit_uri`][mkdocs.structure.files.File.edit_uri] attribute of a `File`, for example from a plugin or hook, to make it different from the default (equal to `src_uri`), 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 `edit_uri` to that source file or script accordingly. + +* The `File` object now stores its original `src_dir`, `dest_dir`, `use_directory_urls` values as attributes. + +* Fields of `File` are computed on demand but cached. Only the three above attributes are primary ones, and partly also [`dest_uri`][mkdocs.structure.files.File.dest_uri]. This way, it is possible to, for example, overwrite `dest_uri` of a `File`, and `abs_dest_path` will be calculated based on it. However you need to clear the attribute first using `del f.abs_dest_path`, because the values are cached. + +* `File` instances are now hashable (can be used as keys of a `dict`). Two files can no longer be considered "equal" unless it's the exact same instance of `File`. + +Other changes: + +* The internal storage of `File` objects inside a `Files` object has been reworked, so any plugins that choose to access `Files._files` will get a deprecation warning. + +* The order of `File` objects inside a `Files` collection is no longer significant when automatically inferring the `nav`. They get forcibly sorted according to the default alphabetic order. + +Context: #3451, #3463 + +### Hooks and debugging + +* Hook files can now import adjacent *.py files using the `import` statement. Previously this was possible to achieve only through a `sys.path` workaround. See the new mention in [documentation](../user-guide/configuration.md#hooks). Context: #3568 + +* Verbose `-v` log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: #3444 + +### Deprecations + +* Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429 + +* The theme config file `mkdocs_theme.yml` no longer executes YAML tags. Context: #3465 + +* The plugin event `on_page_read_source` is soft-deprecated because there is always a better alternative to it (see the new `File` API or just `on_page_markdown`, depending on the desired interaction). + + When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case. + + See [**documentation**](../dev-guide/plugins.md#on_page_read_source). Context: #3503 + +#### API deprecations + +* It is no longer allowed to set `File.page` to a type other than `Page` or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381. + +* `Theme._vars` is deprecated - use `theme['foo']` instead of `theme._vars['foo']` + +* `utils`: `modified_time()`, `get_html_path()`, `get_url_path()`, `is_html_file()`, `is_template_file()` are removed. `path_to_url()` is deprecated. + +* `LiveReloadServer.watch()` no longer accepts a custom callback. + +Context: #3429 + +### Misc + +* The `sitemap.xml.gz` file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460 + +Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.3...1.6.0). + +## Version 1.5.3 (2023-09-18) + +* Fix `mkdocs serve` sometimes locking up all browser tabs when navigating quickly (#3390) + +* Add many new supported languages for "search" plugin - update lunr-languages to 1.12.0 (#3334) + +* Bugfix (regression in 1.5.0): In "readthedocs" theme the styling of "breadcrumb navigation" was broken for nested pages (#3383) + +* Built-in themes now also support Chinese (Traditional, Taiwan) language (#3154) + +* Plugins can now set `File.page` to their own subclass of `Page`. There is also now a warning if `File.page` is set to anything other than a strict subclass of `Page`. (#3367, #3381) + + Note that just instantiating a `Page` [sets the file automatically](https://github.com/mkdocs/mkdocs/blob/f94ab3f62d0416d484d81a0c695c8ca86ab3b975/mkdocs/structure/pages.py#L34), so care needs to be taken not to create an unneeded `Page`. + +Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.2...1.5.3). + +## Version 1.5.2 (2023-08-02) + +* Bugfix (regression in 1.5.0): Restore functionality of `--no-livereload`. (#3320) + +* Bugfix (regression in 1.5.0): The new page title detection would sometimes be unable to drop anchorlinks - fix that. (#3325) + +* Partly bring back pre-1.5 API: `extra_javascript` items will once again be mostly strings, and only sometimes `ExtraScriptValue` (when the extra `script` functionality is used). + + Plugins should be free to append strings to `config.extra_javascript`, but when reading the values, they must still make sure to read it as `str(value)` in case it is an `ExtraScriptValue` item. For querying the attributes such as `.type` you need to check `isinstance` first. Static type checking will guide you in that. (#3324) + +See [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.1...1.5.2). + +## Version 1.5.1 (2023-07-28) + +* Bugfix (regression in 1.5.0): Make it possible to treat `ExtraScriptValue` as a path. This lets some plugins still work despite the breaking change. + +* Bugfix (regression in 1.5.0): Prevent errors for special setups that have 3 conflicting files, such as `index.html`, `index.md` *and* `README.md` (#3314) + +See [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.0...1.5.1). + +## Version 1.5.0 (2023-07-26) + +### New command `mkdocs get-deps` + +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: + +```bash +pip install $(mkdocs get-deps) +``` + +The idea is that right after running this command, you can directly follow it up with `mkdocs build` and it will almost always "just work", without needing to think which dependencies to install. + +The way it works is by scanning `mkdocs.yml` for `themes:`, `plugins:`, `markdown_extensions:` items and doing a reverse lookup based on a large list of known projects (catalog, see below). + +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. + +The command allows overriding which config file is used (instead of `mkdocs.yml` in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See [`mkdocs get-deps --help`](../user-guide/cli.md#mkdocs-get-deps). + +Context: #3205 + +### MkDocs has an official catalog of plugins + +Check out and add all your general-purpose plugins, themes and extensions there, so that they can be looked up through `mkdocs get-deps`. + +This was renamed from "best-of-mkdocs" and received significant updates. In addition to `pip` installation commands, the page now shows the config boilerplate needed to add a plugin. + +### Expanded validation of links + +#### Validated links in Markdown + +> As you may know, within Markdown, MkDocs really only recognizes **relative** links that lead to another physical `*.md` 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 `*.md` links into `*.html` as appropriate, and it would also always tell you if such a link doesn't actually lead to an existing file. + +However, the checks for links were really loose and had many concessions. For example, links that started with `/` ("absolute") and links that *ended* with `/` 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 `..` with `use_directory_urls` enabled. + +Now, in addition to validating relative links, MkDocs will print `INFO` messages for unrecognized types of links (including absolute links). They look like this: + +```text +INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'? +``` + +If you don't want any changes, not even the `INFO` messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to `mkdocs.yml` (**not** recommended): + +```yaml +validation: + absolute_links: ignore + unrecognized_links: ignore +``` + +If, on the opposite end, you want these to print `WARNING` messages and cause `mkdocs build --strict` to fail, you are recommended to configure these to `warn` instead. + +See [**documentation**](../user-guide/configuration.md#validation) for actual recommended settings and more details. Context: #3283 + +#### Validated links in the nav + +Links to documents in the [`nav` configuration](../user-guide/configuration.md#nav) now also have configurable validation, though with no changes to the defaults. + +You are welcomed to turn on validation for files that were forgotten and excluded from the nav. Example: + +```yaml +validation: + nav: + omitted_files: warn + absolute_links: warn +``` + +This can make the following message appear with the `WARNING` level (as opposed to `INFO` as the only option previously), thus being caught by `mkdocs --strict`: + +```text +INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: ... +``` + +See [**documentation**](../user-guide/configuration.md#validation). Context: #3283, #1755 + +#### Mark docs as intentionally "not in nav" + +There is a new config `not_in_nav`. With it, you can mark particular patterns of files as exempt from the above `omitted_files` warning type; no messages will be printed for them anymore. (As a corollary, setting this config to `*` is the same as ignoring `omitted_files` altogether.) + +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. + +The `not_in_nav` config is a set of gitignore-like patterns. See the next section for an explanation of another such config. + +See [**documentation**](../user-guide/configuration.md#not_in_nav). Context: #3224, #1888 + +### Excluded doc files + +There is a new config `exclude_docs` that tells MkDocs to ignore certain files under `docs_dir` and *not* copy them to the built `site` as part of the build. + +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. + +The `exclude_docs` config follows the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format) and is specified as a multiline YAML string. For example: + +```yaml +exclude_docs: | + *.py # Excludes e.g. docs/hooks/foo.py + /requirements.txt # Excludes docs/requirements.txt +``` + +Validation of links (described above) is also affected by `exclude_docs`. During `mkdocs serve` the messages explain the interaction, whereas during `mkdocs build` excluded files are as good as nonexistent. + +As an additional related change, if you have a need to have both `README.md` and `index.md` 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. + +See [**documentation**](../user-guide/configuration.md#exclude_docs). Context: #3224 + +#### Drafts + +> DANGER: **Dropped from version 1.6:** +> +> The `exclude_docs` config no longer applies the "drafts" functionality for `mkdocs serve`. This was renamed to [`draft_docs`](../user-guide/configuration.md#draft_docs). + +The `exclude_docs` config has another behavior: all excluded Markdown pages will still be previewable in `mkdocs serve` only, just with a "DRAFT" marker on top. Then they will of course be excluded from `mkdocs build` or `gh-deploy`. + +If you don't want `mkdocs serve` to have any special behaviors and instead want it to perform completely normal builds, use the new flag `mkdocs serve --clean`. + +See [**documentation**](../user-guide/configuration.md#exclude_docs). Context: #3224 + +### `mkdocs serve` no longer exits after build errors + +If there was an error (from the config or a plugin) during a site re-build, `mkdocs serve` 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. + +But errors on the *first* build still cause `mkdocs serve` to exit, as before. + +Context: #3255 + +### Page titles will be deduced from any style of heading + +MkDocs always had the ability to infer the title of a page (if it's not specified in the `nav`) based on the first line of the document, if it had a `

` heading that had to written starting with the exact character `#`. Now any style of Markdown heading is understood (#1886). Due to the previous simplistic parsing, it was also impossible to use `attr_list` attributes in that first heading (#3136). Now that is also fixed. + +### Markdown extensions can use paths relative to the current document + +This is aimed at extensions such as `pymdownx.snippets` or `markdown_include.include`: you can now specify their include paths to be relative to the currently rendered Markdown document, or relative to the `docs_dir`. Any other extension can of course also make use of the new `!relative` YAML tag. + +```yaml +markdown_extensions: + - pymdownx.snippets: + base_path: !relative +``` + +See [**documentation**](../user-guide/configuration.md#paths-relative-to-the-current-file-or-site). Context: #2154, #3258 + +### ` +> > {%- endfor %} +> > ``` +> > +> > This old-style example even uses the obsolete top-level `extra_javascript` list. Please always use `config.extra_javascript` instead. +> > +> > So, a slightly more modern approach is the following, but it is still obsolete because it ignores the extra attributes of the script: +> > +> > ```django +> > {%- for path in config.extra_javascript %} +> > +> > {%- endfor %} +> > ``` +> +> >? EXAMPLE: **New style:** +> > +> > ```django +> > {%- for script in config.extra_javascript %} +> > {{ script | script_tag }} +> > {%- endfor %} +> > ``` +> +> If you wish to be able to pick up the new customizations while keeping your theme compatible with older versions of MkDocs, use this snippet: +> +> >! EXAMPLE: **Backwards-compatible style:** +> > +> > ```django +> > {%- for script in config.extra_javascript %} +> > {%- if script.path %} {# Detected MkDocs 1.5+ which has `script.path` and `script_tag` #} +> > {{ script | script_tag }} +> > {%- else %} {# Fallback - examine the file name directly #} +> > +> > {%- endif %} +> > {%- endfor %} +> > ``` + ## Theme Files There are various files which a theme treats special in some way. Any other @@ -185,7 +245,6 @@ used options include: * [config.repo_url](../user-guide/configuration.md#repo_url) * [config.repo_name](../user-guide/configuration.md#repo_name) * [config.copyright](../user-guide/configuration.md#copyright) -* [config.google_analytics](../user-guide/configuration.md#google_analytics) #### nav @@ -226,7 +285,7 @@ Following is a basic usage example which outputs the first and second level navigation as a nested list. ```django -{% if nav|length>1 %} +{% if nav|length > 1 %}