bubblin-jekyll — Jekyll Blog Template

SHA-256: 9e9f41b92bf7b3dec622a2f0ae0b2ab6a4c15cb2ea25a904c20d454b432b2dbd

2026-10-03T18:01:39.201Z

# bubblin-jekyll

The `Bubblin-Jekyll` is the Jekyll theme in use at [The Bubblin Blog](https://bubblin.io/blog/). It is a particularly useful theme for situations where you want to add a blog to your site, say on the side of your rails app (website) or over a url like this:

> https://example.com/blog/


`Bubblin-Jekyll` was originally a fork off of [Minima](https://github.com/jekyll/minima)—the default gem-theme of Jekyll-but it has been rewritten completely using the [Toucaan CSS](https://github.com/marvindanig/toucaan) fundamentals for its themed layout.

A tutorial on how to setup a jekyll blog using the `bubblin-jekyll` theme alongside your rails app is available [here](https://bubblin.io/blog/).

[Theme preview](https://jekyll.github.io/bubblin-jekyll/)

![bubblin-jekyll theme preview](/screenshot.png)

## Installation

Add this line to your Jekyll site's Gemfile:

```ruby
gem "bubblin-jekyll"
```

And add this line to your Jekyll site:

```yaml
theme: bubblin-jekyll

search: true
```

And then execute:

    $ bundle

### Layouts

Refers to files within the `_layouts` directory, that define the markup for your theme.

  - `default.html` — The base layout that lays the foundation for subsequent layouts. The derived layouts inject their contents into this file at the line that says ` {{ content }} ` and are linked to this file via [FrontMatter](https://jekyllrb.com/docs/frontmatter/) declaration `layout: default`.
  - `home.html` — The layout for your landing-page / home-page / index-page.
  - `page.html` — The layout for your documents that contain FrontMatter, but are not posts.
  - `post.html` — The layout for your posts.

### Includes

Refers to snippets of code within the `_includes` directory that can be inserted in multiple layouts (and another include-file as well) within the same theme-gem.

  - `disqus_comments.html` — Code to markup disqus comment box.
  - `footer.html` — Defines the site's footer section.
  - `google-analytics.html` — Inserts Google Analytics module (active only in production environment).
  - `head.html` &mdash; Code-block that defines the `<head></head>` in *default* layout.
  - `header.html` &mdash; Defines the site's main header section. By default, pages with a defined `title` attribute will have links displayed here.
  - `icon-* files` &mdash; Inserts github and twitter ids with respective icons.

### Sass

Refers to `.scss` files within the `_sass` directory that define the theme's styles.

  - `bubblin-jekyll.scss` &mdash; The core file imported by preprocessed `main.scss`, it defines the variable defaults for the theme and also further imports sass partials to supplement itself.
  - `bubblin-jekyll/_base.scss` &mdash; Resets and defines base styles for various HTML elements.
  - `bubblin-jekyll/_layout.scss` &mdash; Defines the visual style for various layouts.
  - `bubblin-jekyll/_syntax-highlighting.scss` &mdash; Defines the styles for syntax-highlighting.

### Assets

Refers to various asset files within the `assets` directory.
Contains the `main.scss` that imports sass files from within the `_sass` directory. This `main.scss` is what gets processed into the theme's main stylesheet `main.css` called by `_layouts/default.html` via `_includes/head.html`.

This directory can include sub-directories to manage assets of similar type, and will be copied over as is, to the final transformed site directory.

### Plugins

Bubblin-jekyll comes preinstalled with the [`jekyll-seo-tag`](https://github.com/jekyll/jekyll-seo-tag) plugin to make sure your website gets the most useful meta tags. See [usage](https://github.com/jekyll/jekyll-seo-tag#usage) to know how to set it up.

## Usage

### Customization

To override the default structure and style of bubblin-jekyll, simply create the concerned directory at the root of your site, copy the file you wish to customize to that directory, and then edit the file.
e.g., to override the [`_includes/head.html `](_includes/head.html) file to specify a custom style path, create an `_includes` directory, copy `_includes/head.html` from minima gem folder to `<yoursite>/_includes` and start editing that file.

The site's default CSS has now moved to a new place within the gem itself, [`assets/main.scss`](assets/main.scss). To **override the default CSS**, the file has to exist at your site source. Do either of the following:
- Create a new instance of `main.scss` at site source.
  - Create a new file `main.scss` at `<your-site>/assets/`
  - Add the frontmatter dashes, and
  - Add `@import "bubblin-jekyll";`, to `<your-site>/assets/main.scss`
  - Add your custom CSS.
- Download the file from this repo
  - Create  a new file `main.scss` at `<your-site>/assets/`
  - Copy the contents at [assets/main.scss](assets/main.scss) onto the `main.scss` you just created, and edit away!
- Copy directly from Bubblin-Jekyll gem
  - Go to your local bubblin-jekyll gem installation directory ( run `bundle show bubblin-jekyll` to get the path to it ).
  - Copy the `assets/` folder from there into the root of `<your-site>`
  - Change whatever values you want, inside `<your-site>/assets/main.scss`

--

### Change default date format

You can change the default date format by specifying `site.bubblin-jekyll.date_format`
in `_config.yml`.

```
# Bubblin-Jekyll date format
# Refer to http://shopify.github.io/liquid/filters/date/ to customize
bubblin-jekyll:
  date_format: "%b %-d, %Y"
```

--

### Enabling comments (via Disqus)

Optionally, if you have a Disqus account, you can tell Jekyll to use it to show a comments section below each post.

To enable it, add the following lines to your Jekyll site:

```yaml
  disqus:
    shortname: my_disqus_shortname
```

You can find out more about Disqus' shortnames [here](https://help.disqus.com/customer/portal/articles/466208).

Comments are enabled by default and will only appear in production, i.e., `JEKYLL_ENV=production`

If you don't want to display comments for a particular post you can disable them by adding `comments: false` to that post's YAML Front Matter.

--

### Enabling Google Analytics

To enable Google Anaytics, add the following lines to your Jekyll site:

```yaml
  google_analytics: UA-NNNNNNNN-N
```

Google Analytics will only appear in production, i.e., `JEKYLL_ENV=production`


--

### Enabling Heap Analytics

To enable Heap Anaytics, add the following lines to your Jekyll site:

```yaml
  heap_analytics: NN-NNNNNNNNN
```

Heap will appear only in production, i.e., with `JEKYLL_ENV=production`


## Contributing

Bug reports and pull requests are welcome on GitHub at . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

## Development

To set up your environment to develop this theme, run `script/bootstrap`.

To test your theme, run `script/server` (or `bundle exec jekyll serve`) and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme and the contents. As you make modifications, your site will regenerate and you should see the changes in the browser after a refresh.

## License

The theme is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).