Merge branch 'master' of https://github.com/mmistakes/jekyll-theme-basically-basic
This commit is contained in:
Michael Rose
commit
55ea8c0962
|
|
@ -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
201
README.md
|
|
@ -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:
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue