Skip to content

Answer "is MkDocs still maintained?" and make every page findable - #183

Merged
shenxianpeng merged 2 commits into
mainfrom
claude/project-thread-x15zqw
Nov 14, 2026
Merged

shenxianpeng merged 2 commits into
mainfrom
claude/project-thread-x15zqw

Conversation

@shenxianpeng

@shenxianpeng shenxianpeng commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

People looking for a way forward search for "is MkDocs still maintained", "is MkDocs dead" or "MkDocs alternative", and AI assistants answer from pages that say exactly that. The site had the comparison and the Material end-of-life pages, but no page that answers the first question, every page shared one generic meta description, and there was no robots.txt or share image.

What changes

New page: Is MkDocs Still Maintained? (User Guide, after Installation)

  • Question headings with the answer in the first sentence: state of 1.x, what 2.0 is, will my site stop building, is Material maintained, what are the alternatives, what is MkDocs NG.
  • Facts checked on 2026-11-14 against PyPI and the projects' docs, with a Sources section. Alternatives are stated plainly (ProperDocs and Zensical included); NG's part only lists public promises: regular releases, fixes until 2028-12-31, governance.

Comparison page retitled "MkDocs Alternatives Compared" (nav "MkDocs Alternatives"), latest releases updated to NG 1.11.2 and Zensical 0.1.1. The benchmark tables are unchanged.

Metadata

  • Every page gets its own description front matter. Sumi uses it for the meta, Open Graph and Twitter tags, and llms_txt lists it next to each page in llms.txt.
  • docs/robots.txt with the sitemap (it was a 404).
  • theme.social_image: links shared on chat apps and social media show the MkDocs NG card.
  • The Markdown copies of Governance and Contributing only held the --8<-- snippet line, so agents reading governance.md saw nothing. docs/hooks.py now inlines included .md files (with a test).

README / PyPI: the first paragraph says what MkDocs NG is and why it exists, linking the new page and the comparison; catalog, Sumi and NG Material links go to their sites instead of the repos; keywords added to pyproject.toml (PyPI shows them on the next release).

Considered and left out

  • FAQPage / JSON-LD structured data: Google shows FAQ rich results only for government and health sites since 2023, and AI crawlers read the page text. Not worth a theme change.
  • A "MkDocs alternatives" article: a separate blog post comparing NG, ProperDocs and Zensical is being written; this page can link to it once it's published.
  • A custom home page title: Sumi shows only site_name on the home page; changing that is a theme change for every Sumi site.

Checklist

  • New tests added for new behavior (if applicable)
  • Documentation updated (if applicable)
  • Release notes docs/about/release-notes.md updated (if applicable): docs site only, nothing user-facing in the package

People who wonder whether MkDocs is dead, or what to use instead, search for
exactly that. Answer it on one page: the state of MkDocs 1.x and 2.0, whether
a site stops building, Material's end of life, the alternatives and what
MkDocs NG promises, each with dated, sourced facts.

Retitle the comparison page "MkDocs Alternatives Compared" (nav: "MkDocs
Alternatives"), update its latest-release row, and link both pages from the
home page.
Every page had the same meta description (site_description), so search results
and llms.txt showed one generic line for all of them. Each page now has its own
description in front matter, which Sumi uses for the meta, Open Graph and
Twitter tags and llms_txt for its page list.

Also:

* docs/robots.txt points crawlers at the sitemap (robots.txt was a 404).
* theme.social_image: link previews get the MkDocs NG card instead of none.
* The Markdown copies of Governance and Contributing held only a snippet line;
  docs/hooks.py now inlines included .md files so llms.txt has their text.
* README leads with what MkDocs NG is and why it exists, links the new page,
  and links the catalog, Sumi and NG Material sites instead of their repos.
* pyproject.toml gets keywords for PyPI search.
@codspeed

codspeed Bot commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Merging this PR will not alter performance

✅ 29 untouched benchmarks


Comparing claude/project-thread-x15zqw (82ee801) with main (9a02903)

Open in CodSpeed

@shenxianpeng
shenxianpeng merged commit 0c3657e into main Nov 14, 2026
25 checks passed
@shenxianpeng
shenxianpeng deleted the claude/project-thread-x15zqw branch November 14, 2026 20:52

This branch was successfully deployed

1 active deployment
preview — 82ee801e Deployed Nov 14, 2026 by shenxianpeng via preview #570
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant