bubblin-jekyll¶ ↑
The Bubblin-Jekyll
is the Jekyll theme in use at The Bubblin 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:
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 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.
Installation¶ ↑
Add this line to your Jekyll site's Gemfile:
gem "bubblin-jekyll"
And add this line to your Jekyll site:
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/] declarationlayout: 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<head></head>
in default layout. -
header.html
— Defines the site's main header section. By default, pages with a definedtitle
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 preprocessedmain.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
} plugin to make sure your website gets the most useful meta tags. See 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
} 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
}. 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 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:
disqus: shortname: my_disqus_shortname
You can find out more about Disqus' shortnames here.
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:
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:
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 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.