gatsby-remark-grid-system

• Gatsby
• Gatsby Plugins

At the time of writing this post gatsby-remark-grid-system is still very much experimental, it is functional and has had mild testing.

So what is it?

It’s a grid system, it’s like when you use the Bootstrap grid system. Using a set of class names col-xs-12 col-sm-6 etc you can create all kinds of page layouts.

demo 🍱

As far as i know when writing in markdown this isn’t possible as each element, be it a <p>, <img /> etc will always be display: block and if thats the case the default behavior of html and css means that all elements will most likely be positioned one after the other.

This is great in a mobile-first world as you don’t always have the horizontal space to position elements side by side, but what happens when you do? what happens if you’re writing a blog post and have an image and next to it you’d like to write something cool.

This is where having a grid system in markdown can really help.

I looked around for solutions and had in my mind that i’d like the developer experience to be as similar to the html way as possible.

For those not familiar with Bootstrap, this is what i’m talking about.

<div class="row">
  <div class="col col-xs-12 col-sm-6">Left content</div>
  <div class="col col-xs-12 col-sm-6">Right content</div>
</div>

In the above example we wrap x2 div elements in a container div and give it a class name of row this means the row will be a block level element and will occupy 100% of the screen width and force other elements that come after it, below it.

The ‘children’ / the div elements inside the row are where we need to apply a bit of css. The first class, col sets some default styles, display: flex; etc then the remaining classes relate to how many columns the div elements should occupy across a set of breakpoints.

In the above example we say at the xs breakpoint we should be 12 columns wide and at the sm breakpoint we should be 6 columns wide.

This only really makes sense if you are familiar with a 12 column grid system… i’ll try and explain.

If 12 = 100%, 6 (which is half of 12 and therefore half of 100) is 50%. This works all the way from 1 to 12.

100/3 for instance is 33 which can be used as a percentage. If you had 3 columns at 33% you’d have a 100% of the screen width covered.

From divs to markdown

The plugin works like this…

::: div row
    ::: div col|12|6
    Left content
    :::

    ::: div col|12|6
    Right content
    :::
:::

The x3 colons come from remark-containers a plugin by Dan Behlings which act as a kind of starting point for the transformation. When remark-containers see’s this pattern its able to transform it in to something more useful.

In my case i want to catch the first div element and add my own class of row then catch it’s children and add some col specific classes.

In the above example you’ll see col|12|6 where col is the class name followed by numbers separated by the pipe. These are what’s used to add the Bootstrap inspired class names.

The above translates to

<div class="gatsby-remark-grid-system row">
  <div class="gatsby-remark-grid-system col col-12 col-xs-12 col-sm-6 ">Left content</div>
  <div class="gatsby-remark-grid-system col col-12 col-xs-12 col-sm-6">Right content</div>
</div>

The plugin ships with x4 breakpoints [576, 768, 992, 1200] and each in turn corresponds to a class name i.e xs = 576, sm = 768 and so on.

Using this plugin you’re now able to have a bit more control over horizontal layouts in markdown. I plan to add push and pull options for more control over vertical stacking on the smaller breakpoints.

I’d really appreciate issues, comments or stars on Github so if you are using this plugin in your project please do let me know what you think @pauliescanlon