# 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` — Code-block that defines the `` in *default* layout. - `header.html` — Defines the site's main header section. By default, pages with a defined `title` attribute will have links displayed here. - `icon-* files` — 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` — 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` — Resets and defines base styles for various HTML elements. - `bubblin-jekyll/_layout.scss` — Defines the visual style for various layouts. - `bubblin-jekyll/_syntax-highlighting.scss` — 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 `/_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 `/assets/` - Add the frontmatter dashes, and - Add `@import "bubblin-jekyll";`, to `/assets/main.scss` - Add your custom CSS. - Download the file from this repo - Create a new file `main.scss` at `/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 `` - Change whatever values you want, inside `/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).