Improve installation documentation

- Close #8
2017-03-29 16:32:50 -04:00 · 2017-03-29 16:32:50 -04:00 · 544a6d32ad
parent c595cfe1df
commit 544a6d32ad
1 changed files with 125 additions and 24 deletions
--- a/README.md
+++ b/README.md
@ -23,7 +23,13 @@ with a few enhancements thrown in for good measure:
 ## Table of Contents

 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)
   2. [Google Fonts](#google-fonts)
   3. [Text](#text)
@ -33,26 +39,33 @@ with a few enhancements thrown in for good measure:
   7. [Reading Time](#reading-time)
   8. [Comments (via Disqus)](#comments-via-disqus)
   9. [Google Analytics](#google-analytics)
-3. [Layouts](#layouts)
+4. [Layouts](#layouts)
   1. [Default](#layout-default)
   2. [Post](#layout-post)
   3. [Page](#layout-page)
   4. [Home](#layout-home)
   5. [About](#layout-about)
   6. [Curriculum Vitæ/Resume](#layout-cv)
-4. [Customization](#customization)
+5. [Customization](#customization)
   1. [Overriding Includes and Layouts](#overriding-includes-and-layouts)
   2. [Customizing Sass (SCSS)](#customizing-sass-scss)
   3. [Customizing JavaScript](#customizing-javascript)
   4. [SVG Icons](#svg-icons)
   5. [Customizing Sidebar Content](#customizing-sidebar-content)
-5. [Development](#development)
-6. [Contributing](#contributing)
+6. [Development](#development)
+7. [Contributing](#contributing)
   1. [Pull Requests](#pull-requests)
-7. [Credits](#credits)
+8. [Credits](#credits)

 ## 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:

   ```ruby
@ -72,9 +85,91 @@ with a few enhancements thrown in for good measure:
   theme: jekyll-theme-basically-basic
   ```

-**Note:** 3rd-party Ruby gem themes aren't currently supported on sites hosted 
-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.
+### GitHub Pages Compatible Method
+
+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

@ -196,13 +291,18 @@ following pagination settings:
   ```

 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 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 
-in `_config.yml`:
+`creator` field of Twitter summary cards with the following front matter in 
+`_config.yml`:

 ```yaml
 author:
@ -211,8 +311,8 @@ author:
  picture: /assets/images/johndoe.png
 ```

-Site-wide author information can be overridden in a document's YAML Front Matter 
-in the same way:
+Site-wide author information can be overridden in a document's front matter in 
+the same way:

 ```yaml
 author:
@ -221,9 +321,9 @@ author:
  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 
-YAML Front Matter:
+front matter:

 ```yaml
 author: megaman
@ -268,7 +368,7 @@ with the following [environment value](http://jekyllrb.com/docs/configuration/#s
 `JEKYLL_ENV=production`

 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

@ -302,7 +402,7 @@ and provide additional styling and features inside of the `{{ content }}` block.

 ### `layout: post`

-This layout accommodates the following YAML Front Matter:
+This layout accommodates the following front matter:

 ```yaml
 # optional alternate title to replace page.title at the top of the page
@ -344,7 +444,7 @@ differences.

 ### `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:

 ```yaml
@ -353,7 +453,7 @@ paginate: true  # enables pagination loop, see section above for additional setu

 ### `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:

 ```yaml
@ -363,14 +463,14 @@ 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`.

 If blank there no image will appear.

 ### `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 
 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.
 3. Open a pull request on GitHub.

-Sample pages can be found in the [`/docs`](docs) folder if you'd like to tackle 
-any "low-hanging fruit" like fixing typos, bad grammar, etc.
+Sample pages can be found in the [`/docs`](docs) and [`/example`](/example) 
+folders if you'd like to tackle any "low-hanging fruit" like fixing typos, bad 
+grammar, etc.

 ---