This commit is contained in:
Michael Rose 2018-01-08 08:15:40 -05:00
commit 55ea8c0962
2 changed files with 173 additions and 71 deletions

View File

@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/) The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/). and this project adheres to [Semantic Versioning](http://semver.org/).
## Unreleased
### Changed
- New installation and upgrade instructions.
## [1.2.0] - 2018-01-05 ## [1.2.0] - 2018-01-05
### Added ### Added

201
README.md
View File

@ -25,10 +25,16 @@ with a few enhancements thrown in for good measure:
1. [Ruby Gem Method](#ruby-gem-method) 1. [Ruby Gem Method](#ruby-gem-method)
2. [GitHub Pages Method](#github-pages-method) 2. [GitHub Pages Method](#github-pages-method)
1. [Remove the Unnecessary](#remove-the-unnecessary) 1. [Remove the Unnecessary](#remove-the-unnecessary)
2. [Structure](#structure) 2. [Upgrading](#upgrading)
3. [Ruby Gem](#ruby-gem)
4. [Remote Theme](#remote-theme)
5. [Use Git](#use-git)
1. [Pull Down Updates](#pull-down-updates)
6. [Update Files Manually](#update-files-manually)
7. [Structure](#structure)
1. [Starting Fresh](#starting-fresh) 1. [Starting Fresh](#starting-fresh)
2. [Starting from jekyll new](#starting-from-jekyll-new) 2. [Starting from `jekyll new`](#starting-from-jekyll-new)
3. [Configuration](#configuration) 8. [Configuration](#configuration)
1. [Skin](#skin) 1. [Skin](#skin)
2. [Google Fonts](#google-fonts) 2. [Google Fonts](#google-fonts)
3. [Text](#text) 3. [Text](#text)
@ -38,78 +44,81 @@ with a few enhancements thrown in for good measure:
7. [Reading Time](#reading-time) 7. [Reading Time](#reading-time)
8. [Comments (via Disqus)](#comments-via-disqus) 8. [Comments (via Disqus)](#comments-via-disqus)
9. [Google Analytics](#google-analytics) 9. [Google Analytics](#google-analytics)
4. [Layouts](#layouts) 9. [Layouts](#layouts)
1. [Default](#layout-default) 1. [`layout: default`](#layout-default)
2. [Post](#layout-post) 2. [`layout: post`](#layout-post)
3. [Page](#layout-page) 3. [`layout: page`](#layout-page)
4. [Home](#layout-home) 4. [`layout: home`](#layout-home)
5. [About](#layout-about) 5. [`layout: about`](#layout-about)
6. [Curriculum Vitæ/Resume](#layout-cv) 6. [`layout: cv`](#layout-cv)
5. [Customization](#customization) 10. [Customization](#customization)
1. [Overriding Includes and Layouts](#overriding-includes-and-layouts) 1. [Overriding Includes and Layouts](#overriding-includes-and-layouts)
2. [Customizing Sass (SCSS)](#customizing-sass-scss) 2. [Customizing Sass (SCSS)](#customizing-sass-scss)
3. [Customizing JavaScript](#customizing-javascript) 3. [Customizing JavaScript](#customizing-javascript)
4. [SVG Icons](#svg-icons) 4. [SVG Icons](#svg-icons)
5. [Customizing Sidebar Content](#customizing-sidebar-content) 5. [Customizing Sidebar Content](#customizing-sidebar-content)
6. [Development](#development) 11. [Development](#development)
7. [Contributing](#contributing) 12. [Contributing](#contributing)
1. [Pull Requests](#pull-requests) 1. [Pull Requests](#pull-requests)
8. [Credits](#credits) 13. [Credits](#credits)
1. [Creator](#creator)
2. [Icons + Demo Images:](#icons--demo-images)
3. [Other:](#other)
14. [License](#license)
## Installation ## Installation
If you're running Jekyll v3.3+ and self-hosting you can quickly install the If you're running Jekyll v3.5+ and self-hosting you can quickly install the
theme as Ruby gem. If you're hosting with GitHub Pages you'll have to use the theme as a Ruby gem. If you're hosting with GitHub Pages you can install as a
"repo fork" method or directly copy all of the theme files (see remote theme or directly copy all of the theme files (see [structure](#structure)
[structure](#structure) below) into your project. below) into your project.
### Ruby Gem Method ### Ruby Gem Method
1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so: 1. Add this line to your Jekyll site's `Gemfile`:
```ruby ```ruby
gem "jekyll-theme-basically-basic" gem "jekyll-theme-basically-basic"
``` ```
2. Add this line to your Jekyll site's `_config.yml` file:
2. Fetch and update your bundled gems by running the following
[Bundler](http://bundler.io/) command:
```bash
bundle
```
3. Set the `theme` in your project's Jekyll configuration, `_config.yml`:
```yaml ```yaml
theme: jekyll-theme-basically-basic theme: jekyll-theme-basically-basic
``` ```
2. Then run [Bundler](http://bundler.io/) to install the theme gem and dependencies:
```terminal
bundle install
```
### GitHub Pages Method ### GitHub Pages Method
If you're hosting with GitHub Pages follow these steps instead: GitHub Pages has added [full support](https://github.com/blog/2464-use-any-theme-with-github-pages)
for any GitHub-hosted theme.
Replace `gem "jekyll"` with: 1. Replace `gem "jekyll"` with:
```ruby ```ruby
gem "github-pages", group: :jekyll_plugins gem "github-pages", group: :jekyll_plugins
``` ```
Run `bundle update` and verify that all gems install properly. 2. Run `bundle update` and verify that all gems install properly.
Add `remote_theme: "mmistakes/jekyll-theme-basically-basic"` to your `_config.yml` file. 3. Add `remote_theme: "mmistakes/jekyll-theme-basically-basic"` to your
`_config.yml` file. Remove any other `theme:` or `remote_theme:` entries.
Then add [`jekyll-remote-theme`](https://github.com/benbalter/jekyll-remote-theme) to the `plugins` (previously gems) array in your `_config.yml` file like so: ---
```yaml **Note:** Your Jekyll site should be viewable immediately at
plugins: <http://USERNAME.github.io>. If it's not, you can force a rebuild by
- jekyll-remote-theme **Customizing Your Site** (see below for more details).
```
Remove any other `theme:` or `remote_theme:` entry. If you're hosting several Jekyll based sites under the same GitHub username you
will have to use Project Pages instead of User Pages. Essentially you rename the
**Note:** Your Jekyll site should be viewable immediately at <http://USERNAME.github.io>. If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details). repo to something other than **USERNAME.github.io** and create a `gh-pages`
branch off of `master`. For more details on how to set things up check
If you're hosting several Jekyll based sites under the same GitHub username you will have to use Project Pages instead of User Pages. Essentially you rename the repo to something other than **USERNAME.github.io** and create a `gh-pages` branch off of `master`. For more details on how to set things up check [GitHub's documentation](https://help.github.com/articles/user-organization-and-project-pages/). [GitHub's documentation](https://help.github.com/articles/user-organization-and-project-pages/).
#### Remove the Unnecessary #### Remove the Unnecessary
@ -130,6 +139,95 @@ safely remove the following files and folders:
- `/docs` - `/docs`
- `/example` - `/example`
## Upgrading
If you're using the Ruby Gem or remote theme versions of Basically Basic,
upgrading is fairly painless.
To check which version you are currently using, view the source of your built
site and you should something similar to:
```
<!--
Basically Basic Jekyll Theme 1.2.0
Copyright 2017-2018 Michael Rose - mademistakes.com | @mmistakes
Free for personal and commercial use under the MIT license
https://github.com/mmistakes/jekyll-basically-theme/blob/master/LICENSE.md
-->
```
At the top of every `.html` file, `/assets/css/main.css`, and `/assets/js/main.js`.
## Ruby Gem
Simply run `bundle update` if you're using Bundler (have a `Gemfile`) or `gem
update jekyll-theme-basically-basic` if you're not.
## Remote Theme
When hosting with GitHub Pages you'll need to push up a commit to force a
rebuild with the latest [theme release](https://github.com/mmistakes/jekyll-theme-basically-basic/releases).
An empty commit will get the job done too if you don't have anything to push at
the moment:
```terminal
git commit --allow-empty -m "Force rebuild of site"
```
## Use Git
If you want to get the most out of the Jekyll + GitHub Pages workflow, then
you'll need to utilize Git. To pull down theme updates you must first ensure
there's an upstream remote. If you forked the theme's repo then you're likely
good to go.
To double check, run `git remote -v` and verify that you can fetch from `origin https://github.com/mmistakes/jekyll-theme-basically-basic.git`.
To add it you can do the following:
```terminal
git remote add upstream https://github.com/mmistakes/jekyll-theme-basically-basic.git
```
### Pull Down Updates
Now you can pull any commits made to theme's `master` branch with:
```terminal
git pull upstream master
```
Depending on the amount of customizations you've made after forking, there's
likely to be merge conflicts. Work through any conflicting files Git flags,
staging the changes you wish to keep, and then commit them.
## Update Files Manually
Another way of dealing with updates is [downloading the theme](https://github.com/mmistakes/jekyll-theme-basically-basic/archive/master.zip)
--- replacing your layouts, includes, and assets with the newer ones manually.
To be sure that you don't miss any changes it's probably a good idea to review
the theme's [commit history](https://github.com/mmistakes/jekyll-theme-basically-basic/commits/master)
to see what's changed since.
Here's a quick checklist of the important folders/files you'll want to be
mindful of:
| Name | |
| ---- | --- |
| `_layouts` | Replace all. Apply edits if you customized any layouts. |
| `_includes` | Replace all. Apply edits if you customized any includes. |
| `assets` | Replace all. Apply edits if you customized stylesheets or scripts. |
| `_sass` | Replace all. Apply edits if you customized Sass partials. |
| `_data/theme.yml` | Safe to keep. Verify that there were no major structural changes or additions. |
| `_config.yml` | Safe to keep. Verify that there were no major structural changes or additions. |
---
**Note:** If you're not seeing the latest version, be sure to flush browser and
CDN caches. Depending on your hosting environment older versions of
`/assets/css/main.css`, `/assets/js/main.js`, or `*.html` may be cached.
## Structure ## Structure
Layouts, includes, Sass partials, and data files are all placed in their default Layouts, includes, Sass partials, and data files are all placed in their default
@ -140,7 +238,7 @@ files in the project's root directory.
files found in `/_layouts`, `/_includes`, `/_sass`, and `/assets` will be files found in `/_layouts`, `/_includes`, `/_sass`, and `/assets` will be
missing. This is normal as they are bundled with the [`jekyll-theme-basically-basic`](https://rubygems.org/gems/jekyll-theme-basically-basic) gem. missing. This is normal as they are bundled with the [`jekyll-theme-basically-basic`](https://rubygems.org/gems/jekyll-theme-basically-basic) gem.
```bash ```terminal
jekyll-theme-basically-basic jekyll-theme-basically-basic
├── _data # data files ├── _data # data files
| └── theme.yml # theme settings and custom text | └── theme.yml # theme settings and custom text
@ -360,7 +458,8 @@ Front Matter.
Optionally, if you have a [Disqus](https://disqus.com/) account, you can show a Optionally, if you have a [Disqus](https://disqus.com/) account, you can show a
comments section below each post. comments section below each post.
To enable Disqus comments, add your [Disqus shortname](https://help.disqus.com/customer/portal/articles/466208) to your project's `_config.yml` file: To enable Disqus comments, add your [Disqus shortname](https://help.disqus.com/customer/portal/articles/466208) to your project's
`_config.yml` file:
```yaml ```yaml
disqus: disqus:
@ -521,19 +620,17 @@ To override the default [Sass](http://sass-lang.com/guide) (located in theme's
- Customize what you want inside `<your_project/assets/stylesheets/main.scss`. - Customize what you want inside `<your_project/assets/stylesheets/main.scss`.
**Note:** To make more extensive changes and customize the Sass partials bundled **Note:** To make more extensive changes and customize the Sass partials bundled
in the gem. You will need to copy the complete contents the `_sass` directory to in the gem. You will need to copy the complete contents of the `_sass` directory
`<your_project>` due to the way Jekyll currently reads those files. to `<your_project>` due to the way Jekyll currently reads those files.
To make basic tweaks to theme's style Sass variables can be overridden by adding To make basic tweaks to theme's style Sass variables can be overridden by adding
to `<your_project>/assets/stylesheets/main.scss`. For instance, to change the to `<your_project>/assets/stylesheets/main.scss`. For instance, to change the
accent color used throughout the theme add: accent color used throughout the theme add the following:
```scss ```scss
$accent-color: red; $accent-color: red;
``` ```
Before any `@import` lines.
### Customizing JavaScript ### Customizing JavaScript
To override the default JavaScript bundled in the theme, do one of the following: To override the default JavaScript bundled in the theme, do one of the following: