The Cayman Blog theme

Cayman Blog is a Jekyll theme for GitHub Pages. It is based on the nice Cayman theme, with blogging features added. You can preview the theme to see what it looks like, or even use it today.

Netlify CMS

This blog includes Netlify CMS for content management. To use it:

1. Access the admin interface at /admin (e.g., https://chanchann.github.io/blog/admin/)
2. Log in with your GitHub account (the one with push access to this repository)
3. Create and edit blog posts through the web interface
4. When you save, the CMS will commit changes to the repository automatically

Note on Netlify CMS Setup

For Netlify CMS to work properly with GitHub authentication, you need to:

1. Sign up for a Netlify account at netlify.com if you don't have one
2. Connect your GitHub repository to Netlify
3. Enable Identity service in your Netlify site settings
4. Set up Git Gateway in Netlify to allow CMS access to your repository

For detailed instructions, see the Netlify CMS docs.

Install

Cayman Blog Theme has been developed as a Jekyll theme gem for easier use. It is also 100% compatible with GitHub Pages — just with a more involved installation process according to whether you're running Jekyll v3.3+ and self-hosting, or if you're hosting with GitHub Pages.

Self hosting

If you're running Jekyll v3.3+ and self-hosting you can quickly install the theme as Ruby gem:

1. Add this line to your Jekyll site's Gemfile:

   gem "jekyll-theme-cayman-blog"
   

2. Add this line to your Jekyll site's _config.yml file:

   theme: jekyll-theme-cayman-blog
   

3. Then run Bundler to install the theme gem and dependencies:

   script/bootstrap
   

Hosting with GitHub Pages

If you're hosting your blog with GitHub Pages you'll have to consider this:

⚠️ As stated in the official Jekyll documentation:

If you're publishing your Jekyll site on GitHub Pages, note that GitHub Pages supports only some gem-based themes. See Supported Themes in GitHub's documentation to see which themes are supported.

Therefore, this theme, as well as many others, can not be installed in the same way as the ones officially supported by GitHub Pages (e.g. Cayman, Minima), a bit more effort has to be put on.

The easiest way I found to install Cayman Blog Theme, is installing the theme gem, and then converting the gem-based theme to regular theme.

Alternatively, for new projects, one could fork the whole theme, and keep only the interesting files.

Gem Install

This method is preferred for existing Jekyll blogs, as well as newly created ones. Notice that the files index.md, about.md, contact.md will be overwritten (only index.md is really needed, the other two are just placeholders).

1. Install the theme gem: $ gem install jekyll-theme-cayman-blog

2. Run $ gem env gemdir to know where the gem was installed

3. Open the folder shown in the output

4. Open the folder gems

5. Open the theme folder (e.g. jekyll-theme-cayman-blog-0.0.5)

6. Copy all the files into your newly created or existing blog folder

7. Leave empty theme your site's _config.yml:

   theme:

8. Modify _config.yml, about.md, contact.md for your project

9. Customize the theme

Install as a Fork

1. Fork the repo
2. Clone down the repo with $ git clone git@github.com:username/reponame.git
3. Delete the screenshot.png and screenshot-mobile.png files
4. Empty the _posts folder
5. Install bundler and gems with $ script/bootstrap
6. Run Jekyll with $ bundle exec jekyll serve
7. Modify _config.yml, about.md, contact.md, and now.md for your project
8. Customize the theme

Customizing

Configuration variables

Cayman Blog 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]

RSS feeds

To enable RSS feeds and also make visible an RSS feeds button in the footer, the Jekyll Feed plugin must be installed.

Add this line to your site's Gemfile:

gem 'jekyll-feed'

And then add this line to your site's _config.yml:

plugins:
  - jekyll-feed

⚠️ If you are using Jekyll < 3.5.0 use the gems key instead of plugins.

For more information about configuring this plugin, see the official Jekyll Feed plugin page.

SEO tags

Cayman Blog includes simple SEO tags from jekyll-social-metatags. Have a look at the page for its usage.

The usage is compatible with the plugin Jekyll SEO Tag, which provides a battle-tested template of crowdsourced best-practices.

To switch to a better SEO tags however, one should install Jekyll SEO Tag:

1. Add this line to your site's Gemfile:

   gem 'jekyll-seo-tag'

2. And then add this line to your site's _config.yml:

   plugins:
     - jekyll-seo-tag

3. Replace with the following, the <!-- jekyll-seo-tag --> comment in your site's default.html:

   {% seo %}

For more information about configuring this plugin, see the official Jekyll SEO Tag page.

Stylesheet

If you'd like to add your own custom styles:

1. Create a file called /assets/css/style.scss in your site
2. Add the following content to the top of the file, exactly as shown:

   @import "{{ site.theme }}";