Remarking pinax-theme-bootstrap To Be Semantic

Since 2011, we’ve been packaging templates for Pinax apps inside pinax-theme-bootstrap. Over the years we’ve moved more and more app templates that used to be bundled with the app into the theme. Unfortunately, we are too coupled to specific Bootstrap versions.

Photo by Greg Rakozy on Unsplash

We have been fans of Bootstrap since the early days as a Twitter open source project.

It is mobile-first. It is fast to build out prototypes. It is easy to layer in style.

We built the set of templates in pinax-theme-bootstrap to use Bootstrap by having the markup use classes from the framework. This has made maintenance slow and difficult when new versions of Bootstrap are released. It also makes the templates not very reusable if you want to use a different CSS framework.

It’s time for a change.

Plenty of people have advocated for using semantic markup over specific framework pieces. At the risk of bloating the css a bit more, you end up with very clean markup that can be reused with frameworks, which I think makes sense for Pinax, but perhaps not a one off project.

Currently, there is an effort in progress to make all templates have semantic markup and classes. There might be some overlap where the Bootstrap classes are semantic. For example, the alert divs are pretty semantic as-is.

In the starter projects that Pinax provides, we’ll provide Sass modules that map the semantic markup to various Bootstrap framework mixins, utilities and classes.

For example, here is how we have structured the top nav bar in the templates and the corresponding Sass mapping to bootstrap:


Sass Mapping

The one place that we’ll be leaving associated with bootstrap is the use of the bootstrap form template tag. There is so much it gives us for free it’d be a shame to have to rewrite large portions of it just to be free of a framework. I see us replacing this soon with our own semantic markup forms template tag.

The Javascript that ships with pinax-theme-bootstrap will be pulled out and added to the starter projects static build process so there is no static that ships with the theme.

Now that all the style definition is in the starter projects rather than the pinax-theme-bootstrap app, it is no longer really a theme or related to bootstrap, so we will rename it to pinax-templates.

We may or may not take the Sass that maps the semantic markup to Bootstrap style and create npm packages. Time will tell if that is a worthwhile exercise or not.

What we hope to see from this is a pinax-templates package that can focus purely on maintainable and reusable templates that are easier to maintain and longer lived between versions of Bootstrap and that can be used with other CSS frameworks.

As part of this effort, we will aim to do a much better job of documenting the templates in terms of their block definitions as well as the context that they expect to be present. Ideally you should be able to override the appropriate blocks, set body classes, etc. without having to copy in the templates unless you just need to make massive structural changes.

Stay tuned!