From 0b620f609a25613d25162ef97b30ab76abe86ea7 Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Tue, 7 Mar 2017 16:11:32 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 265 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e3a361c --- /dev/null +++ b/README.md @@ -0,0 +1,265 @@ +# 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. + +## Table of Contents + +## Installation + +1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so: + + ```ruby + gem "jekyll-theme-basically-basic", :git => "https://github.com/mmistakes/jekyll-theme-basically-basic.git" + ``` + +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 + theme: jekyll-theme-basically-basic + ``` + +## Configuration + +Configuration of site-wide elements (`title`, `description`, `author`, etc.) happens in your project's `_config.yml`. See the [example configuration](/example/_config.yml) for reference. + +### Skin + +This theme comes in six different skins (color variations). To change skins edit your project's `_config.yml` to one of the following: + +| `theme_skin: default` | `theme_skin: night` | `theme_skin: plum` | +| `theme_skin: sea` | `theme_skin: soft` | `theme_skin: steel` | + +### Navigation + +By default all internal pages with a `title` will be added to the "off-canvas" menu. For more granular control and sorting of these menu links: + +1. Create a custom list to override the default setting by adding a `navigation_pages` array to your `_config.yml` file. + +2. Add raw page paths in the order you'd like: + + ```yaml + navigation_pages: + - about.md + - cv.md + ``` + +Each menu link's title and URL will be populated based on their `title` and `permalink` respectively. + +### Pagination + +Break up the main listing of posts into smaller lists and display them over multiple pages by [enabling pagination](http://jekyllrb.com/docs/pagination/). + +1. Include the `jekyll-paginate` plugin in your `Gemfile`. + + ```ruby + group :jekyll_plugins do + gem "jekyll-paginate" + end + ``` + +2. Add `jekyll-paginate` to `gems` array in your `_config.yml` file and the following pagination settings: + + ```yaml + paginate: 5 # amount of posts to show per page + paginate_path: /page:num/ + ``` + +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. + +### Comments (via Disqus) + +Optionally, if you have a [Disqus](https://disqus.com/) account, you can show a 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: + +```yaml + disqus: + shortname: my_disqus_shortname +``` + +Comments are enabled by default and will only appear in production when built with the following [environment value](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time): `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. + +### Google Analytics + +To enable Google Analytics, add your [tracking ID](https://support.google.com/analytics/answer/1032385) to `_config.yml` like so: + +```yaml + google_analytics: UA-NNNNNNNN-N +``` + +Similar to comments, the Google Analytics tracking script will only appear in production when using the following environment value: `JEKYLL_ENV=production`. + +## Layouts + +This theme provides the following layouts, which you can use by setting the `layout` [Front Matter](https://jekyllrb.com/docs/frontmatter/) on each page, like so: + +```yaml +--- +layout: name +--- +``` + +### `layout: default` + +### `layout: post` + +### `layout: page` + +### `layout: home` + +### `layout: about` + +### `layout: cv` + +## Customization + +The default structure, style, and scripts of this theme can be overridden and customized in the following two ways. + +### Overriding Includes and Layouts + +Theme defaults can be [overridden](http://jekyllrb.com/docs/themes/#overriding-theme-defaults) by placing a file with the same name into your project's `_includes` or `_layouts` directory. For instance: + +- To specify a custom style path or meta data to the [`_includes/head.html `](_includes/head.html) file, create an `_includes` directory in your project, copy `_includes/head.html` from Basically +Basic's gem folder to `/_includes` and start editing that file. + +**ProTip:** to locate the theme's files on your computer run `bundle show jekyll-theme-basically-basic`. This returns the location of the gem-based theme files. + +### Customizing Sass (SCSS) + +To override the default [Sass](http://sass-lang.com/guide) (located in theme's `_sass` directory), do one of the following: + +1. Copy directly from the Basically Basic gem + + - Go to your local Basically Basic gem installation directory (run `bundle show jekyll-theme-basically-basic` to get the path to it). + - Copy the contents of `/assets/stylesheets/main.scss` from there to ``. + - Customize want you want inside `/assets/stylesheets/main.scss`. + +2. Copy from this repo. + + - Copy the contents of [assets/stylesheets/main.scss](assets/stylesheets/main.scss) to ``. + - Customize want you want inside `` 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 `/assets/stylesheets/main.scss`. For instance, to change the accent color used throughout the theme add: + +```scss +$accent-color: red; +``` + +Before any `@import` lines. + +### Customizing JavaScript + +To override the default JavaScript bundled in the theme, do one of the following: + +1. Copy directly from the Basically Basic gem + + - Go to your local Basically Basic gem installation directory (run `bundle show jekyll-theme-basically-basic` to get the path to it). + - Copy the contents of `/assets/javascripts/main.js` from there to ``. + - Customize want you want inside `/assets/javascripts/main.js`. + +2. Copy from this repo. + + - Copy the contents of [assets/javascripts/main.js](assets/javascripts/main.js) to ``. + - Customize want you want inside `/assets/javascripts/main.js`. + +### Customizing Sidebar Content + +--- + +## Development + +To set up your environment to develop this theme: + +1. Clone this repo +2. `cd` into `/example` and run `bundle install`. + +To test the theme the locally as you make changes to it: + +1. `cd` into the root folder of the repo (e.g. `jekyll-theme-basically-basic`). +2. Run `bundle exec rake preview` and open your browser to `http://localhost:4000/example/`. + +This starts a Jekyll server using the theme's files and contents of the `example/` directory. As modifications are made, refresh your browser to see any changes. + +## Contributing + +Found a typo in the documentation? Interested in adding a feature or +[fixing a bug][issues]? Then by all means [submit an issue][new-issue] or take a +stab at submitting a [pull request][using-pull-requests]. If this is your first +pull request, it may be helpful to read up on the [GitHub Flow][github-flow]. + +[issues]: https://github.com/mmistakes/jekyll-theme-basically-basic/issues +[new-issue]: https://github.com/mmistakes/jekyll-theme-basically-basic/issues/new +[using-pull-requests]: https://help.github.com/articles/using-pull-requests/ +[github-flow]: https://guides.github.com/introduction/flow/ + +### Pull Requests + +When submitting a pull request: + +1. Clone the repo. +2. Create a branch off of `develop` and give it a meaningful name (e.g. + `my-awesome-new-feature`) and describe the feature or fix. +3. Open a pull request on GitHub. + +Theme documentation and 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. + +--- + +## Credits + +### Creator + +**Michael Rose** + +- +- +- + +### Icons + Demo Images: + +- [Simple Icons](https://simpleicons.org/) +- [Noun Project](https://thenounproject.com) +- [Unsplash](https://unsplash.com/) + +### Other: + +- [Jekyll](http://jekyllrb.com/) +- [Susy](http://susy.oddbird.net/) +- [Breakpoint](http://breakpoint-sass.com/) + +--- + +## License + +The MIT License (MIT) + +Copyright (c) 2017 Michael Rose + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.