MkDocs-NG Feature Plan

[shenxianpeng]

Curated from mkdocs/mkdocs issues and
discussions, sorted by user demand
(reactions 👍 + comments). Items already addressed by mkdocs-ng are excluded.

See also the Fixed Upstream Issues doc page for the full list of resolved upstream issues (including ones not originally tracked here).

---

🔥 P0 – High Demand / Urgent Bugs

1. Remove CDNs from built-in themes ✅ Done

• Issue: mkdocs/mkdocs#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
• Status in mkdocs-ng: ✅ Fixed in 1.8.0 (Vendor highlight.js in built-in themes (no more CDN) #75) — highlight.js is now bundled locally; no CDN references remain in either built-in theme.

2. Improve mkdocs serve performance & authoring experience 🚧 In progress

• Issue: mkdocs/mkdocs#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.
• Status in mkdocs-ng: 🚧 Not yet optimized. A CodSpeed continuous-benchmarking suite was added (Add CodSpeed continuous benchmarking #88, Add scaling and serve-loop benchmarks to the CodSpeed suite #89) to establish a measured baseline before changing the build/serve pipeline; a local scaling study showed superlinear cost growth (7.8 → 9.3 → 22.1 ms/page at 100/400/1600 pages), confirming the O(N²) navigation-rendering issue this ticket describes. Optimization work is next.

3. Stable public Python API ✅ Done

• Issue: mkdocs/mkdocs#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
• Status in mkdocs-ng: ✅ Fixed in 1.8.0 (Add stable public Python API (mkdocs.build / mkdocs.serve) #76) — mkdocs.build() and mkdocs.serve() are now the documented public API.

4. Remove hardcoded Google Analytics from theme ✅ Done

• Issue: mkdocs/mkdocs#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
• Status in mkdocs-ng: ✅ Fixed in 1.8.0 (Remove legacy Universal Analytics snippet from built-in themes #84) — the legacy Universal Analytics snippet is removed from both built-in themes; use theme.analytics.gtag (GA4) or override the analytics template block.

5. Support multiple INHERIT configs

• Issue: mkdocs/mkdocs#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 ✅ Done

• Issue: mkdocs/mkdocs#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: ✅ Fixed in 1.7.0 (Fix CLI livereload option and CI failures in tests #4) and 1.7.3 (Fix Click default option handling #60) — the root cause was Click's default-value handling breaking with Click ≥8.2, not livereload itself. Verified: a bare mkdocs serve (no flags) now watches, rebuilds and reloads the browser by default.

7. mkdocs serve does not watch files (Click ≥ 8.3.0 regression) ✅ Done

• Issue: mkdocs/mkdocs#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: ✅ Fixed in 1.7.0 (Fix CLI livereload option and CI failures in tests #4) and 1.7.3 (Fix Click default option handling #60) by correcting Click's default-value handling directly, so no upper pin on click is needed. Verified against Click 8.4.2 (latest at time of writing).

---

⚡ P1 – Important Features & Fixes

8. Live reload triggers on editor temp / hidden files ✅ Done

• Issue: mkdocs/mkdocs#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
• Status in mkdocs-ng: ✅ Fixed in 1.7.3 (Fix/livereload ignore temp files #55) — vim swap files, ~ backups and Emacs auto-save files no longer trigger rebuilds.

9. Add rel="external" to outbound links

• Issue: mkdocs/mkdocs#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
• 👍: 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
• 👍: 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
• 👍: 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 / PR #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
• 👍: 3 · 💬: 0
• Description: Text fragment links (#:~: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
• 👍: 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 ✅ Done

• Issue: mkdocs/mkdocs#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
• Status in mkdocs-ng: ✅ Fixed in 1.8.0 (Use index page titles for auto-generated section names #54) — auto-generated section titles now use the index page's title instead of the raw directory name when an index page exists.

17. Support GitHub-style Markdown Alerts

• Issue: mkdocs/mkdocs#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
• 👍: 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
• 👍: 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
• 👍: 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
• 👍: 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
• 👍: 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
• 👍: 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 ✅ Done

• Issue: mkdocs/mkdocs#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: ✅ Fixed in 1.7.3 (Fix Click default option handling #60), same Click default-value handling fix as Add Dependabot configuration for updates #6/Add Release Drafter workflow configuration #7. Verified against Click 8.4.2.

25. WSL: mkdocs serve fails to live reload ✅ Done

• Issue: mkdocs/mkdocs#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.
• Status in mkdocs-ng: ✅ Fixed in 1.7.0 (Fix CLI livereload option and CI failures in tests #4) / 1.7.3 (Fix Click default option handling #60) — investigated directly: the reporter's own diagnosis (ext4, inotifywait sees events fine, explicit --livereload works) matches the Click default-handling regression, not a WSL/filesystem-specific bug. The bundled PollingObserver file watcher doesn't depend on inotify anyway. Verified end-to-end with Click 8.4.2: a bare mkdocs serve watches, rebuilds and reloads the browser.

---

Last updated: 2026-08-12 — 9 items marked done, 1 in progress
Sources: mkdocs/mkdocs open issues, sorted by reactions