loading...
Cover image for How to inline SVG files  in your Bridgetown site

How to inline SVG files in your Bridgetown site

andrewmcodes profile image Andrew Mason ・5 min read

This is a short tutorial to showcase how you can quickly integrate bridgetown-inline-svg into your Bridgetown site to easily 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, just open in Gitpod via the button below, and open the browser preview on port 4000 after dependencies are installed and Bridgetown starts up.

Open in Gitpod

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
Enter fullscreen mode Exit fullscreen mode

Our new site has been generated! πŸŽ‰

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
Enter fullscreen mode Exit fullscreen mode

or manually:

# Gemfile

group :bridgetown_plugins do
  gem "bridgetown-inline-svg", "~> 1.1.0"
end
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

Default Bridgetown Site

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%" %}
Enter fullscreen mode Exit fullscreen mode

This will produce something like:

Home page with illustration

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):

{% svg "assets/undraw_content_creator.svg" width="100%" height="280" %}
Enter fullscreen mode Exit fullscreen mode

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

Post page with illustration

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>
Enter fullscreen mode Exit fullscreen mode

Your footer should now look something like:

Footer icon

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%" %}
Enter fullscreen mode Exit fullscreen mode

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

<svg width="100%" height="100%"></svg>
Enter fullscreen mode Exit fullscreen mode

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 %}
Enter fullscreen mode Exit fullscreen mode

produces:

<svg width="100%" height="240"></svg>
Enter fullscreen mode Exit fullscreen mode

Style

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

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

produces:

<svg style="color:#6c63ff;"></svg>
Enter fullscreen mode Exit fullscreen mode

Classes

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

{% svg "path/to/my.svg" class="class-1 class-2" %}
Enter fullscreen mode Exit fullscreen mode

produces:

<svg class="class-1 class-2"></svg>
Enter fullscreen mode Exit fullscreen mode

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!

Posted on by:

andrewmcodes profile

Andrew Mason

@andrewmcodes

Andrew Mason is a full stack Ruby on Rails developer. He is passionate about open source, podcasting, and surfing. Andrew podcasts on Remote Ruby.

Discussion

pic
Editor guide