How to inline SVG files in your Bridgetown site

This is a short tutorial to showcase how you can quickly integrate bridgetown-inline-svg into your Bridgetown site to inline your SVG assets when you build your site.

The code for this tutorial can be found at: andrewmcodes/bridgetown-inline-svg-starter

This tutorial is using version 1.1.0 of bridgetown-inline-svg. If you are already using this plugin, you may need to upgrade the gem.

Let’s get started!

Quickstart

To follow along without building the project yourself, open in Gitpod via the button below, and open the browser preview on port 4000 after dependencies are installed and Bridgetown starts up.

Setup

This tutorial will assume you have Ruby, Node, and the bridgetown gem installed locally.

For detailed instructions on getting Bridgetown set up on your local machine, take a look at the Bridgetown Getting Started Documentation and the Bridgetown Installation Guides. I also go into a little more depth in this post detailing how to setup NetlifyCMS on your Bridgetown site.

Creating a new Bridgetown site

The first thing we are going to do is generate a new Bridgetown site.

Run the following command in your terminal:

bridgetown new bridgetown-inline-svg-starter
cd bridgetown-inline-svg-starter

Our new site has been generated! :tada:

Add bridgetown-inline-svg plugin

The next thing we are going to do is add the bridgetown-inline-svg gem.

Run the following command in your terminal to add the plugin to your site’s Gemfile:

bundle add bridgetown-inline-svg -g bridgetown_plugins

or manually:

# Gemfile

group :bridgetown_plugins do
  gem "bridgetown-inline-svg", "~> 1.1.0"
end

Add SVG files

Create a folder for your SVG files under src/. You can name or nest it however you like. I am just going to create a folder named assets:

mkdir src/assets

Then get your SVG files! This library works great with anything from illustrations to icons.

For the purpose of this demo, I downloaded two illustrations from unDraw by Katerina Limpitsouni, which is a great resource of open source illustrations, and one icon from Heroicons, an open source SVG icon library from Adam Wathan and Steve Schoger.

You can download my assets here.

My project src/assets folder now looks like:

|-- bridgetown
    |-- src
+   |   |-- assets
+   |       |-- mail.svg
+   |       |-- undraw_content_creator.svg
+   |       |-- undraw_design_components.svg

Using the plugin

Let’s take a look at what we have right now. Run yarn start in your terminal and open http://localhost:4000 in your browser.

Your should see following in:

Pages

“Pages are the most basic building block for content..” Bridgetown Pages Documentation

Let’s add a simple full-width SVG to our home page. Add the following to src/index.md, but replace my filepath with your own:

{% svg "assets/undraw_design_components.svg" width="100%" %}

This will produce something like:

Collections

“Collections are a great way to group related content…” Bridgetown Collections Documentation

Let’s add a simple full-width SVG to the blog post Bridgetown generated for us. Add the following to src/_posts/2020-07-20-welcome-to-bridgetown.md (the date prefix will be whatever date you generated the project):

{% raw %}{% svg "assets/undraw_content_creator.svg" width="100%" height="280" %}{% endraw %}

Navigate to the post by going to http://localhost:4000/posts/ and choose your post. It will look something like this:

Components

“A component is a reusable piece of template logic (sometimes referred to as a “partial”) that can be included in any part of the site…” Bridgetown Components Documentation

Let’s add an icon to our footer component. Add the following to src/_components/footer.liquid:

<footer>
- Contact me at {{ metadata.email }}
+ {% svg "assets/mail.svg" style="color:#6c63ff;" height="1.5rem" %}
+ <p>{{ metadata.email }}</p>
</footer>

Your footer should now look something like:

Attributes

You can pass any valid SVG attribute to the plugin. If the attribute you pass in is already set in your SVG markup, the plugin will override it.

Here are a few examples based on usage above:

Width and Height

{% svg "path/to/my.svg" width="100%" %}

Adding width="100%" as an argument will change our output to:

<svg width="100%" height="100%"></svg>

Height is automatically set to match width if omitted because IE11 won’t use the viewport attribute to calculate the image’s aspect ratio.

If you don’t want the width and height to match, set both:

{% svg "path/to/my.svg" width="100%" height=240 %}

produces:

<svg width="100%" height="240"></svg>

Style

Set or override inline styles on your SVG with the style attribute:

{% svg "path/to/my.svg" style="color:#6c63ff;" %}

produces:

<svg style="color:#6c63ff;"></svg>

Classes

Set or override CSS classes on your SVG with the class attribute:

{% svg "path/to/my.svg" class="class-1 class-2" %}

produces:

<svg class="class-1 class-2"></svg>

Wrap up

From this point, you can continue adding SVGs to your site and the plugin will inline them when Bridgetown builds.

We didn’t cover it in this post, but the plugin can also optimize your SVGs as well. View the README for the full documentation.

If you encounter any issues or find a bug with the plugin, feel free to report it on the repository.

Want to learn more?

Check out my website or sign up for my newsletter for more Bridgetown content!

Happy coding!