Recently I migrated all of my Jekyll sites from Minima 2.5.1 (updated August 2019) to the latest version on GitHub (updated January 2023). This came with lots of new features, but also changed how social links are handled. In this post I’ll cover both the old and new method for adding new social links, as well as the technical details.

Before we get started, here is the Minima 2.5.1 sourcecode, and here is the latest source code. Minima inexplicably hasn’t had a new release in over 3 years, so the latest codebase has diverged from the latest release.

Which Minima version do I have?

If you’ve just set up your Jekyll blog, you have Minima 2.5.1.

If you’ve manually set remote_theme=jekyll/minima in your _config.yml, you have the unreleased Minima 3.0.0.

Adding a new social link is pretty straightforward, but there’s no official guide! You can see an example of this process in a commit from when I added a Substack link to my site. Note that the SVG is minimised (all on one line), but you can still see the <symbol>.


  1. Get an SVG.
  2. Change the SVG into a named symbol.
    • Open in any text editor.
    • Remove everything except the <svg> and <path> sections.
    • Change the <svg and </svg> to <symbol and </symbol>.
    • Delete everything from the <symbol except viewport=" ... ", and add an id=" ... ".
    • Delete everything from the <path except d=" ... ".
  3. Add SVG to combined image.
    • Put the SVG code at the bottom of assets/minima-social-icons.svg, just before </svg>.
  4. Add social link to footer.
    • Inside social.html, copy an existing line (e.g. YouTube) and replace the URL & variable names (e.g. youtube_username to coins_username).
    • Don’t forget to update the minima-social-icons.svg#youtube to your ID from step 2.
  5. Add to _config.yml.
    • For example, these coins might be coins_username: Jake123 and coins_url:
  6. Relaunch your site, your new social link should be there!


Whilst the process of adding a new social icon to Minima 2.5.1 is pretty convoluted, at least the use of it is simple!

  1. footer.html includes social.html.
  2. social.html checks each social source to see if it is defined in _config.yml, and displays the username & URL if so.
  3. Additionally, social.html uses the symbol’s id to fetch a specific section of the minima-social-icons.svg, e.g. #youtube.

Whilst there is a guide on the project’s readme, it can be a little tricky to know how to resize the image and handle it correctly.


  1. Get an SVG.
  2. Resize to be 16x16 square.
    • I used “iloveimg”, but if you have a proper SVG editor feel free to use it.
    • Set the width & height px to 16 (since SVGs are scalable there won’t be any loss of quality) then download.
    • It’s OK if it’s not square by a pixel or two, but it’s worth the effort if possible!
  3. Remove everything except <path> data.
    • Open in any text editor.
    • Check inside the <svg> element for viewBox="0 0 16 16", this means it’s the correct size.
    • Delete everything outside of the <path> tag, and the style=" ... " bit, then save.
  4. Put this SVG in _includes/social-icons/.
  5. Add to _config.yml.
    • For example, these coins might be - { platform: coins, user_url: "" }
  6. Relaunch your site, your new social link should be there!


Minima 3 changed how social icons are used. Instead of being manually added into one big SVG, they are now dynamically built up during compile time.

Personally I think this is overly convoluted, and would be better served by just displaying standard SVG icons, or using the slightly simpler previous system. The justifications in the PR do make sense, but for a “minimal” theme it’s a totally unnecessary complication (as was the previous system). Adding a new clickable icon shouldn’t include this much complexity:

Generating the combined SVG

  1. minima-social-icons.liquid loops through the social_links defined in _config.yml, and includes svg_symbol.html once per social link.
  2. svg_symbol.html builds up a 16x16 section of the overall SVG, including the social link’s icon by name.

Using the combined SVG

  1. _includes/footer.html (the site’s footer) includes social.html.
  2. social.html loops through the social_links defined in _config.yml, and includes social-item.html once per social link.
  3. social-item.html looks in the minima-social-icons.svg file for an SVG with the social link’s name, and displays a clickable icon.