From 18e69c1319d8112ff6a48a65362088aed55d9e50 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Thu, 30 Apr 2026 00:31:25 +0300 Subject: [PATCH 1/4] Fix Click default option handling --- docs/about/release-notes.md | 1 + mkdocs/__main__.py | 16 ++++++++++++++++ mkdocs/tests/cli_tests.py | 27 +++++++++++++++++++++++++++ 3 files changed, 44 insertions(+) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index dc90f98b..33bcf08e 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -27,6 +27,7 @@ The current members of the MkDocs-NG team. ### Fixed +* Fix CLI default handling with recent Click versions so omitted options do not override configured `strict`, `use_directory_urls`, or serve reload mode values. * Fix dropdown submenu arrow invisible in the navigation menu. #44 * Fix malformed URLs (e.g., unterminated IPv6 literals) crashing the entire build. #45 * Fix build crash caused by broken (dangling) symlinks in the docs directory. #46 diff --git a/mkdocs/__main__.py b/mkdocs/__main__.py index a6e278c0..1f81388d 100644 --- a/mkdocs/__main__.py +++ b/mkdocs/__main__.py @@ -219,6 +219,19 @@ def callback(ctx, param, value): )(f) +def unset_default_source_values(kwargs, *names): + ctx = click.get_current_context(silent=True) + if ctx is None: + return + + for name in names: + if ( + name in kwargs + and ctx.get_parameter_source(name) is click.core.ParameterSource.DEFAULT + ): + kwargs[name] = None + + common_options = add_options(quiet_option, verbose_option) common_config_options = add_options( click.option("-f", "--config-file", type=click.File("rb"), help=config_help), @@ -283,6 +296,7 @@ def serve_command(**kwargs): from mkdocs.commands import serve _enable_warnings() + unset_default_source_values(kwargs, "build_type", "strict", "use_directory_urls") serve.serve(**kwargs) @@ -296,6 +310,7 @@ def build_command(clean, **kwargs): from mkdocs.commands import build _enable_warnings() + unset_default_source_values(kwargs, "strict", "use_directory_urls") cfg = config.load_config(**kwargs) cfg.plugins.on_startup(command="build", dirty=not clean) try: @@ -331,6 +346,7 @@ def gh_deploy_command( from mkdocs.commands import build, gh_deploy _enable_warnings() + unset_default_source_values(kwargs, "strict", "use_directory_urls") cfg = config.load_config( remote_branch=remote_branch, remote_name=remote_name, **kwargs ) diff --git a/mkdocs/tests/cli_tests.py b/mkdocs/tests/cli_tests.py index d4f1cefd..e028f146 100644 --- a/mkdocs/tests/cli_tests.py +++ b/mkdocs/tests/cli_tests.py @@ -14,6 +14,33 @@ class CLITests(unittest.TestCase): def setUp(self): self.runner = CliRunner() + def test_unset_default_source_values_restores_default_values(self): + kwargs = {"build_type": "False", "strict": False, "use_directory_urls": False} + ctx = mock.Mock() + ctx.get_parameter_source.return_value = cli.click.core.ParameterSource.DEFAULT + + with mock.patch("mkdocs.__main__.click.get_current_context", return_value=ctx): + cli.unset_default_source_values( + kwargs, "build_type", "strict", "use_directory_urls" + ) + + self.assertIsNone(kwargs["build_type"]) + self.assertIsNone(kwargs["strict"]) + self.assertIsNone(kwargs["use_directory_urls"]) + + def test_unset_default_source_values_preserves_commandline_values(self): + kwargs = {"strict": False, "use_directory_urls": False} + ctx = mock.Mock() + ctx.get_parameter_source.return_value = ( + cli.click.core.ParameterSource.COMMANDLINE + ) + + with mock.patch("mkdocs.__main__.click.get_current_context", return_value=ctx): + cli.unset_default_source_values(kwargs, "strict", "use_directory_urls") + + self.assertFalse(kwargs["strict"]) + self.assertFalse(kwargs["use_directory_urls"]) + @mock.patch("mkdocs.commands.serve.serve", autospec=True) def test_serve_default(self, mock_serve): result = self.runner.invoke(cli.cli, ["serve"], catch_exceptions=False) From 3fabcaffd5df006fd43e18e06114ef706b7ef3e6 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Thu, 30 Apr 2026 00:46:57 +0300 Subject: [PATCH 2/4] Handle Click default values correctly --- PLAN.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 00000000..035b8e81 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,167 @@ +# MkDocs-NG Feature Plan + +Curated from [mkdocs/mkdocs issues](https://github.com/mkdocs/mkdocs/issues) and +[discussions](https://github.com/mkdocs/mkdocs/discussions), sorted by user demand +(reactions :+1: + comments). Items already addressed by mkdocs-ng are excluded. + +--- + +## ๐Ÿ”ฅ P0 โ€“ High Demand / Urgent Bugs + +### 1. Remove CDNs from built-in themes +- **Issue**: [mkdocs/mkdocs#2171](https://github.com/mkdocs/mkdocs/issues/2171) +- **๐Ÿ‘**: 18 ยท ๐Ÿ’ฌ: 7 +- **Description**: The built-in `mkdocs` and `readthedocs` themes load fonts (e.g. Lato, Roboto Slab) and CSS from Google Fonts / CDNs. Users who self-host documentation want full offline / privacy-respecting operation without third-party requests. Some fonts are already bundled, but `base.html` still references external URLs. +- **Labels**: `Theme-mkdocs`, `Theme-readthedocs` + +### 2. Improve `mkdocs serve` performance & authoring experience +- **Issue**: [mkdocs/mkdocs#3695](https://github.com/mkdocs/mkdocs/issues/3695) +- **๐Ÿ‘**: 15 ยท ๐Ÿ’ฌ: 22 +- **Description**: Opened by the maintainer of Material for MkDocs. Proposes collaborative improvements to `mkdocs serve`: faster rebuilds, smarter watcher, better error messages, and lowering the friction of the write-build-check loop. Concrete ideas include incremental builds, file-system-level caching, and a plugin-friendly architecture for serve hooks. + +### 3. Stable public Python API +- **Issue**: [mkdocs/mkdocs#1240](https://github.com/mkdocs/mkdocs/issues/1240) +- **๐Ÿ‘**: 10 ยท ๐Ÿ’ฌ: 8 +- **Description**: There is no officially supported way to invoke MkDocs from Python code. Users currently call internal functions (e.g. `build_command()`, `serve_command()`) or shell out via `subprocess`. A documented, stable API (e.g. `mkdocs.build()`, `mkdocs.serve()`) is needed for build-system integrations, CI scripts, and programmatic usage. +- **Labels**: `Enhancement`, `Needs design decision` + +### 4. Remove hardcoded Google Analytics from theme +- **Issue**: [mkdocs/mkdocs#3630](https://github.com/mkdocs/mkdocs/issues/3630) +- **๐Ÿ‘**: 8 ยท ๐Ÿ’ฌ: 1 +- **Description**: The `mkdocs` theme hardcodes a Google Analytics snippet via the `analytics` template tag block. This is out of place in a privacy-conscious static site generator. Proposal: drop the built-in GA support entirely and document how to add analytics via `extrahead` template overrides instead. +- **Labels**: `Cleanup` + +### 5. Support multiple `INHERIT` configs +- **Issue**: [mkdocs/mkdocs#2624](https://github.com/mkdocs/mkdocs/issues/2624) +- **๐Ÿ‘**: 8 ยท ๐Ÿ’ฌ: 3 +- **Description**: `INHERIT` currently accepts only a single file path. Users with complex setups want to compose configuration from multiple files (e.g. one for markdown extensions, one for plugins, one for extra settings). Proposal: allow `INHERIT` to accept a list of paths. +- **Labels**: `Configuration` + +### 6. Fix `mkdocs serve --livereload` not triggering automatically +- **Issue**: [mkdocs/mkdocs#4055](https://github.com/mkdocs/mkdocs/issues/4055) +- **๐Ÿ‘**: 25 ยท ๐Ÿ’ฌ: 6 +- **Description**: In recent versions, livereload no longer works unless `--livereload` is passed explicitly. mkdocs-ng **partially** addresses this through PRs restoring `--livereload`, but some users still report it not working by default. This may intersect with the Click version issue (#4032) and WSL-specific problems (#4081). +- **Status in mkdocs-ng**: โœ… `--livereload` flag restored; default behaviour should be verified + +### 7. `mkdocs serve` does not watch files (Click โ‰ฅ 8.3.0 regression) +- **Issue**: [mkdocs/mkdocs#4032](https://github.com/mkdocs/mkdocs/issues/4032) +- **๐Ÿ‘**: 66 ยท ๐Ÿ’ฌ: 31 +- **Description**: Starting with Click 8.3.0, file watching breaks entirely โ€” changes no longer trigger a rebuild. Workaround is pinning `click<=8.2.1`. This is the highest-reaction open issue by far. +- **Status in mkdocs-ng**: needs verification โ€” `pyproject.toml` currently allows `click >=7.0`; CI pins to `8.1.8` for min-version tests, but the runtime constraint does not prevent 8.3.0. + +--- + +## โšก P1 โ€“ Important Features & Fixes + +### 8. Live reload triggers on editor temp / hidden files +- **Issue**: [mkdocs/mkdocs#2519](https://github.com/mkdocs/mkdocs/issues/2519) +- **๐Ÿ‘**: 7 ยท ๐Ÿ’ฌ: 18 +- **Description**: Editors like Vim create swap files (`.foo.md.swp`) and hidden files that cause `mkdocs serve` to constantly rebuild even though those files aren't included in the output. The watcher should ignore dot-files and editor temp files by default, with an opt-in mechanism for directories like `.well-known/`. +- **Labels**: `Command - serve`, `Configuration` + +### 9. Add `rel="external"` to outbound links +- **Issue**: [mkdocs/mkdocs#3914](https://github.com/mkdocs/mkdocs/issues/3914) +- **๐Ÿ‘**: 7 ยท ๐Ÿ’ฌ: 0 +- **Description**: External (absolute URL) links should be automatically annotated with `rel="external"` so theme authors and users can style them differently (e.g. add an external-link icon). This became more important after Material for MkDocs switched to always using absolute URLs for navigation. +- **Labels**: `Enhancement` + +### 10. Cache busting for static assets +- **Issue**: [mkdocs/mkdocs#1979](https://github.com/mkdocs/mkdocs/issues/1979) +- **๐Ÿ‘**: 5 ยท ๐Ÿ’ฌ: 34 +- **Description**: MkDocs has no built-in mechanism to append content hashes to CSS/JS filenames for cache busting. After a documentation site update, returning visitors may get stale cached assets. Implementation could be via a plugin (preferred by maintainers) or core feature. +- **Labels**: `Enhancement`, `Plugins` + +### 11. Decouple built-in search from core +- **Issue**: [mkdocs/mkdocs#3698](https://github.com/mkdocs/mkdocs/issues/3698) +- **๐Ÿ‘**: 5 ยท ๐Ÿ’ฌ: 8 +- **Description**: The search plugin (based on lunr.js) is bundled with core MkDocs. lunr.js is unmaintained (last commit ~4 years ago) with known bugs. Proposal: extract search into a standalone installable package, decouple it from the core release cycle, and pave the way for a modern replacement. +- **Labels**: `Search` + +### 12. Decouple built-in themes from core +- **Issue**: [mkdocs/mkdocs#3636](https://github.com/mkdocs/mkdocs/issues/3636) +- **๐Ÿ‘**: 4 ยท ๐Ÿ’ฌ: 17 +- **Description**: The core maintainers agreed to move the `readthedocs` theme (and possibly `mkdocs` theme) into separate repos and installable packages. This simplifies core, allows themes to be versioned independently, and opens the door for new default themes. +- **Labels**: `Cleanup` + +### 13. Support root directory as `docs_dir` +- **Issue**: [mkdocs/mkdocs#3450](https://github.com/mkdocs/mkdocs/issues/3450) / [PR #3519](https://github.com/mkdocs/mkdocs/pull/3519) +- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 15 +- **Description**: MkDocs currently forbids placing `mkdocs.yml` inside the `docs_dir`. Users who want to use the project root as `docs_dir` (e.g. monorepos, projects with `README.md` as homepage) need to work around this restriction. The PR #3519 removes the validation check and auto-excludes config/site files from the docs. +- **Labels**: `Navigation` + +--- + +## ๐Ÿ“‹ P2 โ€“ Nice to Have + +### 14. Support text fragment links (ignore them during validation) +- **Issue**: [mkdocs/mkdocs#3952](https://github.com/mkdocs/mkdocs/issues/3952) +- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 0 +- **Description**: [Text fragment links](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment/Text_fragments) (`#:~:text=โ€ฆ`) are a modern web standard for linking to specific text on a page. MkDocs' anchor validator incorrectly reports them as broken anchors. The validator should recognize and skip `#:~:text=` fragments. +- **Labels**: `Validation` + +### 15. Auto-switch port when the default port is busy +- **Issue**: [mkdocs/mkdocs#3496](https://github.com/mkdocs/mkdocs/issues/3496) +- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 0 +- **Description**: If port 8000 is already in use, `mkdocs serve` should automatically try the next available port (8001, 8002, โ€ฆ) instead of failing. A related PR (#3498) adds a manual port override flag, but automatic fallback is the desired UX. +- **Labels**: `Command - serve` + +### 16. Smart section titles when no nav is configured +- **Issue**: [mkdocs/mkdocs#3356](https://github.com/mkdocs/mkdocs/issues/3356) +- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 6 +- **Description**: When no `nav` is defined in `mkdocs.yml`, section titles for sub-directories should be derived from the index page's title metadata or first heading, rather than displaying raw directory names. This is already a feature in Material for MkDocs (`navigation.smart-section-titles`), but should be available in core. +- **Labels**: `Navigation`, `Titles` + +### 17. Support GitHub-style Markdown Alerts +- **Issue**: [mkdocs/mkdocs#3997](https://github.com/mkdocs/mkdocs/issues/3997) +- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 2 +- **Description**: GitHub-flavored markdown alert blocks (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`) should render as styled callouts in MkDocs. This would improve portability of docs authored on GitHub to MkDocs sites. + +### 18. Extend `on_page_context` with Jinja2 Environment reference +- **Issue**: [mkdocs/mkdocs#3709](https://github.com/mkdocs/mkdocs/issues/3709) +- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 1 +- **Description**: The `on_page_context` plugin event should expose the Jinja2 `Environment` object so plugins can apply per-page template filters and globals. This is needed for multi-instance plugins (e.g. Material for MkDocs blog plugin) where each plugin instance needs to register its own template functions per page. + +### 19. Deprecated options should emit `INFO`, not `WARNING` +- **Issue**: [mkdocs/mkdocs#3696](https://github.com/mkdocs/mkdocs/issues/3696) +- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 5 +- **Description**: The `Deprecated` config helper emits `WARNING` messages, which break `--strict` mode. Since deprecated options are still functional (just discouraged), they should emit `INFO`-level messages so strict builds don't fail on deprecation notices alone. + +### 20. Custom import paths for `markdown_extensions` +- **Issue**: [mkdocs/mkdocs#3772](https://github.com/mkdocs/mkdocs/issues/3772) +- **๐Ÿ‘**: 1 ยท ๐Ÿ’ฌ: 29 +- **Description**: Users who write small project-specific Markdown extensions need a way to add the extension's directory to `sys.path` from within `mkdocs.yml`, without requiring `PYTHONPATH` hacks or pip-installable packages. A config option like `markdown_extensions_path: ["extensions/"]` would suffice. + +### 21. Respect display text when the same `.md` file appears in nav multiple times +- **Issue**: [mkdocs/mkdocs#3710](https://github.com/mkdocs/mkdocs/issues/3710) +- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 3 +- **Description**: When a file is referenced multiple times in `nav` with different display names (e.g. `- 'French Main Dishes': 'French Cuisine.md'` and `- 'French Desserts': 'French Cuisine.md'`), MkDocs now overrides both entries with the first title encountered. Previously, each entry kept its set display text. + +--- + +## ๐Ÿ”ง P3 โ€“ Maintenance & Infrastructure + +### 22. New default theme +- **Issue**: [mkdocs/mkdocs#3680](https://github.com/mkdocs/mkdocs/issues/3680) +- **๐Ÿ‘**: 0 ยท ๐Ÿ’ฌ: 6 +- **Description**: The default `mkdocs` theme is dated (Bootstrap 3). A new, modern, optionally installable default theme should be designed and shipped separately, as part of the theme decoupling effort (#3636). + +### 23. Title source precedence controls +- **Issue**: [mkdocs/mkdocs#3532](https://github.com/mkdocs/mkdocs/issues/3532) +- **๐Ÿ‘**: 0 ยท ๐Ÿ’ฌ: 37 +- **Description**: When a page has both a YAML `title` meta field and an H1 heading, the precedence between them (and the `nav` display name) can be surprising. Users want more control over which source wins, ideally configurable per page or globally. + +### 24. Fix `use_directory_urls: true` with Click โ‰ฅ 8.2.2 +- **Issue**: [mkdocs/mkdocs#4014](https://github.com/mkdocs/mkdocs/issues/4014) +- **๐Ÿ‘**: 7 ยท ๐Ÿ’ฌ: 5 +- **Description**: Click 8.2.2 changed path behavior that broke `use_directory_urls: true` โ€” generated links become `page/index.html` instead of `page/`. This is related to #4032 and may require pinning or fixing the Click integration. +- **Status in mkdocs-ng**: unknown โ€” needs testing with Click โ‰ฅ 8.2.2 + +### 25. WSL: `mkdocs serve` fails to live reload +- **Issue**: [mkdocs/mkdocs#4081](https://github.com/mkdocs/mkdocs/issues/4081) +- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 2 +- **Description**: On WSL with ext4 filesystem, file-watching doesn't trigger livereload. May be related to the Click watcher regression (#4032) or filesystem notification limitations in WSL. + +--- + +*Last updated: 2026-04-29* +*Sources: [mkdocs/mkdocs open issues](https://github.com/mkdocs/mkdocs/issues), sorted by reactions* From 7b6299b6a0e37b9e70b5cae6e2f7903b8704f881 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Thu, 30 Apr 2026 01:13:33 +0300 Subject: [PATCH 3/4] Require Click 8.1.8 --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 6e610245..37bffb20 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,7 +36,7 @@ classifiers = [ dynamic = ["version"] requires-python = ">=3.8" dependencies = [ - "click >=7.0", + "click >=8.1.8", "Jinja2 >=2.11.1", "markupsafe >=2.0.1", "Markdown >=3.3.6", From f5efbd92c299889823e2b2daad36b3dcb121f82c Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Thu, 30 Apr 2026 01:14:47 +0300 Subject: [PATCH 4/4] fixup! Require Click 8.1.8 --- PLAN.md | 167 -------------------------------------------------------- 1 file changed, 167 deletions(-) delete mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index 035b8e81..00000000 --- a/PLAN.md +++ /dev/null @@ -1,167 +0,0 @@ -# MkDocs-NG Feature Plan - -Curated from [mkdocs/mkdocs issues](https://github.com/mkdocs/mkdocs/issues) and -[discussions](https://github.com/mkdocs/mkdocs/discussions), sorted by user demand -(reactions :+1: + comments). Items already addressed by mkdocs-ng are excluded. - ---- - -## ๐Ÿ”ฅ P0 โ€“ High Demand / Urgent Bugs - -### 1. Remove CDNs from built-in themes -- **Issue**: [mkdocs/mkdocs#2171](https://github.com/mkdocs/mkdocs/issues/2171) -- **๐Ÿ‘**: 18 ยท ๐Ÿ’ฌ: 7 -- **Description**: The built-in `mkdocs` and `readthedocs` themes load fonts (e.g. Lato, Roboto Slab) and CSS from Google Fonts / CDNs. Users who self-host documentation want full offline / privacy-respecting operation without third-party requests. Some fonts are already bundled, but `base.html` still references external URLs. -- **Labels**: `Theme-mkdocs`, `Theme-readthedocs` - -### 2. Improve `mkdocs serve` performance & authoring experience -- **Issue**: [mkdocs/mkdocs#3695](https://github.com/mkdocs/mkdocs/issues/3695) -- **๐Ÿ‘**: 15 ยท ๐Ÿ’ฌ: 22 -- **Description**: Opened by the maintainer of Material for MkDocs. Proposes collaborative improvements to `mkdocs serve`: faster rebuilds, smarter watcher, better error messages, and lowering the friction of the write-build-check loop. Concrete ideas include incremental builds, file-system-level caching, and a plugin-friendly architecture for serve hooks. - -### 3. Stable public Python API -- **Issue**: [mkdocs/mkdocs#1240](https://github.com/mkdocs/mkdocs/issues/1240) -- **๐Ÿ‘**: 10 ยท ๐Ÿ’ฌ: 8 -- **Description**: There is no officially supported way to invoke MkDocs from Python code. Users currently call internal functions (e.g. `build_command()`, `serve_command()`) or shell out via `subprocess`. A documented, stable API (e.g. `mkdocs.build()`, `mkdocs.serve()`) is needed for build-system integrations, CI scripts, and programmatic usage. -- **Labels**: `Enhancement`, `Needs design decision` - -### 4. Remove hardcoded Google Analytics from theme -- **Issue**: [mkdocs/mkdocs#3630](https://github.com/mkdocs/mkdocs/issues/3630) -- **๐Ÿ‘**: 8 ยท ๐Ÿ’ฌ: 1 -- **Description**: The `mkdocs` theme hardcodes a Google Analytics snippet via the `analytics` template tag block. This is out of place in a privacy-conscious static site generator. Proposal: drop the built-in GA support entirely and document how to add analytics via `extrahead` template overrides instead. -- **Labels**: `Cleanup` - -### 5. Support multiple `INHERIT` configs -- **Issue**: [mkdocs/mkdocs#2624](https://github.com/mkdocs/mkdocs/issues/2624) -- **๐Ÿ‘**: 8 ยท ๐Ÿ’ฌ: 3 -- **Description**: `INHERIT` currently accepts only a single file path. Users with complex setups want to compose configuration from multiple files (e.g. one for markdown extensions, one for plugins, one for extra settings). Proposal: allow `INHERIT` to accept a list of paths. -- **Labels**: `Configuration` - -### 6. Fix `mkdocs serve --livereload` not triggering automatically -- **Issue**: [mkdocs/mkdocs#4055](https://github.com/mkdocs/mkdocs/issues/4055) -- **๐Ÿ‘**: 25 ยท ๐Ÿ’ฌ: 6 -- **Description**: In recent versions, livereload no longer works unless `--livereload` is passed explicitly. mkdocs-ng **partially** addresses this through PRs restoring `--livereload`, but some users still report it not working by default. This may intersect with the Click version issue (#4032) and WSL-specific problems (#4081). -- **Status in mkdocs-ng**: โœ… `--livereload` flag restored; default behaviour should be verified - -### 7. `mkdocs serve` does not watch files (Click โ‰ฅ 8.3.0 regression) -- **Issue**: [mkdocs/mkdocs#4032](https://github.com/mkdocs/mkdocs/issues/4032) -- **๐Ÿ‘**: 66 ยท ๐Ÿ’ฌ: 31 -- **Description**: Starting with Click 8.3.0, file watching breaks entirely โ€” changes no longer trigger a rebuild. Workaround is pinning `click<=8.2.1`. This is the highest-reaction open issue by far. -- **Status in mkdocs-ng**: needs verification โ€” `pyproject.toml` currently allows `click >=7.0`; CI pins to `8.1.8` for min-version tests, but the runtime constraint does not prevent 8.3.0. - ---- - -## โšก P1 โ€“ Important Features & Fixes - -### 8. Live reload triggers on editor temp / hidden files -- **Issue**: [mkdocs/mkdocs#2519](https://github.com/mkdocs/mkdocs/issues/2519) -- **๐Ÿ‘**: 7 ยท ๐Ÿ’ฌ: 18 -- **Description**: Editors like Vim create swap files (`.foo.md.swp`) and hidden files that cause `mkdocs serve` to constantly rebuild even though those files aren't included in the output. The watcher should ignore dot-files and editor temp files by default, with an opt-in mechanism for directories like `.well-known/`. -- **Labels**: `Command - serve`, `Configuration` - -### 9. Add `rel="external"` to outbound links -- **Issue**: [mkdocs/mkdocs#3914](https://github.com/mkdocs/mkdocs/issues/3914) -- **๐Ÿ‘**: 7 ยท ๐Ÿ’ฌ: 0 -- **Description**: External (absolute URL) links should be automatically annotated with `rel="external"` so theme authors and users can style them differently (e.g. add an external-link icon). This became more important after Material for MkDocs switched to always using absolute URLs for navigation. -- **Labels**: `Enhancement` - -### 10. Cache busting for static assets -- **Issue**: [mkdocs/mkdocs#1979](https://github.com/mkdocs/mkdocs/issues/1979) -- **๐Ÿ‘**: 5 ยท ๐Ÿ’ฌ: 34 -- **Description**: MkDocs has no built-in mechanism to append content hashes to CSS/JS filenames for cache busting. After a documentation site update, returning visitors may get stale cached assets. Implementation could be via a plugin (preferred by maintainers) or core feature. -- **Labels**: `Enhancement`, `Plugins` - -### 11. Decouple built-in search from core -- **Issue**: [mkdocs/mkdocs#3698](https://github.com/mkdocs/mkdocs/issues/3698) -- **๐Ÿ‘**: 5 ยท ๐Ÿ’ฌ: 8 -- **Description**: The search plugin (based on lunr.js) is bundled with core MkDocs. lunr.js is unmaintained (last commit ~4 years ago) with known bugs. Proposal: extract search into a standalone installable package, decouple it from the core release cycle, and pave the way for a modern replacement. -- **Labels**: `Search` - -### 12. Decouple built-in themes from core -- **Issue**: [mkdocs/mkdocs#3636](https://github.com/mkdocs/mkdocs/issues/3636) -- **๐Ÿ‘**: 4 ยท ๐Ÿ’ฌ: 17 -- **Description**: The core maintainers agreed to move the `readthedocs` theme (and possibly `mkdocs` theme) into separate repos and installable packages. This simplifies core, allows themes to be versioned independently, and opens the door for new default themes. -- **Labels**: `Cleanup` - -### 13. Support root directory as `docs_dir` -- **Issue**: [mkdocs/mkdocs#3450](https://github.com/mkdocs/mkdocs/issues/3450) / [PR #3519](https://github.com/mkdocs/mkdocs/pull/3519) -- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 15 -- **Description**: MkDocs currently forbids placing `mkdocs.yml` inside the `docs_dir`. Users who want to use the project root as `docs_dir` (e.g. monorepos, projects with `README.md` as homepage) need to work around this restriction. The PR #3519 removes the validation check and auto-excludes config/site files from the docs. -- **Labels**: `Navigation` - ---- - -## ๐Ÿ“‹ P2 โ€“ Nice to Have - -### 14. Support text fragment links (ignore them during validation) -- **Issue**: [mkdocs/mkdocs#3952](https://github.com/mkdocs/mkdocs/issues/3952) -- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 0 -- **Description**: [Text fragment links](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment/Text_fragments) (`#:~:text=โ€ฆ`) are a modern web standard for linking to specific text on a page. MkDocs' anchor validator incorrectly reports them as broken anchors. The validator should recognize and skip `#:~:text=` fragments. -- **Labels**: `Validation` - -### 15. Auto-switch port when the default port is busy -- **Issue**: [mkdocs/mkdocs#3496](https://github.com/mkdocs/mkdocs/issues/3496) -- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 0 -- **Description**: If port 8000 is already in use, `mkdocs serve` should automatically try the next available port (8001, 8002, โ€ฆ) instead of failing. A related PR (#3498) adds a manual port override flag, but automatic fallback is the desired UX. -- **Labels**: `Command - serve` - -### 16. Smart section titles when no nav is configured -- **Issue**: [mkdocs/mkdocs#3356](https://github.com/mkdocs/mkdocs/issues/3356) -- **๐Ÿ‘**: 3 ยท ๐Ÿ’ฌ: 6 -- **Description**: When no `nav` is defined in `mkdocs.yml`, section titles for sub-directories should be derived from the index page's title metadata or first heading, rather than displaying raw directory names. This is already a feature in Material for MkDocs (`navigation.smart-section-titles`), but should be available in core. -- **Labels**: `Navigation`, `Titles` - -### 17. Support GitHub-style Markdown Alerts -- **Issue**: [mkdocs/mkdocs#3997](https://github.com/mkdocs/mkdocs/issues/3997) -- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 2 -- **Description**: GitHub-flavored markdown alert blocks (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`) should render as styled callouts in MkDocs. This would improve portability of docs authored on GitHub to MkDocs sites. - -### 18. Extend `on_page_context` with Jinja2 Environment reference -- **Issue**: [mkdocs/mkdocs#3709](https://github.com/mkdocs/mkdocs/issues/3709) -- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 1 -- **Description**: The `on_page_context` plugin event should expose the Jinja2 `Environment` object so plugins can apply per-page template filters and globals. This is needed for multi-instance plugins (e.g. Material for MkDocs blog plugin) where each plugin instance needs to register its own template functions per page. - -### 19. Deprecated options should emit `INFO`, not `WARNING` -- **Issue**: [mkdocs/mkdocs#3696](https://github.com/mkdocs/mkdocs/issues/3696) -- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 5 -- **Description**: The `Deprecated` config helper emits `WARNING` messages, which break `--strict` mode. Since deprecated options are still functional (just discouraged), they should emit `INFO`-level messages so strict builds don't fail on deprecation notices alone. - -### 20. Custom import paths for `markdown_extensions` -- **Issue**: [mkdocs/mkdocs#3772](https://github.com/mkdocs/mkdocs/issues/3772) -- **๐Ÿ‘**: 1 ยท ๐Ÿ’ฌ: 29 -- **Description**: Users who write small project-specific Markdown extensions need a way to add the extension's directory to `sys.path` from within `mkdocs.yml`, without requiring `PYTHONPATH` hacks or pip-installable packages. A config option like `markdown_extensions_path: ["extensions/"]` would suffice. - -### 21. Respect display text when the same `.md` file appears in nav multiple times -- **Issue**: [mkdocs/mkdocs#3710](https://github.com/mkdocs/mkdocs/issues/3710) -- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 3 -- **Description**: When a file is referenced multiple times in `nav` with different display names (e.g. `- 'French Main Dishes': 'French Cuisine.md'` and `- 'French Desserts': 'French Cuisine.md'`), MkDocs now overrides both entries with the first title encountered. Previously, each entry kept its set display text. - ---- - -## ๐Ÿ”ง P3 โ€“ Maintenance & Infrastructure - -### 22. New default theme -- **Issue**: [mkdocs/mkdocs#3680](https://github.com/mkdocs/mkdocs/issues/3680) -- **๐Ÿ‘**: 0 ยท ๐Ÿ’ฌ: 6 -- **Description**: The default `mkdocs` theme is dated (Bootstrap 3). A new, modern, optionally installable default theme should be designed and shipped separately, as part of the theme decoupling effort (#3636). - -### 23. Title source precedence controls -- **Issue**: [mkdocs/mkdocs#3532](https://github.com/mkdocs/mkdocs/issues/3532) -- **๐Ÿ‘**: 0 ยท ๐Ÿ’ฌ: 37 -- **Description**: When a page has both a YAML `title` meta field and an H1 heading, the precedence between them (and the `nav` display name) can be surprising. Users want more control over which source wins, ideally configurable per page or globally. - -### 24. Fix `use_directory_urls: true` with Click โ‰ฅ 8.2.2 -- **Issue**: [mkdocs/mkdocs#4014](https://github.com/mkdocs/mkdocs/issues/4014) -- **๐Ÿ‘**: 7 ยท ๐Ÿ’ฌ: 5 -- **Description**: Click 8.2.2 changed path behavior that broke `use_directory_urls: true` โ€” generated links become `page/index.html` instead of `page/`. This is related to #4032 and may require pinning or fixing the Click integration. -- **Status in mkdocs-ng**: unknown โ€” needs testing with Click โ‰ฅ 8.2.2 - -### 25. WSL: `mkdocs serve` fails to live reload -- **Issue**: [mkdocs/mkdocs#4081](https://github.com/mkdocs/mkdocs/issues/4081) -- **๐Ÿ‘**: 2 ยท ๐Ÿ’ฌ: 2 -- **Description**: On WSL with ext4 filesystem, file-watching doesn't trigger livereload. May be related to the Click watcher regression (#4032) or filesystem notification limitations in WSL. - ---- - -*Last updated: 2026-04-29* -*Sources: [mkdocs/mkdocs open issues](https://github.com/mkdocs/mkdocs/issues), sorted by reactions*