How to create a blog like https://squidfunk.github.io/mkdocs-material/blog/2021/excluding-content-from-search/

[slavipande]

Hi everyone,

I'm trying to create a blog-like experience with material for mkdocs. I searched through the material website for hints and also tried searching here in the discussions, but, unfortunately, haven't found the way to do it. So, I'd be really grateful if someone can provide more details as to how to create a blog post like the ones on the material website (e.g., https://squidfunk.github.io/mkdocs-material/blog/2021/excluding-content-from-search/).

Specifically, what I mean with this is that I'd like to find out how to create a blog page that has author name and pic, date of publishing, read time, etc., data in the beginning of the blog. Here's a screenshot for more clarity:

I will be looking forward to the upcoming discussion on the matter. :)

Best regards,
Svetoslav

[squidfunk]

This is currently an all-manual process – there's no magic involved, other than HTML + CSS. I may provide "batteries included" blogging capabilities at some point in the future, or when more users really need it.

[squidfunk]

For directions, just follow the original Markdown:
https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/docs/blog/2021/search-better-faster-smaller.md

[slavipande]

Thanks for your response, @squidfunk :)

I thought there's more into it, but if this is the case, I'm happy to try it out. I've already tried combining material with HTML + CSS to create a custom landing page for our help portal (dirigible.io/help), so let's see how it turns out.

Cheers,
Svetoslav

[hellt]

I am very interested in seeing this as part of the mkdocs-insiders for example. Was desperately looking for blogging engine with mkdocs-material styling

I tried to follow the steps and created the overrides/main.html, but then I couldn't figure which CSS/JS files I need to refer to from that template. Do I need to have it like here(1) or here(2)?

Would I need to build any css/js or would I be OK just copying it from the repo?

[squidfunk]

The material folder is built from the src folder. If you just clone the repository and follow the theme development guide, it will work as intended – it's the same process I use. I'll try to find some time in the future to streamline the process and write about blogging with Material for MkDocs.

[hellt]

thanks @squidfunk
I tried stuff, but got stuck, will wait for some docs around it.

ps/ @slavipande if you managed to get this working I'd appreciate you sharing a link to your commit

[slavipande]

Hi @hellt ,

Here are a couple of notes on what worked for me:

• I reused the following HTML part from the original .md that @squidfunk referenced above and pasted it in the correct place in my .md file:
  
• In order for this to be visualized properly, I've got an additional CSS file created (and declared in the mkdocs.yml) as described in Additional CSS. Here's the content of the CSS:

/* Styles for blog-like features - author avatar & name, posting date, min to read, etc. */
.md-typeset .mdx-author img {
  border-radius: 100%;
  height: 2rem;
}

.md-typeset .mdx-author {
  display: flex;
  font-size: .68rem;
}

.md-typeset .mdx-author p>span {
  display: block;
}

p {
  display: block;
  margin-block-start: 1em;
  margin-block-end: 1em;
  margin-inline-start: 0px;
  margin-inline-end: 0px;
}

.md-typeset .mdx-author p:first-child {
  flex-shrink: 0;
  margin-right: .8rem;
}

With this setup, I don't think you need to overwrite any parts of the theme. Not sure, though, maybe @squidfunk can correct me if I'm wrong.

I think you'll have to manually paste the HTML code in each .md file where you'd like to have the blogging capabilities (author avatar, name, link to gh profile, publish date and reading time). Needless to say, you'll have to provide your own values for author avatar, name, link to gh profile. One thing I learned recently, you can get your github avatar URL in several ways and you get slightly different links, but all of them would work. IMO, it's easier to just replace <username> in this URL https://avatars.githubusercontent.com/<username> and you'll see your github avatar. If you google github avatar url, you'll see alternative ways, too.

Hope this helps!

[4kelly]

Hey @slavipande @hellt I was interested in trying out a blog with MkDocs as well.

I took @squidfunk's design inspiration and packaged it up into something a bit easier to use.

• See demo website with instructions: https://material-mkdocs-blog.4kelly.com (repo).
• PR to this repo to add the templates for squids blog. Add blog templating overrides #3192

[hellt]

Wow that's dope! Really looking forward having this in mkdocs-material

[slavipande]

@4kelly, looks great!

Also, @hellt, @squidfunk,

Here's a blog article on what we did for Eclipse Dirigible Blogs so the blogging capabilities are part of the page template and can be controlled via the page frontmatter: Enable Blogging Capabilities with Material for MkDocs.

Hope this is helpful!

Best regards,
Svetoslav

[ben519]

Also note that Markdown in HTML must be applied for this to work.

[squidfunk]

I've started to collect some ideas in #3353. Any input is appreciated, feel free to leave a comment!