Migrating my blog to mkdocs - experience so far

[timvink]

First of all, kudos for the new blog plugin and the excellent documentation!

I recently moved my blog, and thought it might be helpful to share some of the problems I encountered, as this kind of feedback can be hard to come by. A small way to kind of pay back & hopefully help make mkdocs-material better for more users!

• I used the github actions template provided, but wanted to install pngquant for mkdocs imaging . Just adding a step with apt install pngquant did not work for me first try. I solved it using a custom action, see https://github.com/timvink/personal-site/blob/33b08538220693144f7e829f1ef1b40566fc29e0/.github/workflows/ci.yml#L23C1-L26C23 .
• I use a custom domain to link to my github pages. It adds a CNAME file to the gh-pages branch. But everytime my site re-builds, it deletes the CNAME file and my website becomes unavailable. Solution was to add the CNAME file to the docs/ folder in my master branch.
• I wanted to customize my homepage. mkdocs-material has a custom homepage also, so naturally I looked there as an example. The fact that you can create an override template like home.html and add that to a page (index.md in this case) using the meta YAML, is actually very useful. I was surprised this was not in the docs.. this kind of customization seems common to me.
• In my custom template home.html for my index.md, I wanted to loop over the blog pages, just like in the blog.html template. But those blog pages where not available in the jinja2 context. I solved that by creating a custom mkdocs hook script like this:

def on_page_context(context, **kwargs):
    """
    Store blog pages in context, so we can use them in home.html override.
    """
    context['blog_pages'] = []
    for page in context['pages']:
        if page.page.meta.get('template') == "blog-post.html":
            context['blog_pages'].append(page.page)

It's not intuitive.. maybe the list of blogpages can be added to the context by the blog plugin itself?

• My old blog used the format <domainname>.<tld>/<slug-of-blogpost> . Even with the customized slug (which I used) I am still forced to use <domainname>.<tld>/blog/<slug-of-blogpost> . Notice the /blog in there. I did not want to break my old links by migrating, so I used mkdocs-redirect plugin to manually map the old links to the new. I recommend the mkdocs-material docs refer to mkdocs-redirect when explain how to migrate and/or allow changing the url for a blogpost from the root (instead of from /blog)
• I use mailchimp to manage an email subscription list. Mkdocs-material has these nice buttons, but I didn't get it to look very nice. Perhaps a section on integrations would be nice to kind of simplify this kind of customization stuff. At least a crash course into the CSS classes that are available would be nice, then I can make customizations easier myself.
• Fixing links, broken images, etc required some work. Probably unavoidable, although I image you could be some migration tools for certain very common blog systems.

In case you're interested, you can see the source code in https://github.com/timvink/personal-site/tree/main

Overall very happy with the migration -- looking forward to using all the mkdocs functionality for blogging!

Might report back after a while with new findings. I have yet to try out things like using a jupyter notebook (https://github.com/greenape/mknotebooks) as a blogpost, which could be very cool for technical blogging; inserting random javascript interactive snippets, etc.

[squidfunk]

Thanks for sharing your experience – those are very valuable insights, as it helps us making the blog plugin better.

I used the github actions template provided, but wanted to install pngquant for mkdocs imaging . Just adding a step with apt install pngquant did not work for me first try. I solved it using a custom action, see https://github.com/timvink/personal-site/blob/33b08538220693144f7e829f1ef1b40566fc29e0/.github/workflows/ci.yml#L23C1-L26C23 .

It should be enough to run apt-get install pngquant, as mentioned in our image processing guide. See our documentation workflow for reference:

mkdocs-material/.github/workflows/documentation.yml

Lines 68 to 69 in d144a1c

	- name: Install dependencies
	run: sudo apt-get install pngquant

The publishing guide doesn't include it, because the GitHub action tries to be as minimal as possible, and the optimize plugin for which this is for (not the blog plugin) mentions a link to the image processing guide in the documentation:

The optimize plugin is built into Material for MkDocs and doesn't need to be installed.

However, in order to optimize all media files, it's necessary to install the dependencies for image processing, if they're not already available on your system. The linked guide includes instructions for several operating systems and mentions some alternative environments.

---

I use a custom domain to link to my github pages. It adds a CNAME file to the gh-pages branch. But everytime my site re-builds, it deletes the CNAME file and my website becomes unavailable. Solution was to add the CNAME file to the docs/ folder in my master branch.

This is mentioned in the MkDocs documentation. We can't mirror all options from MkDocs, but since Material for MkDocs is the main entrypoint for many people building documentation, we should add an example for hosting on a custom domain to our docs. (cc @alexvoss)

I wanted to customize my homepage. mkdocs-material has a custom homepage also, so naturally I looked there as an example. The fact that you can create an override template like home.html and add that to a page (index.md in this case) using the meta YAML, is actually very useful. I was surprised this was not in the docs.. this kind of customization seems common to me.

It is mentioned in our documentation, albeit not at the best location. We'll be reworking the customization guide as well in the near future, explaining how to create and use custom templates. (cc @alexvoss)

In my custom template home.html for my index.md, I wanted to loop over the blog pages, just like in the blog.html template. But those blog pages where not available in the jinja2 context. I solved that by creating a custom mkdocs hook script like this:

We can certainly add the top-level blog view to the context, which would allow you to access blog posts, categories and archives in custom templates. You can open a feature request if you like to see this in Material for MkDocs.

My old blog used the format ./ . Even with the customized slug (which I used) I am still forced to use ./blog/ . Notice the /blog in there. I did not want to break my old links by migrating, so I used mkdocs-redirect plugin to manually map the old links to the new. I recommend the mkdocs-material docs refer to mkdocs-redirect when explain how to migrate and/or allow changing the url for a blogpost from the root (instead of from /blog)

The blog prefix is sourced from blog_dir – it's the location at which your blog is built. The canonical use case is to build a blog alongside your documentation, but you can also easily build a standalone blog that is hosted at the top-level, omitting the blog prefix. Again, we'll be reworking our blog setup guide to host exactly those examples in the coming weeks. (cc @alexvoss) In the meantime, this blog article explains how to set up a custom blog. It should make defining redirects unnecessary.

I use mailchimp to manage an email subscription list. Mkdocs-material has these nice buttons, but I didn't get it to look very nice. Perhaps a section on integrations would be nice to kind of simplify this kind of customization stuff. At least a crash course into the CSS classes that are available would be nice, then I can make customizations easier myself.

I'm sorry, but we can't offer a CSS crash course on our docs. Our docs are already 91 pages and growing, and maintaining a documentation of this size becomes quite a challenge. However, we offer examples in our reference how to use buttons, in fact, exactly for your use case:

[Subscribe to our newsletter](<url-to-newsletter>){ .md-button }

I'm not sure what you mean by integrations – we try to provide the basic building blocks with which you can build practically everything you wish for. Other than that, I'm happy to learn about what you specifically imagine how this should work.

Fixing links, broken images, etc required some work. Probably unavoidable, although I image you could be some migration tools for certain very common blog systems.

Yes, we're thinking about writing a few blog posts how to migrate from other systems like Jekyll and friends, but we would have to rely on the community to create scripts that simplify integrations. Please understand that we must try to invest our time with the maximum possible impact, and writing tools for blog integrations for specific other tools provides a much smaller impact that working for example on the new search. Thus, we have to rely on the community to help us our on those matters ☺️ We hope for your understanding.

Might report back after a while with new findings. I have yet to try out things like using a jupyter notebook (https://github.com/greenape/mknotebooks) as a blogpost, which could be very cool for technical blogging; inserting random javascript interactive snippets, etc.

Everything that works with Material for MkDocs should also work with the blog plugin – that the entire idea of it: you can leverage the entirety of powerful components for blogging that you already use for technical writing. We're also happy for any further feedback we receive!