Repository navigation
Answer "is MkDocs still maintained?" and make every page findable - #183
Merged
Merged
Conversation
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.
Contributor
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
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
descriptionfront matter. Sumi uses it for the meta, Open Graph and Twitter tags, and llms_txt lists it next to each page inllms.txt.docs/robots.txtwith the sitemap (it was a 404).theme.social_image: links shared on chat apps and social media show the MkDocs NG card.--8<--snippet line, so agents readinggovernance.mdsaw nothing.docs/hooks.pynow inlines included.mdfiles (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;
keywordsadded topyproject.toml(PyPI shows them on the next release).Considered and left out
site_nameon the home page; changing that is a theme change for every Sumi site.Checklist
docs/about/release-notes.mdupdated (if applicable): docs site only, nothing user-facing in the package