mkdocs-material/blog/2022/09/12/blog-support-just-landed/

[giscus[bot]]

mkdocs-material/blog/2022/09/12/blog-support-just-landed/

Our new blog is built with the brand new built-in blog plugin. You can build a blog alongside your documentation or standalone

https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed/

[ojacques]

Awesome. I will move my own personal README site to mkdocs-insiders. Thank you!

[StarfallProjects]

Just did my first try-out and loving this. Amazed how much configuration is already built in. I particularly love details like categories_allowed.

I can think of a few features that would be nice to have. Sorry for the long list - I do love what already exists.

• Support for multiple blogs in one site (for example, one blog designed to age out might want dates in slugs, and an archive, while another might be more evergreen. You might have situations where you want, say, a company news blog, and a guest writer blog with tutorials)
• Option to add content to generated category pages: this would be great for creating content "hubs" for SEO purposes. For example, allow users to add an intro paragraph for each content page.
• Option of cover images for blog posts (when even I feel things look too dry and serious, we're probably in the Sahara) Perhaps people could set an image via a frontmatter variable? (I'm wondering if this could already be done using some override, but official support would be nice)
• Better styling for figures (not just a blog post issue). Perhaps some border or background that groups the caption to the image more?
• Option to not display the categories in the blog list page. I'm expecting some posts to cross a lot of categories, and this started to look messy when I tried it out.

[squidfunk]

Thanks for the detailed feedback!

Support for multiple blogs in one site (for example, one blog designed to age out might want dates in slugs, and an archive, while another might be more evergreen. You might have situations where you want, say, a company news blog, and a guest writer blog with tutorials)

This should already work by using multiple instances of the plugin and different blog_dir directories. If it doesn't, please create an issue.

Option to add content to generated category pages: this would be great for creating content "hubs" for SEO purposes. For example, allow users to add an intro paragraph for each content page.

Category and archive index pages are currently generated. We could allow the user to provide manually created pages, which will override the creation logic, for which arbitrary content can be defined. Great idea! You can open a feature request if you like.

Option of cover images for blog posts (when even I feel things look too dry and serious, we're probably in the Sahara) Perhaps people could set an image via a frontmatter variable? (I'm wondering if this could already be done using some override, but official support would be nice)

100% agree – I wanted to get the basic functionality out first before adding other layouts and more fancy functionality. You can also open an issue, so we can discuss different use cases and how this feature is expected to work.

Better styling for figures (not just a blog post issue). Perhaps some border or background that groups the caption to the image more?

This is essentially a matter of taste, which can be achieved with some additional CSS.

Option to not display the categories in the blog list page. I'm expecting some posts to cross a lot of categories, and this started to look messy when I tried it out.

So the categories should not be included in the navigation, but the pages should be computed and linked from the blog articles, correct? We could add another configuration option that excludes categories from being linked in the navigation, but I'd want to discuss this feature before implementing, whether it makes also sense for other users and what other cases there are.

[StarfallProjects]

Thanks for the responses!

Option to not display the categories in the blog list page. I'm expecting some posts to cross a lot of categories, and this started to look messy when I tried it out.

So the categories should not be included in the navigation, but the pages should be computed and linked from the blog articles, correct? We could add another configuration option that excludes categories from being linked in the navigation, but I'd want to discuss this feature before implementing, whether it makes also sense for other users and what other cases there are.

Sorry I was unclear. I meant don't list which categories each post is in, when listing the post on the index page. You can end up with a very long string of links above the blog post in the list.

Issues created:

• Custom content pages: Option to add content to generated blog category pages #4363
• Cover images: Cover images for blog posts #4364

I also had a play, and got myself enough cover image functionality to be going on with. Quick write-up here: https://starfallprojects.co.uk/blog/add-cover-images-to-blog-posts-in-material-for-mkdocs/

[squidfunk]

Sorry I was unclear. I meant don't list which categories each post is in, when listing the post on the index page. You can end up with a very long string of links above the blog post in the list.

We could add an option to limit the number of categories, same as with authors in post excerpts. Then, only the first n tags would be rendered. Also authors could influence which tags are shown by rearranging them in the Markdown file.

[nazzacode]

Is there any plan to make this available beyond the insiders program? I would love to use Material for mkdocs for my personal blog, but 15$/mo is a lot for just this.
I think this could actually be quite a large stand alone use case and might be good to open up with a free tier?

[facelessuser]

All the features offered in insiders are planned to be released publicly once the target financial goal is hit. The base blogging support seems to be in https://squidfunk.github.io/mkdocs-material/insiders/?h=insiders#12000-piri-piri, which is only two tiers away. Some additional blog work seems to be included four tiers away: https://squidfunk.github.io/mkdocs-material/insiders/?h=insiders#16000-chipotle.

[squidfunk]

I understand that $15/month is a lot for some, but please understand that I must somehow compensate for my time that I work on this project, building new features, fixing bugs and answering questions. As @facelessuser pointed out, basic blog support is not that far away from landing in the community edition – it's probably a matter of a few months. Thus, waiting is always an option. It'll be released eventually. Additional features for blogging will be attached to higher goals in the future.

[nazzacode]

Ok awesome, that's good to know-- perhaps I will just get it for a month to try it out. Keep up the good work!

[SoumayaMauthoorMOJ]

I love this feature! Do you think it might be possible to add a subscription process in the future so that people automatically get emailed when a new blog is published? Or maybe we should be integrating with another tool for this e.g. Disqus?

[squidfunk]

Thanks! Have you checked the RSS plugin? If you enable RSS, users can subscribe to updates on your blog via the RSS reader of their choice. Email is not possible to support, because we don't know the email address of users. For this, you would need to set up a newsletter service yourself, e.g., using Mailchimp.

[SoumayaMauthoorMOJ]

Ok will look into Mailchimp thanks :-)

[pchalasani]

This is an excellent feature, thank you. Following up on the above, I am wondering how I can combine this with an email newsletter, say Substack. I made a substack account, and I embed the susbscribe button into my mkdocs blog. However the actual content to send to subscribers , I would need to manually create. Maybe the email will contain some preview text of the mkdocs page, and there will be a link to read more on the mkdocs site itself. Does that sound like a good way to do it? Ideally I would like to send the whole blog post via email, but I think that won't work since emails cannot support all of the code/math/admonition features in mkdocs-material. Any thoughts or suggestions? Thanks!

[squidfunk]

Thanks! Unfortunately, email and web are two entirely different beasts. Crafting HTML emails that look great on all clients is a complex task that is quite orthogonal to building a good responsive website. Thus, I'd consider it rather out of scope.

[pchalasani]

Thanks yes makes sense. This is what I am going to do: use substack as an email collection service, and in my mkdocs/material blog I embed the substack signup button. When I need to send a new post to subscribers, I manually create a post containing a plain-text teaser (couple paras) with a link to the main blog saying "read more". I now only need to add social-share buttons on my blog if possible

[SamIsConfused69]

Do we need to rebuild the entire site with every blog post?

[squidfunk]

Yes, as it is with all MkDocs pages, because the navigation and other deduced metadata might change.

[SamIsConfused69]

Gotcha - thanks!

[bqliang]

Hello, first of all, thank you for all your work on mk-docs. Initially I used hexo as my personal static blog, but for some reasons I kept looking for better ones, like Hugo, Zola, Docusaurus, Eleventy... They either had themes that failed to satisfy me, or the configuration process is too difficult for me, or it takes me countless hours on small details but I can't solve them. Finally I came across mk-docs. Although I know it is more for building api documentation, mk-docs meets almost all my needs for a personal static blog. Especially when mk-docs starts adding more support for blogging.
But really, $15 a month is a little expensive for someone who is obsessed with details and just wants to have a beautiful blog.
Well, having said that, I hope mk-docs will get better and better.

post_excerpt: When a post doesn't define an excerpt, views include the entire post.

Is it possible to add a configuration like this?
post_auto_excerpt_max_length: 70

[alexvoss]

Hi, you may want to follow this previous discussion on generating excerpts. I think there will be a solution for this in the not-too-distant future. Note that the blog plugin is now in the public version, though not all features are. Your sponsorship would help to keep Material for MkDocs moving at the speed it does (but I appreciate that peoples' circumstances vary).

[bqliang]

That's great! Thanks for your reply.

[itsjusttriz]

Hi, i cant seem to find anywhere to get minor support with the use of this "module?"

I was wondering if it was possible to trigger inline/custom js from inside a blog post? e.g. to make a hidden element become visible when a certain thing was clicked?

[alexvoss]

Have you tried writing the JavaScript that would hide something based on a condition? I would suggest just developing this in something like codepen. I am sure you can find plenty examples that will give you an idea of how to go about it. I am happy to help once you have something and need it integrated into Material.

[itsjusttriz]

you seem to be misunderstanding me... my issue isnt the Javascript logic. My question was if it was possible to use <script> tags in blog posts, as when i DID try it.. nothing was happening?

[alexvoss]

In that case, please create a minimal reproduction so we can have a look.

[itsjusttriz]

yeaaa... no im not doing this. I asked a simple yes or no question and am getting pushed around to different things. Im good to just quit using mkdocs-material at this stage. 👍🏼

[alexvoss]

I am sorry you feel this way but you have given me nothing to go by. Yes, you can put a script tag into a blog post. Without some information to go on, how am I supposed to help?

[jreuben11]

looks great !

• which blog hosting sites support this ?
• can this work with github pages, and if so, is there guidance docs ?

[niclasheinz]

It works with GitHub Pages - see docs here

You can use any Static Site Hosting Provider.