Blog: embed blog posts in other pages

[jordan-breton]

Context

I'm using Mkdocs Material in three projects. Two internal documentation and a personal website that will present my side projects and share my passion towards IT generally. All those three websites will use the blog plugin.

Description

The goal of this feature would be to allow embeding the N last posts of a blog category on any page.

Markup

The idea would be to use a markup that will be parsed by the theme. To be consistent with the <!-- more --> syntax for the excerpts, it could look like this:

<!-- blog:category_name nbPosts -->, ex: <!-- blog:feature 5 --> to embed the last 5 posts belonging to the feature category.

Note: the syntax <!-- blog 5 --> could be considered valid, and just embed the last 5 blog posts.

Data in partials/templates

For more flexibility, providing the post data indexed by categories in partials and templates would be very useful too:

{% for post in blog.categories.category_name %}, ex: {% for post in blog.categories.feature %} to loop over the feature category posts.

As a mirror of the markup solution, all posts would be available in blog.posts.

Related links

• Requesting a change
• Blog excerpt

Use Cases

As authors, we can just embed any number of posts from any category with a one-liner, on any page and maybe two or three times on the same page, depending on our use cases.

We don't have to bother anymore with keeping these lists up to date.

Benefits overview

• Informing our users that something new has been posted in the blog directly on the homepage.
• Could help present the project by linking last implemented features.
• On any page, linking a documentation section/introduction to useful resources that can be found in some blog posts. Especially useful to provide very detailed examples of a feature.
• Encouraging users to discover the blog/consume the blog by embedding posts at some key places.
• Very useful when the theme is used to build a personal website too, from a UX perspective.

Drawbacks

Don't see anything that would break. Should not require too much work. The articles would be displayed as they currently are on the blog index/category index. If any further customization is needed, the ability to use the data provided to partials and templates would allow displaying them the way we want.

Visuals

No response

Before submitting

• [X] I have read and followed the change request guidelines.
• [X] I have verified that my idea is a change request and not a bug report.
• [X] I have ensured that, to the best knowledge, my idea will benefit the entire community.
• [X] I have included relevant links to the documentation, related issues and discussions to underline the need for my idea.

[hellt]

good idea, I think I'd love the same functionality but expanded with tags, not only categories

[OlegZv]

I support this as well. My use case is to feature some blog posts on the main index.md page alongside some "intro" material.

[squidfunk]

Awesome! Best way to show your support is using reactions – just upvote ☺️

[squidfunk]

This functionality will be implemented as part of the new tags plugin. We've already got a first alpha over at Insiders which basically lays the groundwork for this feature request and has massive new capabilities. If you're on Insiders, you can already test it! You can tag the blog articles that you want to include in a listing with a tag, and then create a listing with that tag:

plugins:
  - tags

There's no more need to specify the index via tags_file – you can use indexes everywhere now. Let's say you tag the blog articles with the tag latest. Then, add the following where you want the list of blog articles to show up:

### Newest blog posts

<!-- @tags latest -->

This will include all blog posts that are tagged with the latest tag. The tag will also show up on the blog post. If you don't want the tag to show up on the blog post, just use a different front matter property name (this is also new), which will allow you to use tags as a mere structural mechanism, e.g. let's say hidden_tags

plugins:
  - tags:
      tags_property_name: hidden_tags

This will render the tags index, but won't include those tags in the blog post. Note that the tags plugin is now also multi-instance capable, so you can use one instance for tags, and one for latest blog posts.

I understand that this is still a little inconvenient, but it will get simpler in the near future. Before we're considering this issue resolved, we will add the following capabilities:

• Provide a sort function for blog posts by date as part of the listing configuration
• Provide a listing layout that better caters to blog posts (custom listing layouts will be added next)
• Provide the ability to automatically limit or randomize listings
• Create a simple example that clearly demonstrates all of this

This will also allow to link blog posts in a "suggest next reading" carousel at the end of a post, which is another nice functionality that we're considering adding. We're getting there!

[squidfunk]

By the way, all sponsors can help us test the plugin and give feedback in #6517 – it should already be reasonably stable, I've squashed many bugs yesterday and today. I'm confident that we'll push it into production in the coming 2 weeks, including adding documentation and some easily runnable examples.