Merge pull request #73 from daviddarnes/update-installation

Update installation

README.md

@@ -12,6 +12,7 @@
 - [Features](#features)
 - [Examples](#examples)
 - [Installation](#installation)
+- [Customising](#customising)
 - [Configuration](#configuration)
   - [Gem dependency settings](#gem-dependency-settings)
   - [Site settings](#site-settings)
@@ -23,23 +24,22 @@
 
 ## About
 
-Alembic is a starting point for [Jekyll](https://jekyllrb.com/) projects. Rather than starting from scratch, this boilerplate is designed to get the ball rolling immediately. Install it, configure it, tweak it, push it.
+**Alembic is a starting point for [Jekyll](https://jekyllrb.com/) projects. Rather than starting from scratch, this boilerplate theme is designed to get the ball rolling immediately. Install it, configure it, tweak it, push it.**
 
 ## Features
 
-- Available as a starter kit or as [Jekyll theme gem](http://jekyllrb.com/docs/themes/)
+- Available as a **theme gem** and **GitHub Pages** theme
 - Simple and elegant design that can be used out of the box or as solid starting point
-- Tested in all major browsers, including IE and Edge
-- Configurable colours and typography in a single settings file
-- Extensive set of shortcodes to include various elements; such as buttons, icons, figure images and more
-- Solid typographic framework from [Sassline](https://sassline.com/)
+- Tested in all major browsers, including **IE and Edge**
+- **Configurable colours** and typography in a single settings file
+- Extensive set of **shortcodes** to include various elements; such as buttons, icons, figure images and more
+- Solid **typographic framework** from [Sassline](https://sassline.com/)
 - Configurable navigation via a single file
 - Modular Jekyll components
 - Post category support in the form of a single post index page grouped by category
 - Built in live search using JavaScript
-- Contact form built in using [Formspree](https://formspree.io/)
-- Works on [GitHub Pages](https://pages.github.com/) out of the box
-- Designed with [Siteleaf](http://www.siteleaf.com/) in mind
+- **Contact form** built in using [Formspree](https://formspree.io/)
+- Designed with **[Siteleaf](http://www.siteleaf.com/)** in mind
 - Has 9 of the most popular networks as performant sharing buttons
 - Has documentation
 
@@ -59,47 +59,56 @@ Here are a few examples of Alembic out in the wild being used in a variety of wa
 
 ## Installation
 
+### As a Jekyll theme
+
+1. Add `gem "alembic-jekyll-theme"` to your `Gemfile` to add the theme as a dependancy
+2. Run the command `bundle install` in the root of project to install the theme and its dependancies
+3. Add `theme: alembic-jekyll-theme` to your `_config.yml` file to set the site theme
+4. Run `bundle exec jekyll serve` to build and serve your site
+5. Done! Use the [configuration](#configuration) documentation and the example [`_config.yml`](https://github.com/daviddarnes/alembic/blob/master/_config.yml) file to set things like the navigation, contact form and social sharing buttons
+
+### As a GitHub Pages remote theme
+
+1. Add `gem "jekyll-remote-theme"` to your `Gemfile` to add the theme as a dependancy
+2. Run the command `bundle install` in the root of project to install the jekyll remote theme gem as a dependancy
+3. Add `jekyll-remote-theme` to the list of `plugins` in your `_config.yml` file
+4. Add `remote_theme: daviddarnes/alembic` to your `_config.yml` file to set the site theme
+5. Run `bundle exec jekyll serve` to build and serve your site
+6. Done! Use the [configuration](#configuration) documentation and the example [`_config.yml`](https://github.com/daviddarnes/alembic/blob/master/_config.yml) file to set things like the navigation, contact form and social sharing buttons
+
 ### As a Boilerplate / Fork
 
-1. [Fork the repo](https://github.com/daviddarnes/alembic#fork-destination-box)
-2. Clone down the repo with `git clone [email protected]:username/reponame.git`
-3. Replace the `Gemfile` in the root of the repo with the one in `demo/Gemfile`
-4. Delete the following unnecessary files/folders: `demo/`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `LICENSE`, `screenshot.png` and `alembic-jekyll-theme.gemspec`
-5. Change the `logo.svg` and `default-social-image.png` in the `assets/` folder to your own branding
-6. Configure your site settings using the `_config.yml`, more info can be found in [Configuration](#configuration)
-7. Change the `CNAME` record to your projects' record
-8. Install bundler with `gem install bundler`
-9. Install gems with `bundle install`
-10. Run Jekyll with `bundle exec jekyll serve --watch`
-11. Begin hacking for your project
+_(deprecated, not recommended)_
 
-### As a Jekyll 3.3 theme gem
+1. [Fork the repo](https://github.com/daviddarnes/alembic#fork-destination-box)
+2. Replace the `Gemfile` with one stating all the gems used in your project
+3. Delete the following unnecessary files/folders: `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `LICENSE`, `screenshot.png`, `CNAME` and `alembic-jekyll-theme.gemspec`
+4. Run the command `bundle install` in the root of project to install the jekyll remote theme gem as a dependancy
+5. Run `bundle exec jekyll serve` to build and serve your site
+6. Done! Use the [configuration](#configuration) documentation and the example [`_config.yml`](https://github.com/daviddarnes/alembic/blob/master/_config.yml) file to set things like the navigation, contact form and social sharing buttons
 
-1. Download the starter `/demo` content, [quick download link](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/daviddarnes/alembic/tree/master/demo)
-2. Configure your site settings using the `_config.yml`, more info can be found in [Configuration](#configuration)
-3. Create a `logo.svg` and `default-social-image.png` in a new `assets/` folder
-4. Install bundler with `gem install bundler`
-5. Install gems with `bundle install`
-6. Run Jekyll with `bundle exec jekyll serve --watch`
-7. Begin hacking for your project
+## Customising
 
-### Boilerplate & Theme differences
+When using Alembic as a theme means you can take advantage of the file overriding method. This allows you to overwrite any file in this theme with your own custom file, simply by matching the file name and path. The most common example of this would be if you want to add your own styles or change the core style settings.
 
-The boilerplate kit is better for more drastic hacking and changes, a project that's quite different to any other and needs a lot of custom work done. Additionally you'll only be able to use this method if you want to host it on GitHub Pages, as [themes can't be submitted](https://pages.github.com/themes/)... yet.
+To add your own styles copy the [`styles.scss`](https://github.com/daviddarnes/alembic/blob/master/assets/styles.scss) into your own project with the same file path (`assets/styles.scss`). From there you can add your own styles, you can even optionally ignore the theme styles by removing the `@import "alembic";` line.
 
-Using the theme will allow you to receive updates made and will be more programmatic. To make your own changes you'll need to overwrite the files with your own. For example: If I want to change the colours and typography of my site I'll need to copy the [`_settings.scss`](https://github.com/daviddarnes/alembic/blob/master/_sass/_settings.scss) file and create my own in `_sass/_settings.scss` with my own changes. This is the same for all files within the theme, which means your own project will be more lean than if you were to use the boilerplate.
+If you're just looking to set your own colours and fonts copy the [`_settings.scss`](https://github.com/daviddarnes/alembic/blob/master/_sass/_settings.scss) file into your project at the same file path (`_sass/_settings.scss`) and change variables however you wish. The settings are a mixture of custom variables and settings from [Sassline](https://medium.com/@jakegiltsoff/sassline-v2-0-e424b2881e7e) - follow the link to find out how to configure the typographic settings.
 
 ## Configuration
 
-There's a number of settings you'll need to change before you can start hacking away at files. Here's a run down of what you'll need to change:
+There are a number of optional settings for you to configure. Use the example [`_config.yml`](https://github.com/daviddarnes/alembic/blob/master/_config.yml) file in the repo and use the documentation below to configure your site:
 
 ### Gem dependency settings
+
 `twitter`, `author` and `social` values will need to be changed to the projects' social information or removed. Look for the `Gem settings` comment within the `/_config.yml` file. These values are for the [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) - follow the link to find out more.
 
 ### Site settings
+
 You'll need to change the `description`, `title` and `url` to match with the project. You'll also need to replace the `/assets/logo.svg` and `/assets/default-social-image.png` with the project logo and default social image. Setting the site language can be done with `lang`, the theme will default to `en-US`. The `email` needs to be changed to the email you want to receive contact form enquires with. The `disqus` value can be changed to your project username on [Disqus](https://disqus.com), remove this from the `/_config.yml` file if you don't want comments enabled. Look for the `Site settings` comment within the `/_config.yml` file. The `repo` setting is optional, for now, and can be removed entirely, if you wish.
 
 ### Site navigation
+
 There are a total of 4 different navigation types:
 
 - `navigation_header`: The links shown in the header (it is also used on the 404 page)
@@ -124,7 +133,7 @@ Available options:
 - `text`: The text of the button _required_
 - `link`: The link that the button goes to _required_
 - `icon`: The icon that is added to the end of the button text
-- `color`: The color of the button
+- `color`: The colour of the button
 
 ### `figure.html`
 An image with optional caption.

_config.yml

@@ -18,11 +18,10 @@ exclude:
 - CNAME
 - Gemfile
 - Gemfile.lock
-- demo/*
 - alembic-jekyll-theme.gemspec
 
 # 2. Installed Gems
-gems:
+plugins:
 - jekyll-sitemap
 - jekyll-mentions
 - jekyll-paginate

_sass/_theme.scss

@@ -404,6 +404,9 @@ pre code {
 
 // Sassline overrides
 .typeset {
+  a > code {
+    text-shadow: none;
+  }
   .button,
   button {
     background-image: none;

alembic-jekyll-theme.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "alembic-jekyll-theme"
-  spec.version       = "2.2.5"
+  spec.version       = "2.3"
   spec.authors       = ["David Darnes"]
   spec.email         = ["[email protected]"]
 
@@ -15,15 +15,15 @@ Gem::Specification.new do |spec|
 
   spec.files         = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|_layouts|_includes|_sass|LICENSE|README)}i) }
 
-  spec.add_runtime_dependency "jekyll", "~> 3.4"
+  spec.add_runtime_dependency "jekyll", "~> 3.6"
   spec.add_runtime_dependency "jekyll-sitemap", "~> 0.13"
   spec.add_runtime_dependency "jekyll-mentions", "~> 1.2"
   spec.add_runtime_dependency "jekyll-paginate", "~> 1.1"
-  spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.2"
+  spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.3"
   spec.add_runtime_dependency "jekyll-redirect-from", "~> 0.12"
   spec.add_runtime_dependency "jekyll-default-layout", "~> 0.1"
   spec.add_runtime_dependency "jekyll-feed", "~> 0.9"
-  spec.add_runtime_dependency "jemoji", "~> 0.8"
+  spec.add_runtime_dependency "jemoji", "~> 0.9"
 
   spec.add_development_dependency "bundler", "~> 1.14"
 end