mkdocs-material

mkdocs-material copied to clipboard

Contribution guidelines

• [X] I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• [X] ... to my best knowledge, my idea wouldn't break something for other users
• [X] ... the documentation does not mention anything about my idea
• [X] ... there are no open or closed issues that are related to my idea

Description

Each category page for the blog is auto-generated. It would be great to be able to add custom content (such as an intro paragraph)

I imagine two possible approaches:

• Manual category index pages, with custom content up top, and then the list of posts below
• Some sort of config file (like the .meta.yml) containing content for category pages

The first is probably more intuitive for users?

Use Cases

The category pages act as hub pages for topics, which as I understand it can be good for SEO.

Screenshots / Mockups

No response

As discussed in https://github.com/squidfunk/mkdocs-material/discussions/4344#discussioncomment-3644360, probably the best and most flexible way is to allow the user to manually create the category pages with custom content. Same goes for archive pages, albeit the use case might not pop up as often:

.
├─ docs/
│  └─ blog/
│     ├─ category/
│     │  ├─ foo.md
│     │  └─ bar.md
│     ├─ posts/
│     └─ index.md
└─ mkdocs.yml

Added in squidfunk/mkdocs-material-insiders@08ab20cce3a499352ad8fafab9ee57925e4997ec and released as part of 8.5.3+insiders-4.24.0. The documentation includes a new section how to add custom content to generated index pages.

Additionally, there's a new setting called post_excerpt_max_categories, which implements the functionality of your other feature request, allowing to limit the number of categories for post excerpts. authors_in_excerpt has been renamed to post_excerpt_max_authors. Correct me if I'm wrong, but I think that all of the things you mentioned in your feedback should now be possible. Oh, and thanks again for the detailed feedback! Happy to iterate.

Wow that was very speedy! Will try this out in the coming days! 🎉