diff --git a/README.md b/README.md
index 94a47e0b..e2050b70 100644
--- a/README.md
+++ b/README.md
@@ -30,9 +30,16 @@
Documentation ·
Switching from MkDocs ·
Release notes ·
- Plugin catalog
+ Plugin catalog
+**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
@@ -55,9 +62,8 @@ third-party themes, plugins, and Markdown extensions.
> [!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,
@@ -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
@@ -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
diff --git a/docs/about/comparison.md b/docs/about/comparison.md
index 69c7902b..cc2dab4f 100644
--- a/docs/about/comparison.md
+++ b/docs/about/comparison.md
@@ -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
@@ -21,7 +27,7 @@ If something here is wrong or out of date, please
| 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`
diff --git a/docs/about/contributing.md b/docs/about/contributing.md
index 0c7bc9cb..2d9dd81d 100644
--- a/docs/about/contributing.md
+++ b/docs/about/contributing.md
@@ -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"
diff --git a/docs/about/fixed-upstream-issues.md b/docs/about/fixed-upstream-issues.md
index fe5ec114..e8d39e96 100644
--- a/docs/about/fixed-upstream-issues.md
+++ b/docs/about/fixed-upstream-issues.md
@@ -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
diff --git a/docs/about/governance.md b/docs/about/governance.md
index 246f1ae1..c09827c0 100644
--- a/docs/about/governance.md
+++ b/docs/about/governance.md
@@ -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"
diff --git a/docs/about/license.md b/docs/about/license.md
index 44546d3c..4cd88d1a 100644
--- a/docs/about/license.md
+++ b/docs/about/license.md
@@ -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.
diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md
index 5fae93ba..36c1bbb1 100644
--- a/docs/about/release-notes.md
+++ b/docs/about/release-notes.md
@@ -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
---
diff --git a/docs/dev-guide/README.md b/docs/dev-guide/README.md
index 183365e0..6944b24b 100644
--- a/docs/dev-guide/README.md
+++ b/docs/dev-guide/README.md
@@ -1,3 +1,7 @@
+---
+description: "Documentation for developers of MkDocs themes and plugins."
+---
+
# Developer Guide
Extending MkDocs
diff --git a/docs/dev-guide/api.md b/docs/dev-guide/api.md
index bc2c85fd..9c8a1aff 100644
--- a/docs/dev-guide/api.md
+++ b/docs/dev-guide/api.md
@@ -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.
diff --git a/docs/dev-guide/plugins.md b/docs/dev-guide/plugins.md
index d3c9eb7b..405902db 100644
--- a/docs/dev-guide/plugins.md
+++ b/docs/dev-guide/plugins.md
@@ -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
diff --git a/docs/dev-guide/themes.md b/docs/dev-guide/themes.md
index d3cdacc7..72ab5a5c 100644
--- a/docs/dev-guide/themes.md
+++ b/docs/dev-guide/themes.md
@@ -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.
diff --git a/docs/dev-guide/translations.md b/docs/dev-guide/translations.md
index 3fdeaace..3f4cc70d 100644
--- a/docs/dev-guide/translations.md
+++ b/docs/dev-guide/translations.md
@@ -1,3 +1,7 @@
+---
+description: "How to add or update translations of the built-in MkDocs themes."
+---
+
# Translations
Theme localization guide.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 16afbc95..2614aa6e 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -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!
diff --git a/docs/hooks.py b/docs/hooks.py
index 76e4ac4b..b736bf90 100644
--- a/docs/hooks.py
+++ b/docs/hooks.py
@@ -28,6 +28,7 @@
ISSUE_REF_RE = re.compile(r"(?\d+)\b")
VERSION_EXAMPLE_RE = re.compile(r"mkdocs, version \S+ from")
COMPAT_CASES_MARKER = ""
+MARKDOWN_SNIPPET_RE = re.compile(r'^--8<-- "([^"]+\.md)"[ \t]*$', re.MULTILINE)
COMPAT_CASES_PATH = Path(__file__).resolve().parents[1] / "compat" / "cases.yaml"
@@ -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))
@@ -176,3 +188,5 @@ def replacement(m: re.Match) -> str:
markdown,
flags=re.MULTILINE,
)
+
+ return markdown
diff --git a/docs/img/social.png b/docs/img/social.png
new file mode 100644
index 00000000..4f575c29
Binary files /dev/null and b/docs/img/social.png differ
diff --git a/docs/index.md b/docs/index.md
index 205fd0c7..4d40e250 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -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.
*Ship docs.*"
@@ -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/}
diff --git a/docs/robots.txt b/docs/robots.txt
new file mode 100644
index 00000000..1fe8e388
--- /dev/null
+++ b/docs/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://mkdocs-ng.org/sitemap.xml
diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md
index c2250492..be12f998 100644
--- a/docs/user-guide/README.md
+++ b/docs/user-guide/README.md
@@ -1,3 +1,7 @@
+---
+description: "The MkDocs NG user guide: installing, writing, theming, configuring and deploying your documentation."
+---
+
# User Guide
Building Documentation with MkDocs
@@ -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)
diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md
index aef92e30..5e4ff14f 100644
--- a/docs/user-guide/choosing-your-theme.md
+++ b/docs/user-guide/choosing-your-theme.md
@@ -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.
diff --git a/docs/user-guide/cli.md b/docs/user-guide/cli.md
index 987c1382..a0ece335 100644
--- a/docs/user-guide/cli.md
+++ b/docs/user-guide/cli.md
@@ -1,3 +1,7 @@
+---
+description: "Every mkdocs command and option: new, serve, build, gh-deploy and get-deps."
+---
+
# Command Line Interface
::: mkdocs-click
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 29132f50..67a1f7d2 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -1,3 +1,7 @@
+---
+description: "Every setting you can use in mkdocs.yml, with defaults and examples."
+---
+
# Configuration
Guide to all available configuration settings.
diff --git a/docs/user-guide/customizing-your-theme.md b/docs/user-guide/customizing-your-theme.md
index 87093d1a..ed116742 100644
--- a/docs/user-guide/customizing-your-theme.md
+++ b/docs/user-guide/customizing-your-theme.md
@@ -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.
diff --git a/docs/user-guide/deploying-your-docs.md b/docs/user-guide/deploying-your-docs.md
index 3eef2d0a..44a15e21 100644
--- a/docs/user-guide/deploying-your-docs.md
+++ b/docs/user-guide/deploying-your-docs.md
@@ -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
diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
index 233bd57c..c5972708 100644
--- a/docs/user-guide/installation.md
+++ b/docs/user-guide/installation.md
@@ -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.
diff --git a/docs/user-guide/is-mkdocs-still-maintained.md b/docs/user-guide/is-mkdocs-still-maintained.md
new file mode 100644
index 00000000..8c3c6c57
--- /dev/null
+++ b/docs/user-guide/is-mkdocs-still-maintained.md
@@ -0,0 +1,114 @@
+---
+description: "Upstream MkDocs 1.x has had no release since August 2024, and MkDocs 2.0 is an incompatible rewrite. What that means for your site, and the maintained ways to keep it building."
+---
+
+# Is MkDocs Still Maintained?
+
+The state of MkDocs today, and what it means for your site.
+
+---
+
+Short answer: **upstream MkDocs 1.x is no longer developed.** Its last release
+is 1.6.1, from 2024-08-30. Upstream work moved to MkDocs 2.0, a rewrite that
+can't build existing sites. Your site keeps building on 1.6.1 for now, and
+[MkDocs NG](#what-is-mkdocs-ng) continues 1.x with the same `mkdocs` command,
+`mkdocs.yml`, plugins and themes.
+
+Facts on this page were checked on 2026-11-14 against the PyPI release history
+and documentation of each project; see [Sources](#sources). If something here
+is wrong or out of date, please [open an issue].
+
+## What is the state of MkDocs 1.x?
+
+There has been no release of MkDocs 1.x since 1.6.1 on 2024-08-30.
+`pip install mkdocs` still installs it, and sites, plugins and themes built
+for it keep working. Bugs reported since then stay unfixed, and 1.6.1 declares
+support for Python 3.8 to 3.12 only. Many of the bugs that stayed open
+upstream are listed, with their fixes, in
+[Fixed Upstream Issues](../about/fixed-upstream-issues.md).
+
+## What is MkDocs 2.0?
+
+MkDocs 2.0 is a rewrite, published as pre-releases of the `mkdocs` package
+since 2026-08-28; the latest is 2.0.dev6, from 2026-09-15. It has no
+configuration file, plugins or themes: it builds a folder of Markdown files
+with one Jinja template, and stops with an error when it finds a
+`mkdocs.yml`. Existing sites can't be built with it.
+
+Because these are pre-releases, `pip install mkdocs` doesn't install them.
+`pip install --pre mkdocs` and `uv --prerelease allow` do, so avoid those in
+the environment you build your site in.
+
+## Will my site stop building?
+
+Not today. With `mkdocs` pinned below 2.0, for example `mkdocs<2`, your site
+keeps building as it does now. What it doesn't get on 1.6.1 is fixes: for
+bugs, for new Python versions, and for new versions of Python-Markdown, Jinja
+and the other libraries it uses. The longer a site stays on 1.6.1, the more
+likely one of those breaks it.
+
+## Is Material for MkDocs still maintained?
+
+Material for MkDocs is in maintenance mode, with critical fixes and security
+updates until its end of life on 2027-05-05. Its team now develops Zensical.
+[Material for MkDocs End of Life](material-end-of-life.md) lists your options,
+including MkDocs NG Material, which keeps the `material` theme maintained
+after that date.
+
+## What are the alternatives to MkDocs?
+
+For an existing MkDocs site, these are the ways forward:
+
+Project | What it is | Runs MkDocs plugins | Latest release
+--- | --- | --- | ---
+[MkDocs NG](#what-is-mkdocs-ng) | Maintained fork of MkDocs 1.x, same `mkdocs` command | Yes | 1.11.2 (2026-11-11)
+[ProperDocs] | Fork of MkDocs 1.6, with its own `properdocs` command | Yes | 1.6.7 (2026-03-20)
+[Zensical] | New generator from the team behind Material for MkDocs | No; reimplements about 30 popular plugins | 0.1.1 (2026-11-10)
+MkDocs 1.6.1 | The last upstream 1.x release | Yes | 1.6.1 (2024-08-30)
+
+[MkDocs Alternatives Compared](../about/comparison.md) compares them in detail,
+with build times, and says which one suits which site.
+
+## What is MkDocs NG?
+
+MkDocs NG is a maintained fork of MkDocs 1.x, published on PyPI as
+`mkdocs-ng`. It keeps the `mkdocs` command, `mkdocs.yml`, `import mkdocs` and
+the plugin and theme APIs, so switching is a package change:
+
+```bash
+pip install mkdocs-ng
+```
+
+* **Your plugins keep working.** Every change is tested by building sites
+ with around 30 popular plugins, themes and Markdown extensions.
+* **Regular releases.** Nine releases since April 2026, the latest on
+ 2026-11-11; see the [release notes](../about/release-notes.md).
+* **A dated support promise.** MkDocs NG 1.x gets bug, security and
+ compatibility fixes until at least 2028-12-31; see
+ [Versioning and support](../about/release-notes.md#versioning-and-support).
+* **Current Python.** It supports Python 3.10 to 3.15.
+* **Open governance.** Who maintains it, how decisions are made and what
+ happens if a maintainer steps away is written down in
+ [Governance](../about/governance.md).
+
+To try it on your site before you change anything, see
+[Switching to MkDocs NG](migrating.md#try-it-first). Switching back is the
+same one-line change.
+
+## Sources
+
+* PyPI release history:
+ [mkdocs](https://pypi.org/project/mkdocs/#history),
+ [mkdocs-ng](https://pypi.org/project/mkdocs-ng/#history),
+ [properdocs](https://pypi.org/project/properdocs/#history),
+ [zensical](https://pypi.org/project/zensical/#history).
+* MkDocs 2.0: the [package description](https://pypi.org/project/mkdocs/2.0.dev6/)
+ and the source code of 2.0.dev6.
+* Material for MkDocs maintenance:
+ [upcoming changes](https://zensical.org/upcoming-changes/#material-for-mkdocs).
+* Zensical:
+ [MkDocs plugin support](https://zensical.org/docs/compatibility/mkdocs/plugins/).
+
+[open an issue]: https://github.com/mkdocs-ng/mkdocs/issues
+[ProperDocs]: https://properdocs.org/
+[Zensical]: https://zensical.org/
diff --git a/docs/user-guide/localizing-your-theme.md b/docs/user-guide/localizing-your-theme.md
index 279f4a8e..82c1959e 100644
--- a/docs/user-guide/localizing-your-theme.md
+++ b/docs/user-guide/localizing-your-theme.md
@@ -1,3 +1,7 @@
+---
+description: "Show the text of your MkDocs theme, such as search and navigation labels, in your site's language."
+---
+
# Localizing Your Theme
Display your theme in your preferred language.
diff --git a/docs/user-guide/material-end-of-life.md b/docs/user-guide/material-end-of-life.md
index 1c226467..151d40bd 100644
--- a/docs/user-guide/material-end-of-life.md
+++ b/docs/user-guide/material-end-of-life.md
@@ -1,3 +1,7 @@
+---
+description: "Material for MkDocs reaches end of life on 2027-05-05. Your options: MkDocs NG Material, Zensical, MaterialX or Sumi, and who each one suits."
+---
+
# Material for MkDocs End of Life
Your options when Material for MkDocs stops being maintained.
@@ -127,7 +131,7 @@ Your site needs no changes.
dependencies).
* MkDocs NG Material: [documentation][ng-material] and
[PyPI page][ng-material-pypi].
-* [MkDocs NG and its alternatives](../about/comparison.md) compares the
+* [MkDocs Alternatives Compared](../about/comparison.md) compares the
build tools.
[open an issue]: https://github.com/mkdocs-ng/mkdocs/issues
diff --git a/docs/user-guide/migrating.md b/docs/user-guide/migrating.md
index ea5f5482..24ed5478 100644
--- a/docs/user-guide/migrating.md
+++ b/docs/user-guide/migrating.md
@@ -1,3 +1,7 @@
+---
+description: "Move an existing MkDocs site to MkDocs NG. It keeps the mkdocs command, mkdocs.yml, plugins and themes, so switching is a package change."
+---
+
# Switching to MkDocs NG
Move an existing MkDocs site to MkDocs NG.
diff --git a/docs/user-guide/multi-language-sites.md b/docs/user-guide/multi-language-sites.md
index 43a86161..1e25cd57 100644
--- a/docs/user-guide/multi-language-sites.md
+++ b/docs/user-guide/multi-language-sites.md
@@ -1,3 +1,7 @@
+---
+description: "Publish your documentation in several languages from one mkdocs.yml with MkDocs NG's languages setting."
+---
+
# Multi-language Sites
Publish your documentation in several languages from one `mkdocs.yml`.
diff --git a/docs/user-guide/python-api.md b/docs/user-guide/python-api.md
index 71b438b0..7dad81e1 100644
--- a/docs/user-guide/python-api.md
+++ b/docs/user-guide/python-api.md
@@ -1,3 +1,7 @@
+---
+description: "Build and serve MkDocs sites from Python with mkdocs.build() and mkdocs.serve(), for CI scripts and build tool integrations."
+---
+
# Python API
MkDocs can be used as a Python library in addition to a command-line tool.
diff --git a/docs/user-guide/versioned-docs.md b/docs/user-guide/versioned-docs.md
index 099d7480..eec17013 100644
--- a/docs/user-guide/versioned-docs.md
+++ b/docs/user-guide/versioned-docs.md
@@ -1,3 +1,7 @@
+---
+description: "Keep the docs of older releases online with mike, with a menu to switch between versions."
+---
+
# Versioned Docs
Keep the docs of older releases online, with a menu to switch between versions.
diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md
index 08982150..fce7e03e 100644
--- a/docs/user-guide/writing-your-docs.md
+++ b/docs/user-guide/writing-your-docs.md
@@ -1,3 +1,7 @@
+---
+description: "How to lay out your Markdown files, link between pages, add images and use the Markdown that MkDocs supports."
+---
+
# Writing your docs
How to layout and write your Markdown source files.
diff --git a/mkdocs.yml b/mkdocs.yml
index 81042683..7ad0e9f9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,6 +11,8 @@ theme:
logo: img/logo.svg
logo_dark: img/logo-dark.svg
favicon: img/favicon.svg
+ # Shown when a page is shared on social media.
+ social_image: img/social.png
# Brand blue; docs/css/extra.css sets a lighter blue for the dark palette.
accent: "#0061fe"
@@ -22,7 +24,7 @@ nav:
- About:
- Release Notes: about/release-notes.md
- Fixed Upstream Issues: about/fixed-upstream-issues.md
- - Comparison: about/comparison.md
+ - MkDocs Alternatives: about/comparison.md
- Contributing: about/contributing.md
- Governance: about/governance.md
- License: about/license.md
diff --git a/mkdocs/tests/docs_hooks_tests.py b/mkdocs/tests/docs_hooks_tests.py
index 060d0ca7..9423213d 100644
--- a/mkdocs/tests/docs_hooks_tests.py
+++ b/mkdocs/tests/docs_hooks_tests.py
@@ -39,6 +39,16 @@ def test_version_example_tracks_current_release(self):
self.assertIn(f"mkdocs, version {mkdocs.__version__} from", result)
self.assertNotIn("version 0.0.0", result)
+ def test_markdown_snippets_are_inlined(self):
+ root = Path(__file__).resolve().parents[2]
+ markdown = (
+ '--8<-- ".github/GOVERNANCE.md"\n\n--8<-- "docs/img/plugin-events.svg"\n'
+ )
+ result = self.hooks._inline_markdown_snippets(markdown, root)
+ self.assertTrue(result.startswith("# Governance\n"))
+ self.assertNotIn('--8<-- ".github/GOVERNANCE.md"', result)
+ self.assertIn('--8<-- "docs/img/plugin-events.svg"', result)
+
def test_compat_cases_list_links_each_case_to_pypi(self):
cases = [
{"name": "mkdocstrings-python", "install": ["mkdocstrings[python]"]},
diff --git a/pyproject.toml b/pyproject.toml
index 6307fe19..231a02d9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,6 +6,15 @@ build-backend = "hatchling.build"
name = "mkdocs-ng"
description = "Write Markdown. Ship docs. The maintained MkDocs that keeps your plugins working."
readme = "README.md"
+keywords = [
+ "mkdocs",
+ "documentation",
+ "static site generator",
+ "markdown",
+ "docs",
+ "mkdocs fork",
+ "mkdocs alternative",
+]
license = "BSD-2-Clause"
authors = [
{name = "Tom Christie", email = "tom@tomchristie.com"},