Improve installation documentation

- Close #8
This commit is contained in:
Michael Rose 2017-03-29 16:32:50 -04:00
parent c595cfe1df
commit 544a6d32ad
1 changed files with 125 additions and 24 deletions

149
README.md
View File

@ -23,7 +23,13 @@ with a few enhancements thrown in for good measure:
## Table of Contents ## Table of Contents
1. [Installation](#installation) 1. [Installation](#installation)
2. [Configuration](#configuration) 1. [Ruby Gem Method](#ruby-gem-method)
2. [GitHub Pages Compatible Method](#github-pages-compatible-method)
1. [Remove the Unnecessary](#remove-the-unnecessary)
2. [Structure](#structure)
1. [Starting Fresh](#starting-fresh)
2. [Starting from jekyll new](#starting-from-jekyll-new)
3. [Configuration](#configuration)
1. [Skin](#skin) 1. [Skin](#skin)
2. [Google Fonts](#google-fonts) 2. [Google Fonts](#google-fonts)
3. [Text](#text) 3. [Text](#text)
@ -33,26 +39,33 @@ 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)
3. [Layouts](#layouts) 4. [Layouts](#layouts)
1. [Default](#layout-default) 1. [Default](#layout-default)
2. [Post](#layout-post) 2. [Post](#layout-post)
3. [Page](#layout-page) 3. [Page](#layout-page)
4. [Home](#layout-home) 4. [Home](#layout-home)
5. [About](#layout-about) 5. [About](#layout-about)
6. [Curriculum Vitæ/Resume](#layout-cv) 6. [Curriculum Vitæ/Resume](#layout-cv)
4. [Customization](#customization) 5. [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)
5. [Development](#development) 6. [Development](#development)
6. [Contributing](#contributing) 7. [Contributing](#contributing)
1. [Pull Requests](#pull-requests) 1. [Pull Requests](#pull-requests)
7. [Credits](#credits) 8. [Credits](#credits)
## Installation ## Installation
If you're running Jekyll v3.3+ 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
"repo fork" method or directly copy all of the theme files (see
[structure](#structure) below) into your project.
### Ruby Gem Method
1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so: 1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so:
```ruby ```ruby
@ -72,9 +85,91 @@ with a few enhancements thrown in for good measure:
theme: jekyll-theme-basically-basic theme: jekyll-theme-basically-basic
``` ```
**Note:** 3rd-party Ruby gem themes aren't currently supported on sites hosted ### GitHub Pages Compatible Method
with [GitHub Pages](https://pages.github.com/). Basically Basic can still be
used on GH Pages, but you will need to fork the theme instead. Fork the [Basically Basic repo](https://github.com/mmistakes/jekyll-theme-basically-basic/fork),
then rename it to **USERNAME.github.io** --- replacing **USERNAME** with your
GitHub username.
**Note:** Your Jekyll site should be viewable immediately at
<http://USERNAME.github.io>. If it's not, you can force a rebuild by
**configuring your site** (see below for more details).
Replace the contents of `Gemfile` found in the root of your Jekyll site with
the following:
```ruby
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
```
Then run `bundle update` and verify that the [GitHub Pages gem](https://github.com/github/pages-gem)
and its dependencies install properly.
#### Remove the Unnecessary
If you forked or downloaded the `jekyll-theme-basically-basic` repo you can
safely remove the following files and folders:
- `.codeclimate.yml`
- `.editorconfig`
- `.gitattributes`
- `.github`
- `.scss-lint.yml`
- `CHANGELOG.md`
- `jekyll-theme-basically-basic.gemspec`
- `LICENSE.md`
- `Rakefile`
- `README.md`
- `screenshot.png`
- `/docs`
- `/example`
## Structure
Layouts, includes, Sass partials, and data files are all placed in their default
locations. Stylesheets and scripts in `assets`, and a few development related
files in the project's root directory.
**Please note:** If you installed Basically Basic via the Ruby Gem method, theme
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.
```bash
jekyll-theme-basically-basic
├── _data # data files
| └── theme.yml # theme settings and custom text
├── _includes # theme includes and SVG icons
├── _layouts # theme layouts (see below for details)
├── _sass # Sass partials
├── assets
| ├── javascripts
| | └── main.js
| ├── stylesheets
| | └── main.scss
├── _config.yml # sample configuration
└── index.md # sample home page (all posts/not paginated)
```
### Starting Fresh
After creating a `Gemfile` and installing the theme you'll need to add and edit
the following files:
- [`_config.yml`](_config.yml)
- [`/_data/theme.yml`](_data/theme.yml)
- [`index.md`](index.md)
**Note:** Consult the [**pagination**](#pagination) documentation below for
instructions on how to enable it for the home page.
### Starting from `jekyll new`
Using the `jekyll new` command will get you up and running the quickest.
Edit `_config.yml` and create `_data/theme.yml` as instructed above and you're
good to go.
## Configuration ## Configuration
@ -196,13 +291,18 @@ following pagination settings:
``` ```
3. Create `index.html` (or rename `index.md`) in the root of your project and 3. Create `index.html` (or rename `index.md`) in the root of your project and
add `layout: home` `paginate: true` to its YAML Front Matter. add the following front matter:
```yaml
layout: home
paginate: true
```
### Author ### Author
Author information is used as meta data for post "by lines" and propagates the Author information is used as meta data for post "by lines" and propagates the
`creator` field of Twitter summary cards with the following YAML Front Matter `creator` field of Twitter summary cards with the following front matter in
in `_config.yml`: `_config.yml`:
```yaml ```yaml
author: author:
@ -211,8 +311,8 @@ author:
picture: /assets/images/johndoe.png picture: /assets/images/johndoe.png
``` ```
Site-wide author information can be overridden in a document's YAML Front Matter Site-wide author information can be overridden in a document's front matter in
in the same way: the same way:
```yaml ```yaml
author: author:
@ -221,9 +321,9 @@ author:
picture: /assets/images/janedoe.png picture: /assets/images/janedoe.png
``` ```
Or by specifying a corresponding key in the document's YAML Front Matter, that Or by specifying a corresponding key in the document's front matter, that
exists in `site.data.authors`. E.g., you have the following in the document's exists in `site.data.authors`. E.g., you have the following in the document's
YAML Front Matter: front matter:
```yaml ```yaml
author: megaman author: megaman
@ -268,7 +368,7 @@ with the following [environment value](http://jekyllrb.com/docs/configuration/#s
`JEKYLL_ENV=production` `JEKYLL_ENV=production`
If you don't want to display comments for a particular post you can disable If you don't want to display comments for a particular post you can disable
them by adding `comments: false` to that post's YAML Front Matter. them by adding `comments: false` to that post's front matter.
### Google Analytics ### Google Analytics
@ -302,7 +402,7 @@ and provide additional styling and features inside of the `{{ content }}` block.
### `layout: post` ### `layout: post`
This layout accommodates the following YAML Front Matter: This layout accommodates the following front matter:
```yaml ```yaml
# optional alternate title to replace page.title at the top of the page # optional alternate title to replace page.title at the top of the page
@ -344,7 +444,7 @@ differences.
### `layout: home` ### `layout: home`
This layout accommodates the same YAML Front Matter as `layout: page`, with the This layout accommodates the same front matter as `layout: page`, with the
addition of the following: addition of the following:
```yaml ```yaml
@ -353,7 +453,7 @@ paginate: true # enables pagination loop, see section above for additional setu
### `layout: about` ### `layout: about`
This layout accommodates the same YAML Front Matter as `layout: page`, with the This layout accommodates the same front matter as `layout: page`, with the
addition of the following to display an author picture: addition of the following to display an author picture:
```yaml ```yaml
@ -363,14 +463,14 @@ author:
``` ```
Recommended `picture` size is approximately `300 x 300` pixels. If `author` Recommended `picture` size is approximately `300 x 300` pixels. If `author`
object is not explicitly set in the about page's YAML Front Matter the theme object is not explicitly set in the about page's front matter the theme
will default to the value set in `_config.yml`. will default to the value set in `_config.yml`.
If blank there no image will appear. If blank there no image will appear.
### `layout: cv` ### `layout: cv`
This layout accommodates the same YAML Front Matter as `layout: page`. It This layout accommodates the same front matter as `layout: page`. It
leverages a [JSON-based file standard](https://jsonresume.org/schema/) for leverages a [JSON-based file standard](https://jsonresume.org/schema/) for
resume data to conveniently render a curriculum vitæ or resume painlessly. resume data to conveniently render a curriculum vitæ or resume painlessly.
@ -558,8 +658,9 @@ When submitting a pull request:
`my-awesome-new-feature`) and describe the feature or fix. `my-awesome-new-feature`) and describe the feature or fix.
3. Open a pull request on GitHub. 3. Open a pull request on GitHub.
Sample pages can be found in the [`/docs`](docs) folder if you'd like to tackle Sample pages can be found in the [`/docs`](docs) and [`/example`](/example)
any "low-hanging fruit" like fixing typos, bad grammar, etc. folders if you'd like to tackle any "low-hanging fruit" like fixing typos, bad
grammar, etc.
--- ---