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-sm-6 etc you can create all kinds of page layouts.
As far as i know when writing in markdown this isn't possible as each element, be it a
<img /> etc will always be
display: block and if thats the case the default behavior of
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|6Left content:::::: div col|12|6Right 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.