Merge branch 'readme'

Improving Documentation

README.md

@@ -1,6 +1,7 @@
-[![Gem Version](https://badge.fury.io/rb/jekyll-sleek.svg)](https://badge.fury.io/rb/jekyll-sleek) [![Build Status](https://travis-ci.org/janczizikow/sleek.svg?branch=master)](https://travis-ci.org/janczizikow/sleek) [![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/janczizikow/sleek)
 # Sleek
 
+[![Gem Version](https://badge.fury.io/rb/jekyll-sleek.svg)](https://badge.fury.io/rb/jekyll-sleek) [![Build Status](https://travis-ci.org/janczizikow/sleek.svg?branch=master)](https://travis-ci.org/janczizikow/sleek) [![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/janczizikow/sleek)
+
 A modern [Jekyll](https://jekyllrb.com/) theme focused on speed performance & SEO best practices.
 
 ![Sleek Jekyll Theme](./sleek.jpg)
@@ -32,10 +33,10 @@ gem install jekyll
 
 Download and open the [NodeJS installer](https://nodejs.org/en/)
 
-#### Gulp.js (optional, but recommended)
+#### Gulp CLI (optional, but recommended)
 
 ```shell
-sudo npm install -g gulpfile
+npm install --global gulp-cli
 ```
 
 ### Up & Running
@@ -44,7 +45,7 @@ sudo npm install -g gulpfile
 2. Clone or download the repo into directory of your choice: `git clone https://github.com/your-github-username/sleek.git`
 3. Inside the directory run `bundle install` and `npm install`
 4. If you want to use [gulp.js](https://gulpjs.com/) run `gulp` or `npm start`
-  * if you don't want to use gulp you can simply run `bundle exec jekyll serve`
+    * if you don't want to use gulp you can run `bundle exec jekyll serve` instead
 
 #### Installing to existing jekyll project
 
@@ -90,21 +91,67 @@ sleek
 
 ## Usage
 
-TODO
+You can modify the theme by changing the settings in `_config.yml`.
+
+### Posts
+
+Create a new Markdown file such as 2017-01-13-my-post.md in _post folder. Configure YAML Front Matter (stuff between `---`):
+
+```yaml
+---
+layout: post # needs to be post
+title: Getting Started with Sleek # title of your post
+featured-img: sleek #optional - if you want you can include hero image
+---
+```
+
+#### Images
+
+In case you want to add a hero image to the post, apart from changing featured-img in YAML, you also need to add the image file to the project. To do so, just upload an image in .jpg format to `_img` folder. The name must before the .jpg file extension has to match with featured-img in YAML. Next, run `gulp img` from command line to generate optimized version of the image and all the thumbnails. You have to restart the jekyll server to see the changes.
+
+Sleek uses [Lazy Sizes](https://github.com/aFarkas/lazysizes). Lazy Loader for loading images. Check the link for more info. Lazy Sizes doesnt’t require any configuration and it’s going to be included in your bundled js file.
+
+### Pages
+
+The home page is located under index.md file. To change the content or design you have to edit the default.html file in `_layouts` folder.
+
+In order to add a new page, create a new html or markdown file under root directory or inside _pages folder. To add a link in navigation add it in `_config.yml`:
+
+```yaml
+# THEME SETTINGS
+navigation: # Navigation links
+  - {name: 'Home', link: '/'}
+  - {name: 'About', link: '/about'}
+  - {name: 'Contact', link: '/contact'}
+```
+
+`name` is the text that will be shown and link, well, it's a link.
 
 ### Site configuration
 
-TODO
+Sleek comes with [`jekyll-seo-tag`](https://github.com/jekyll/jekyll-seo-tag) plugin preinstalled to make sure your website gets the most useful meta tags. See [usage](https://github.com/jekyll/jekyll-seo-tag/blob/master/docs/usage.md) to know how to set it up.
+
+Additionally, in `_config.yml` you can find custom theme settings under `# THEME SETTINGS` comment. Here's a brief overview of those custom settings:
+
+- `navigation` - collection of links that will be shown in the header
+- `tagline` - text that will be displayed on the homepage under the heading.
+- `hero_img` - background image of the homepage hero section
+
+Other settings usually enable/disable certain feature, and are discussed with the next sections.
 
 ### Google Tag Manager
 
-To enable Google Tag Manager, add the following lines to `_config.yml`:
+To enable Google Tag Manager, add the uncomment the following line in `_config.yml`:
+
 ```yaml
 google_tag_manager: GTM-XXXXXXX
 ```
 
-where `GTM-XXXXXXX` is your Google Tag Manager Container ID.
-**Note** by default GTM tracking snippet will be also included in development. Google Tag Manager was chosen for this project as it's more flexible than Google Analytics, and it can be used to add GA to your site.
+Replace `GTM-XXXXXXX` with your Google Tag Manager Container ID.
+
+**Note** by default GTM tracking snippet will be also included in development environment.
+
+Google Tag Manager was chosen for this project as it's more flexible than Google Analytics, and it can be used to add GA to your site.
 
 ### Disqus
 
@@ -114,30 +161,30 @@ To enable Disqus comments, add your [Disqus shortname](https://help.disqus.com/c
 disqus:
   shortname: my_disqus_shortname
 ```
-### Formspree
 
+### Formspree
 
 To use [Formspree](https://formspree.io/) with your email address, you need to change the following:
 
 Change `your-email@domain.com` email in `_config.yml`
+
 ```yaml
 email: your-email@domain.com
 ```
 
 You can check if it works by simply submitting the form.
 
+If you have a Formspree Gold Account, you can take advantage of using AJAX to submit form. To do so, uncomment last function in `_js/scripts.js` and run `gulp js`. Now the form will be submitted asynchronously, without leaving the page.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/janczizikow/sleek. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/janczizikow/sleek](https://github.com/janczizikow/sleek). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## Development
 
 To set up your environment to develop this theme, run `bundle install` and `npm install`.
 
-Your theme is setup just like a normal Jekyll site! Check out [file structure overview](#file-structure-overview) for details. To test your theme, run `gulp` and open your browser at `http://localhost:3000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
-
-When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled.
-To add a custom directory to your theme-gem, please edit the regexp in `jekyll-sleek.gemspec` accordingly.
+The theme is setup just like a normal Jekyll site! Check out [file structure overview](#file-structure-overview) for details. To test the theme, run `gulp` and open your browser at `http://localhost:3000`. This starts a Jekyll server using the theme. Add pages, documents, data, etc. like normal to test the theme's contents. As you make modifications to the theme and to the content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
 
 ## License
 

_config.yml

@@ -1,15 +1,14 @@
+# SITE CONFIGURATION
 title: Sleek # your site title
-author: GitHub User
-email: your-email@domain.com # email for form submission, you also have to change it in _js/scripts.js
-description: > # this means to ignore newlines until "baseurl:"
+author: GitHub User # You :P
+description: > # Meta description of Homepage
   Write an awesome description for your new site here. You can edit this
   line in _config.yml. It will appear in your document head meta (for
   Google search results) and in your feed.xml site description.
-baseurl: "/" # the subpath of your site, e.g. /blog
-url: "https://janczizikow.github.io/sleek" # the base hostname & protocol for your site, e.g. http://example.com
-twitter_username: jan_czizikow # replace with your_twitter_username or comment to remove link from footer
-github_username:  janczizikow # replace with your_github_username or comment to remove link from footer
-instagram_username: shanlongjj # replace with your_instagram_username or comment to remove link from footer
+baseurl: "/sleek" # the subpath of your site, e.g. /blog
+url: "https://janczizikow.github.io/" # the base hostname & protocol for your site, e.g. http://example.com
+
+# SEO PLUGIN
 social:
   name: Your Name
   links:
@@ -20,13 +19,32 @@ social:
     - https://github.com/benbalter
     - https://keybase.io/benbalter
 
+# THEME SETTINGS
+navigation: # Navigation links
+  - {name: 'Home', link: '/'}
+  - {name: 'About', link: '/about'}
+  - {name: 'Contact', link: '/contact'}
+
+tagline: >
+  Modern Jekyll theme focused on speed performance & SEO best practices
+
+hero_img: posts/sleek_lg.jpg # Main background image: use the path from /assets/img/ => This will output /assets/img/posts/sleek_lg.jpg
+
+email: your-email@domain.com # email for form submission
+
+twitter_username: jan_czizikow # replace with your_twitter_username or comment to remove link from footer
+github_username:  janczizikow # replace with your_github_username or comment to remove link from footer
+instagram_username: shanlongjj # replace with your_instagram_username or comment to remove link from footer
+
 disqus:
   shortname: janczizikow # to enable comments replace with your_disqus_shortname
 
-# Build settings
+# google_tag_manager: GTM-XXXXXXX # Uncomment to enable GTM. Replace GTM-XXXXXXX with your GTM container ID
+
+# BUILD SETTINGS
 markdown: kramdown
 highlighter: rouge # or pygments or null
-theme: jekyll-sleek
+# theme: jekyll-sleek # Uncomment if you're using the theme as a ruby gem
 exclude:
   - README.md
   - node_modules

_includes/card.html

@@ -2,12 +2,12 @@
   {% if post.featured-img %}
   <figure class="post-card__thumb">
     <img
-      src="{{site.url}}/assets/img/posts/{{post.featured-img}}_placehold.jpg",
-      data-srcset="{{site.url}}/assets/img/posts/{{post.featured-img}}_thumb.jpg, {{site.url}}/assets/img/posts/{{post.featured-img}}_thumb@2x.jpg 2x"
+      src="{{ site.url }}{{ site.baseurl }}/assets/img/posts/{{post.featured-img}}_placehold.jpg",
+      data-srcset="{{ site.url }}{{ site.baseurl }}/assets/img/posts/{{post.featured-img}}_thumb.jpg, {{ site.url }}{{ site.baseurl }}/assets/img/posts/{{post.featured-img}}_thumb@2x.jpg 2x"
       class="lazyload blur"
       alt="{{post.title}}"
     />
-    <noscript><img src="{{site.url}}/assets/img/posts/{{post.featured-img}}_thumb.jpg" alt="{{ post.title }}"></noscript>
+    <noscript><img src="{{ site.url }}{{ site.baseurl }}/assets/img/posts/{{post.featured-img}}_thumb.jpg" alt="{{ post.title }}"></noscript>
   </figure>
   {% else %}
   <figure class="post-card__thumb">

_includes/header.html

@@ -8,11 +8,11 @@
       </a>
       <nav class="header__links">
         <div class="container header__links-wrapper">
-          <a class="header__link" href="{{ '/' | relative_url }}" itemprop="url"><span itemprop="name">Home</span></a>
-          <a class="header__link" href="{{ '/about' | relative_url }}" itemprop="url"><span itemprop="name">About</span></a>
-          <a class="header__link" href="{{ '/contact' | relative_url }}" itemprop="url">
-            <span itemprop="name">Contact</span>
-          </a>
+          {% for item in site.navigation %}
+            <a class="header__link" href="{{ item.link | relative_url }}" itemprop="url">
+              <span itemprop="name">{{ item.name }}</span>
+            </a>
+          {% endfor %}
         </div>
       </nav>
       <div class="header__toggle">

_layouts/default.html

@@ -18,10 +18,10 @@
 
     {% include header.html %}
 
-    <div class="hero lazyload" data-bg="{{site.url}}/assets/img/posts/sleek_lg.jpg">
+    <div class="hero lazyload" data-bg="{{ site.url }}{{ site.baseurl }}/assets/img/{{ site.hero_img }}">
       <div class="hero__wrap">
-        <h1 class="hero__title">Sleek</h1>
-        <p class="hero__meta">Modern Jekyll theme focused on speed performance & SEO best practices</p>
+        <h1 class="hero__title">{{ site.title | escape }}</h1>
+        <p class="hero__meta">{{ site.tagline }}</p>
       </div>
     </div>
 

_layouts/post.html

@@ -20,7 +20,7 @@
 
   {% if page.featured-img %}
 
-  <div class="hero lazyload" data-bg="{{site.url}}/assets/img/posts/{{page.featured-img}}.jpg">
+  <div class="hero lazyload" data-bg="{{ site.url }}{{ site.baseurl }}/assets/img/posts/{{ page.featured-img }}.jpg">
     {% else %}
     <div class="hero dark-bg">
       {% endif %}

_posts/2017-11-26-getting-started.md

@@ -5,15 +5,15 @@ featured-img: sleek
 mathjax: true
 ---
 
-## Getting started
+# Getting started
 
 [GitHub Pages](https://pages.github.com) can automatically generate and serve the website for you.
 Let's say you have a username/organisation `my-org` and project `my-proj`; if you locate Jekyll source under `blog` folder of master branch in your repo `github.com/my-org/my-proj`, the website will be served on `my-org.github.io/my-proj`.
 
 1. Just download or fork and clone the source from [github.com/janczizikow/sleek](https://github.com/janczizikow/sleek/).
 2. Make sure your local machine has ruby and node
-2. Edit site settings in  `_config.yml` file according to your project.
-3. Replace `favicons` and `_includes/logo.svg` with your own logo.
+3. Edit site settings in  `_config.yml` file according to your project.
+4. Replace `favicons` and `_includes/logo.svg` with your own logo.
 
 **Note** that you might have to adjust some CSS depending on the width and height of your logo. You can find Header / Navigation related SCSS in `_sass/layout/nav.scss`.
 
@@ -26,22 +26,22 @@ Create a new Markdown file such as `2017-01-13-my-post.md` in `_post` folder. Co
 ```yaml
 
 ---
-layout: post #need to be post
-title: Getting Started with Sleek #title of your post
-featured-img: sleek #optional - if you want you can include name of hero image
+layout: post # needs to be post
+title: Getting Started with Sleek # title of your post
+featured-img: sleek #optional - if you want you can include hero image
 ---
 
 ```
 
 #### Images
 
-In case you want to add a hero image to the post, apart from changing `featured-img` in YAML, you also need to add the image file to the project. To do so, just upload an image in `.jpg` format to `_img` folder. The name must before the `.jpg` file extension has to match with `featured-img` in YAML. Next, run `gulp img` from command line to generate optimized version of the image and all the thumbnails. You have to restart  the jekyll server to see the changes. Sleek uses (Lazy Sizes)[https://github.com/aFarkas/lazysizes] Lazy Loader for loading images. Check the link for more info. Lazy Sizes doesnt't require any configuration and it's going to be included in your bundled js file.
+In case you want to add a hero image to the post, apart from changing `featured-img` in YAML, you also need to add the image file to the project. To do so, just upload an image in `.jpg` format to `_img` folder. The name must before the `.jpg` file extension has to match with `featured-img` in YAML. Next, run `gulp img` from command line to generate optimized version of the image and all the thumbnails. You have to restart  the jekyll server to see the changes. Sleek uses [Lazy Sizes](https://github.com/aFarkas/lazysizes) Lazy Loader for loading images. Check the link for more info. Lazy Sizes doesnt't require any configuration and it's going to be included in your bundled js file.
 
 ### Pages
 
 The home page is located under `index.md` file. To change the content or design you have to edit the `default.html` file in `_layouts` folder.
 
-In order to add a new page, create a new html or markdown file under root directory or inside `_pages` folder and link it in `_includes/header.html`.
+In order to add a new page, create a new html or markdown file under root directory or inside `_pages` folder. To add a link to the page, edit `navigation` setting in `_config.yml`.
 
 ### Images TODO
 
@@ -55,7 +55,6 @@ md |Post Thumb | 329.375px | 658.75px
 lg |Post Thumb | 445.625px | 891.25px
 xl |Post Thumb | 353.125px | 706.25px
 
-
 Breakpoint | Image Type | Width | Retina
 ------------ | ------------ | ------------- | -------------
 xs |Post Hero | 535px | 1070px
@@ -72,12 +71,12 @@ If you want to use [MathJax](https://www.mathjax.org/) in your posts, add `mathj
 ---
 layout: post
 title: Blog Post with MathJax
-featured-img: sleek #optional - if you want you can include name of hero image
-mathjax: true #add this line in order to enable MathJax in the post
+featured-img: sleek # optional - if you want you can include name of hero image
+mathjax: true # add this line in order to enable MathJax in the post
 ---
 ```
 
-#### Example:
+#### Example
 
 In N-dimensional simplex noise, the squared kernel summation radius $r^2$ is $\frac 1 2$
 for all values of N. This is because the edge length of the N-simplex $s = \sqrt {\frac {N} {N + 1}}$

_sass/layout/_footer.scss

@@ -9,7 +9,8 @@ footer {
     color: rgba(33,33,33,0.6);
     border-bottom: 0;
 
-    &:hover {
+    &:hover,
+    &:focus {
       color: $primary;
       border-bottom: 0;
     }
@@ -18,14 +19,14 @@ footer {
 
 .social {
   display: flex;
-  justify-content: space-around;
+  justify-content: center;
   align-items: center;
   max-width: 200px;
   margin: 0 auto 25px;
 }
 
 .social__link:not(:last-child) {
-  margin-right: 1.125rem;
+  margin-right: 1.5rem;
 }
 
 .social__icon {