Add layout documentation

2017-03-08 16:07:22 -05:00 · 2017-03-08 16:07:22 -05:00 · 56ae20eccd
parent a12a907943
commit 56ae20eccd
1 changed files with 144 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,12 @@
 # WIP Basically Basic Jekyll Theme

-Basically Basic is a [Jekyll theme](https://jekyllrb.com/docs/themes/) meant as a substitute for the default `jekyll new` theme --- [Minima](https://github.com/jekyll/minima). Conventions and features found in Minima are fully supported by **Basically Basic**, with a few enhancements here and there.
+Basically Basic is a [Jekyll theme](https://jekyllrb.com/docs/themes/) meant as a substitute for the default `jekyll new` theme --- [Minima](https://github.com/jekyll/minima). Conventions and features found in Minima are fully supported by **Basically Basic**, with a few enhancements here and there:
+
+- Clean responsive design with six customizable variations
+- About page layout
+- Curriculum Vitæ/Resume layout powered by [JSON data](http://registry.jsonresume.org/)
+- Disqus Comments and Google Analytics support
+- SEO best practices via [Jekyll SEO Tag](https://github.com/jekyll/jekyll-seo-tag/)

 ## Table of Contents

@ -72,6 +78,48 @@ Break up the main listing of posts into smaller lists and display them over mult

 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.

+### 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`:
+
+```yaml
+author:
+  name: John Doe
+  twitter: johndoetwitter
+  picture: /assets/images/johndoe.png
+```
+
+Site-wide author information can be overridden in a document's YAML Front Matter in the same way:
+
+```yaml
+author:
+  name: Jane Doe
+  twitter: janedoetwitter
+  picture: /assets/images/janedoe.png
+```
+
+Or by specifying a corresponding key in the document's YAML Front Matter, that exists in `site.data.authors`. E.g., you have the following in the document's YAML Front Matter:
+
+```yaml
+author: megaman
+```
+
+And you have the following in `_data/authors.yml`:
+
+```yaml
+megaman:
+  name: Mega Man
+  twitter: megamantwitter
+  picture: /assets/images/megaman.png
+
+drlight:
+  name: Dr. Light
+  twitter: drlighttwitter
+  picture: /assets/images/drlight.png
+```
+
+Currently `author.picture` is only used in `layout: about`. Recommended size is `300 x 300` pixels.
+
 ### Comments (via Disqus)

 Optionally, if you have a [Disqus](https://disqus.com/) account, you can show a comments section below each post.
@ -109,16 +157,77 @@ layout: name

 ### `layout: default`

+This layout handles all of the basic page scaffolding placing the page content between the masthead and footer elements. All other layouts inherit this one and provide additional styling and features inside of the `{{ content }}` block.
+
 ### `layout: post`

+This layout accommodates the following YAML Front Matter:
+
+```yaml
+# optional alternate title to replace page.title at the top of the page
+alt_title: "Basically Basic"
+
+# optional sub-title below the page title
+sub_title: "The name says it all"
+
+# optional intro text below titles, Markdown allowed
+introduction: |
+    Basically Basic is a Jekyll theme meant to be a substitute for the default `jekyll new` theme --- [Minima](https://github.com/jekyll/minima). Conventions and features found in Minima are fully supported by **Basically Basic**.
+
+# optional call to action links
+actions:
+  - label: "Learn More"
+    icon: github  # references name of svg icon, see full list below
+    url: "http://url-goes-here.com"
+  - label: "Download"
+    icon: download  # references name of svg icon, see full list below
+    url: "http://url-goes-here.com"
+
+image:  # URL to an image associated with the post (e.g., /assets/page-pic.jpg)
+
+# post specific author data if different from what is set in _config.yml 
+author:
+  name: John Doe
+  twitter: johndoetwitter
+
+comments: false  # disable comments on this post
+```
+
 ### `layout: page`

+Visually this layout looks and acts the same as `layout: post`, with two minor differences.
+
+- Author "by line" and publish date are omitted.
+- Disqus comments are omitted.
+
 ### `layout: home`

+This layout accommodates the same YAML Front Matter as `layout: page`, with the addition of the following:
+
+```yaml
+paginate: true  # enables pagination loop, see section above for additional setup
+```
+
 ### `layout: about`

+This layout accommodates the same YAML Front Matter as `layout: page`, with the addition of the following to display an author picture:
+
+```yaml
+author:
+  name: John Doe
+  picture /assets/images/johndoe.png
+```
+
+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 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 leverages a [JSON-based file standard](https://jsonresume.org/schema/) for resume data to conveniently render a curriculum vitæ or resume painlessly.
+
+Simply use JSON Resume's [in-browser resume builder](http://registry.jsonresume.org/) to export a JSON file and save to your project as `_data/cv.json`.
+
 ## Customization

 The default structure, style, and scripts of this theme can be overridden and customized in the following two ways.
@ -172,6 +281,40 @@ To override the default JavaScript bundled in the theme, do one of the following
  - Copy the contents of [assets/javascripts/main.js](assets/javascripts/main.js) to `<your_project>`.
  - Customize want you want inside `<your_project>/assets/javascripts/main.js`.

+### SVG Icons
+
+The theme uses social network logos and other iconography saved as SVGs for performance and flexibility. Said SVGs are located in the `_includes` directory and prefixed with `icon-`. Each icon has been sized and designed to fit a `16 x 16` viewbox and optimized with [SVGO](https://github.com/svg/svgo).
+
+Fill colors are defined in the `_sass/basically-basic/_icons.scss` partial and set with `.icon-name` where class name matches the corresponding icon.
+
+For example the Twitter icon is given a fill color of `#1da1f2` like so:
+
+```html
+<span class="icon icon--twitter">{% include icon-twitter.svg %}</span>
+```
+
+Alongside the SVG assets, there are icon helper includes to aid in generating social network links.
+
+| Include Parameter | Description                      | Required                |
+| ----------------- | ---------------------------------| ----------------------- |
+| `username`        | Username on given social network | **Required**            |
+| `label`           | Text used for hyperlink | Optional, defaults to `username` |
+
+For example, the following `icon-github.html` include:
+
+```liquid
+{% include icon-github.html username=jekyll label='GitHub' %}
+```
+
+Will output the following HTML:
+
+```html
+<a href="https://github.com/jekyll">
+  <span class="icon icon--github"><svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" clip-rule="evenodd" stroke-linejoin="round" stroke-miterlimit="1.414"><path d="M8 0C3.58 0 0 3.582 0 8c0 3.535 2.292 6.533 5.47 7.59.4.075.547-.172.547-.385 0-.19-.007-.693-.01-1.36-2.226.483-2.695-1.073-2.695-1.073-.364-.924-.89-1.17-.89-1.17-.725-.496.056-.486.056-.486.803.056 1.225.824 1.225.824.714 1.223 1.873.87 2.33.665.072-.517.278-.87.507-1.07-1.777-.2-3.644-.888-3.644-3.953 0-.873.31-1.587.823-2.147-.09-.202-.36-1.015.07-2.117 0 0 .67-.215 2.2.82.64-.178 1.32-.266 2-.27.68.004 1.36.092 2 .27 1.52-1.035 2.19-.82 2.19-.82.43 1.102.16 1.915.08 2.117.51.56.82 1.274.82 2.147 0 3.073-1.87 3.75-3.65 3.947.28.24.54.73.54 1.48 0 1.07-.01 1.93-.01 2.19 0 .21.14.46.55.38C13.71 14.53 16 11.53 16 8c0-4.418-3.582-8-8-8"></path></svg></span>
+  <span class="label">GitHub</span>
+</a>
+```
+
 ### Customizing Sidebar Content

 ---