Bubbling Ale Theme¶ ↑
> Bubbling ale is a Jekyll theme for GitHub Pages, based off of Cayman.
Usage¶ ↑
On Github Pages¶ ↑
To use the Bubbling Ale theme on github pages:
-
Add the following to your
_config.yml
:remote_theme: FoamFactory/bubbling-ale
Custom Jekyll Setup¶ ↑
To use the Bubbling Ale theme with a custom Jekyll setup:
-
Add the theme to your
Gemfile
:gem "bubbling-ale", "0.0.2"
-
Add the following to your site's
_config.yml
:theme: bubbling-ale
-
Optionally, if you'd like to preview your site on your computer, add the following to your site's
Gemfile
:gem "github-pages", group: :jekyll_plugins
Customizing¶ ↑
Configuration variables¶ ↑
Bubbling Ale will respect the following variables, if set in your site's _config.yml
:
title: [The title of your site] description: [A short description of your site's purpose]
Additionally, you may choose to set the following optional variables:
show_downloads: ["true" or "false" to indicate whether to provide a download URL] google_analytics: [Your Google Analytics tracking ID]
animated_bubbles_off: ["true" or "false" to indicate whether to disable the bubble animation on the main page]
Stylesheet¶ ↑
If you'd like to add your own custom styles:
-
Create a file called
/assets/css/style.scss
in your site -
Add the following content to the top of the file, exactly as shown:
--- --- @import "{{ site.theme }}";
-
Add any custom CSS (or Sass, including imports) you'd like immediately after the
@import
line
Note: If you'd like to change the theme's Sass variables, you must set new values before the @import
line in your stylesheet.
Layouts¶ ↑
If you'd like to change the theme's HTML layout:
-
Copy the original template from the theme's repository<br />(Pro-tip: click “raw” to make copying easier)
-
Create a file called
/_layouts/default.html
in your site -
Paste the default layout content copied in the first step
-
Customize the layout as you'd like
Overriding GitHub-generated URLs¶ ↑
Templates often rely on URLs supplied by GitHub such as links to your repository or links to download your project. If you'd like to override one or more default URLs:
-
Look at the template source to determine the name of the variable. It will be in the form of
{{ site.github.zip_url }}
. -
Specify the URL that you'd like the template to use in your site's
_config.yml
. For example, if the variable wassite.github.url
, you'd add the following:github: zip_url: http://example.com/download.zip another_url: another value
-
When your site is built, Jekyll will use the URL you specified, rather than the default one provided by GitHub.
Note: You must remove the site.
prefix, and each variable name (after the github.
) should be indent with two space below github:
.
For more information, see the Jekyll variables documentation.
Roadmap¶ ↑
See the open issues for a list of proposed features (and known issues).
Previewing the theme locally¶ ↑
If you'd like to preview the theme locally (for example, in the process of proposing a change):
-
Clone down the theme's repository (
git clone https://github.com/foamfactory/bubbling-ale
) -
cd
into the theme's directory -
Run
script/bootstrap
to install the necessary dependencies -
Run
bundle exec jekyll serve
to start the preview server -
Visit {
localhost:4000
} in your browser to preview the theme