Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,16 @@
<a href="https://mkdocs-ng.org/">Documentation</a> ·
<a href="https://mkdocs-ng.org/user-guide/migrating/">Switching from MkDocs</a> ·
<a href="https://mkdocs-ng.org/about/release-notes/">Release notes</a> ·
<a href="https://github.com/mkdocs-ng/catalog">Plugin catalog</a>
<a href="https://catalog.mkdocs-ng.org/">Plugin catalog</a>
</p>

**MkDocs NG** is the maintained fork of [MkDocs][mkdocs/mkdocs] 1.x. Upstream
MkDocs has had no 1.x release since August 2024, and its 2.0 rewrite can't
build existing sites. MkDocs NG keeps the `mkdocs` command, `mkdocs.yml`,
plugins and themes working, with bug, security and compatibility fixes until at
least 2028-12-31. See [Is MkDocs still maintained?][is-maintained] and
[MkDocs alternatives compared][comparison].

MkDocs is a **fast**, **simple**, and **downright gorgeous** static site
generator that's geared towards building project documentation. Documentation
source files are written in Markdown and configured with a single YAML
Expand All @@ -55,9 +62,8 @@ third-party themes, plugins, and Markdown extensions.
</p>

> [!NOTE]
> **MkDocs NG** is a maintained fork of [mkdocs/mkdocs], published on PyPI as
> `mkdocs-ng` while keeping the `mkdocs` command, imports and configuration
> unchanged — a drop-in replacement.
> **MkDocs NG** is published on PyPI as `mkdocs-ng` while keeping the `mkdocs`
> command, imports and configuration unchanged — a drop-in replacement.
>
> Highlights beyond the last upstream release: Python 3.10–3.15 support,
> built-in `llms.txt` and per-page Markdown output for LLMs and coding agents,
Expand Down Expand Up @@ -118,7 +124,8 @@ first, but they are still welcome in [Discussions].
- [Fixed Upstream Issues][fixed-upstream]
- [Switching to MkDocs NG][migrating]
- [Governance and how long 1.x is supported][governance]
- [Comparison with upstream MkDocs 2.0, ProperDocs and Zensical][comparison]
- [Is MkDocs still maintained?][is-maintained]
- [MkDocs alternatives compared: MkDocs NG, MkDocs 2.0, ProperDocs and Zensical][comparison]
- [Catalog of third-party plugins, themes and recipes][catalog]
- [Sumi][sumi], a local-first documentation theme from the MkDocs NG project
- [MkDocs NG Material][ng-material], Material for MkDocs maintained for MkDocs NG
Expand All @@ -145,12 +152,13 @@ discussion forums are expected to follow the [PyPA Code of Conduct].
[plugins-install]: https://mkdocs-ng.org/user-guide/installation/#plugins-themes-and-the-mkdocs-package
[migrating]: https://mkdocs-ng.org/user-guide/migrating/
[comparison]: https://mkdocs-ng.org/about/comparison/
[is-maintained]: https://mkdocs-ng.org/user-guide/is-mkdocs-still-maintained/
[governance]: https://mkdocs-ng.org/about/governance/
[Contributing Guide]: https://mkdocs-ng.org/about/contributing/
[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
[catalog]: https://github.com/mkdocs-ng/catalog
[sumi]: https://github.com/mkdocs-ng/mkdocs-sumi
[ng-material]: https://github.com/mkdocs-ng/mkdocs-material
[catalog]: https://catalog.mkdocs-ng.org/
[sumi]: https://sumi.mkdocs-ng.org/
[ng-material]: https://material.mkdocs-ng.org/

## License

Expand Down
24 changes: 15 additions & 9 deletions docs/about/comparison.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
# MkDocs NG and Its Alternatives
---
description: "MkDocs NG, ProperDocs, Zensical, MkDocs 1.6 and MkDocs 2.0 compared: which ones run your plugins and themes, how fast they build, and which one to use."
---

# MkDocs Alternatives Compared

How MkDocs NG relates to the other tools that build MkDocs sites.
MkDocs NG, ProperDocs, Zensical and upstream MkDocs, side by side.

---

Since upstream MkDocs 1.x stopped being developed, several projects have
offered a way forward for existing MkDocs sites. This page compares them on
what matters when you already have a site: whether it keeps building
unchanged, and whether your plugins keep running.
Since upstream MkDocs 1.x stopped being developed (see
[Is MkDocs Still Maintained?](../user-guide/is-mkdocs-still-maintained.md)),
several projects have offered a way forward for existing MkDocs sites. This
page compares them on what matters when you already have a site: whether it
keeps building unchanged, and whether your plugins keep running.

Facts on this page were checked on 2026-11-01 against each project's PyPI
release history, documentation and source code; see [Sources](#sources).
Facts on this page were checked on 2026-11-01, and release versions on
2026-11-14, against each project's PyPI release history, documentation and
source code; see [Sources](#sources).
Build times were measured on 2026-11-04.
Projects change quickly, so check their documentation for the current state.
If something here is wrong or out of date, please
Expand All @@ -21,7 +27,7 @@ If something here is wrong or out of date, please
&nbsp; | MkDocs NG | MkDocs 1.6 | MkDocs 2.0 pre-releases | ProperDocs | Zensical
--- | --- | --- | --- | --- | ---
What it is | Maintained fork of MkDocs 1.x | Last upstream 1.x release | Upstream rewrite | Fork of MkDocs 1.6 | New generator by the Material for MkDocs team
Latest release | 1.11.0 (2026-11-04) | 1.6.1 (2024-08-30) | 2.0.dev6 (2026-09-15) | 1.6.7 (2026-03-20) | 0.0.74 (2026-10-30)
Latest release | 1.11.2 (2026-11-11) | 1.6.1 (2024-08-30) | 2.0.dev6 (2026-09-15) | 1.6.7 (2026-03-20) | 0.1.1 (2026-11-10)
PyPI package | `mkdocs-ng` | `mkdocs` | `mkdocs` (`--pre`) | `properdocs` | `zensical`
Command | `mkdocs` | `mkdocs` | `mkdocs` | `properdocs` | `zensical`
Configuration | `mkdocs.yml` | `mkdocs.yml` | None; refuses to run when `mkdocs.yml` exists | `properdocs.yml`, falls back to `mkdocs.yml` | `mkdocs.yml` or `zensical.toml`
Expand Down
4 changes: 4 additions & 0 deletions docs/about/contributing.md
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
---
description: "How to report bugs, propose changes and send pull requests to MkDocs NG, the maintained fork of MkDocs 1.x."
---

--8<-- ".github/CONTRIBUTING.md"
4 changes: 4 additions & 0 deletions docs/about/fixed-upstream-issues.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Long-standing upstream MkDocs bugs that are fixed in MkDocs NG, with the release that fixed each one. Upgrading is a one-line change."
---

# Upstream Issues Fixed in MkDocs NG

MkDocs NG is a maintained fork of [mkdocs/mkdocs], which is no longer under
Expand Down
4 changes: 4 additions & 0 deletions docs/about/governance.md
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
---
description: "Who maintains MkDocs NG, how decisions are made, how releases are published and what happens if a maintainer steps away."
---

--8<-- ".github/GOVERNANCE.md"
4 changes: 4 additions & 0 deletions docs/about/license.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "MkDocs NG is open source under the BSD 2-Clause license. Licenses of the projects it includes."
---

# License

The legal stuff.
Expand Down
4 changes: 4 additions & 0 deletions docs/about/release-notes.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Release notes for every MkDocs NG version, and the versioning and support rules: MkDocs NG 1.x gets fixes until at least 2028-12-31."
---

# Release Notes

---
Expand Down
4 changes: 4 additions & 0 deletions docs/dev-guide/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Documentation for developers of MkDocs themes and plugins."
---

# Developer Guide

Extending MkDocs
Expand Down
4 changes: 4 additions & 0 deletions docs/dev-guide/api.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Reference for the MkDocs Python API used by plugins, themes and scripts: configuration, files, pages, navigation and build functions."
---

# API reference

NOTE: The main entry point to the API is through [Events](plugins.md#events) that are received by plugins. These events' descriptions link back to this page.
Expand Down
4 changes: 4 additions & 0 deletions docs/dev-guide/plugins.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "How to install, use and write MkDocs plugins, with every plugin event and the order in which they run."
---

# MkDocs Plugins

A Guide to installing, using and creating MkDocs Plugins
Expand Down
4 changes: 4 additions & 0 deletions docs/dev-guide/themes.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "How to create, package and distribute a custom MkDocs theme, with the template variables themes can use."
---

# Developing Themes

A guide to creating and distributing custom themes.
Expand Down
4 changes: 4 additions & 0 deletions docs/dev-guide/translations.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "How to add or update translations of the built-in MkDocs themes."
---

# Translations

Theme localization guide.
Expand Down
4 changes: 4 additions & 0 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Install MkDocs NG, create a site, preview it as you write and build it, in a few minutes."
---

# Getting Started with MkDocs

An introductory tutorial!
Expand Down
14 changes: 14 additions & 0 deletions docs/hooks.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
ISSUE_REF_RE = re.compile(r"(?<![\w/`\[])#(?P<number>\d+)\b")
VERSION_EXAMPLE_RE = re.compile(r"mkdocs, version \S+ from")
COMPAT_CASES_MARKER = "<!-- compat-cases -->"
MARKDOWN_SNIPPET_RE = re.compile(r'^--8<-- "([^"]+\.md)"[ \t]*$', re.MULTILINE)
COMPAT_CASES_PATH = Path(__file__).resolve().parents[1] / "compat" / "cases.yaml"


Expand Down Expand Up @@ -149,9 +150,20 @@ def on_config(config: MkDocsConfig) -> None:
_fix_cli_page_defaults()


def _inline_markdown_snippets(markdown: str, root: Path) -> str:
# Pages that only include a Markdown file from the repository, such as
# .github/GOVERNANCE.md, get its text here instead of through
# pymdownx.snippets, so that their Markdown copy for llms.txt has it too.
return MARKDOWN_SNIPPET_RE.sub(
lambda m: Path(root, m[1]).read_text(encoding="utf-8"), markdown
)


def on_page_markdown(
markdown: str, page: Page, config: MkDocsConfig, **kwargs
) -> str | None:
markdown = _inline_markdown_snippets(markdown, Path(config.config_file_path).parent)

if page.file.src_uri == "about/release-notes.md":
return _rewrite_release_notes_links(_update_version_example(markdown))

Expand All @@ -176,3 +188,5 @@ def replacement(m: re.Match) -> str:
markdown,
flags=re.MULTILINE,
)

return markdown
Binary file added docs/img/social.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
template: landing.html
title: MkDocs NG
description: Write Markdown. Ship docs. The maintained MkDocs that keeps your plugins working.
description: "Write Markdown. Ship docs. MkDocs NG is the maintained fork of MkDocs 1.x: same mkdocs command, same mkdocs.yml, and your plugins and themes keep working."
hero:
eyebrow: "MkDocs NG"
title: "Write Markdown.<br>*Ship docs.*"
Expand Down Expand Up @@ -77,7 +77,7 @@ sections:
reverse: true
eyebrow: Already on MkDocs?
title: Switching is a package change.
text: "MkDocs NG keeps the `mkdocs` command, imports and configuration. Your plugins and themes keep working, and bugs that stayed open upstream are fixed. See [how it compares](about/comparison/) to the alternatives."
text: "MkDocs NG keeps the `mkdocs` command, imports and configuration. Your plugins and themes keep working, and bugs that stayed open upstream are fixed. Wondering [whether MkDocs is still maintained](user-guide/is-mkdocs-still-maintained/)? See [how MkDocs NG compares](about/comparison/) to the alternatives."
actions:
- {text: Switching to MkDocs NG, link: user-guide/migrating/, primary: true}
- {text: Fixed upstream issues, link: about/fixed-upstream-issues/}
Expand Down
4 changes: 4 additions & 0 deletions docs/robots.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
User-agent: *
Allow: /

Sitemap: https://mkdocs-ng.org/sitemap.xml
5 changes: 5 additions & 0 deletions docs/user-guide/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "The MkDocs NG user guide: installing, writing, theming, configuring and deploying your documentation."
---

# User Guide

Building Documentation with MkDocs
Expand All @@ -10,6 +14,7 @@ page listed below, or use the *next* and *previous* buttons in the navigation
bar at the top of the page to move through the documentation in order.

- [Installation](installation.md)
- [Is MkDocs Still Maintained?](is-mkdocs-still-maintained.md)
- [Switching to MkDocs NG](migrating.md)
- [Material for MkDocs End of Life](material-end-of-life.md)
- [Writing Your Docs](writing-your-docs.md)
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/choosing-your-theme.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "The built-in mkdocs and readthedocs themes, the Sumi theme and third-party themes, and how to choose and configure one."
---

# Choosing your Theme

Selecting and configuring a theme.
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/cli.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Every mkdocs command and option: new, serve, build, gh-deploy and get-deps."
---

# Command Line Interface

::: mkdocs-click
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/configuration.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Every setting you can use in mkdocs.yml, with defaults and examples."
---

# Configuration

Guide to all available configuration settings.
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/customizing-your-theme.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Change an existing MkDocs theme with extra CSS and JavaScript, or override its templates, without building a theme from scratch."
---

# Customizing Your Theme

Altering a theme to suit your needs.
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/deploying-your-docs.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Deploy an MkDocs site to GitHub Pages, Read the Docs or any host that serves static files."
---

# Deploying your docs

A basic guide to deploying your docs to various hosting providers
Expand Down
4 changes: 4 additions & 0 deletions docs/user-guide/installation.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: "Install MkDocs NG with pip or uv, and how it works alongside the upstream mkdocs package that plugins and themes depend on."
---

# MkDocs Installation

A detailed guide.
Expand Down
Loading
Loading