From ccdc0e3118bb5212efc5160dc08f1773049fbb90 Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Sat, 24 Aug 2013 17:51:19 -0400 Subject: [PATCH] Document Grunt build script --- README.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++-- about.md | 1 + theme-setup.md | 44 ++++++------------- 3 files changed, 124 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 3eb966b..d0d17a5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,115 @@ -hpstr-jekyll-theme -================== +# HPSTR RDX Jekyll Theme -Jekyll theme. Documentation soon... +They say three times the charm, so here is another free responsive Jekyll theme for you. I've learned a ton since open sourcing my first two themes [on Github](http://github.com/mmistakes), and wanted to try a few new things this time around. If you've used my previous themes most of this should be familiar territory... + +## What HPSTR RDX brings to the table: + +* Responsive templates for post, page, and post index `_layouts`. Looks great on mobile, tablet, and desktop devices. +* Gracefully degrads in older browsers. Compatible with Internet Explorer 8+ and all modern browsers. +* Modern and minimal design. +* Sweet animated menu. +* Readable typography to make your words shine. +* Support for large images to call out your favorite posts. +* Comments powered by [Disqus](http://disqus.com) if you choose to enable. +* Simple and clear permalink structure. +* [Open Graph](https://developers.facebook.com/docs/opengraph/) and [Twitter Cards](https://dev.twitter.com/docs/cards) support for a better social sharing experience. +* Simple [custom 404 page]({{ site.url }}/404.html) to get you started. +* Stylesheets for Pygments and Coderay [syntax highlighting]({{ site.url }}/code-highlighting-post/) to make your code examples look snazzy +* Grunt build script for easy theme development ## [Theme Preview](http://mmistakes.github.io/hpstr-jekyll-theme) ![HPSTR RDX Theme Preview screenshot](http://mmistakes.github.io/hpstr-jekyll-theme/images/hpstr-jekyll-theme-preview.jpg) + +--- + +General notes and suggestions for customizing **HPSTR RDX**. + +## Basic Setup for a new Jekyll site + +1. [Install Jekyll](http://jekyllrb.com) and read through the documentation if you haven't already. +2. Fork the [HPSTR RDX repo](https://github.com/mmistakes/hpstr-rdx-theme/fork) +3. Clone the repo you just forked to your computer. +4. Edit `_config.yml` to personalize your site. +5. Check out the sample posts in `_posts` to see examples for pulling in large feature images, tags, and other YAML data. +6. Read the documentation below for further customization pointers and documentation. + +### [Download the Theme](https://github.com/mmistakes/hpstr-jekyll-theme) + +**Pro-tip:** Delete the `gh-pages` branch after cloning and start fresh by branching off `master`. There is a bunch of garbage in `gh-pages` used for the theme's demo that I'm guessing you don't want on your site. +{:.notice} + +--- + +## Setup for an Existing Jekyll site + +1. Clone the following folders: `_includes`, `_layouts`, `assets`, and `images`. +2. Clone the following files and personalize content as need: `about.md`, `archive.html`, `index.html`, `tags.html`, and `feed.xml`. +3. Set the following variables in your `config.yml` file: + +``` yaml +title: Site Title +description: Describe your website here. +disqus_shortname: shortname +url: http://your-website.com + +# Owner/author information +owner: + name: Your Name + avatar: avatar.jpg + bio: "Your bio goes here. It shouldn't be super long but a good two sentences or two should suffice." + email: you@email.com + # Social networking links used in footer. Update and remove as you like. + twitter: + facebook: + github: + stackexchange: + linkedin: + instagram: + flickr: + tumblr: + # For Google Authorship https://plus.google.com/authorship + google_plus: + +# Analytics and webmaster tools stuff goes here +google_analytics: +google_verify: +# https://ssl.bing.com/webmaster/configure/verify/ownership Option 2 content= goes here +bing_verify: + +# Links to include in top navigation +# For external links add external: true +links: + - title: Theme Setup + url: /theme-setup + - title: External Link + url: http://mademistakes.com + external: true + +# http://en.wikipedia.org/wiki/List_of_tz_database_time_zones +timezone: America/New_York +future: true +pygments: true +markdown: kramdown + +# Amount of posts to show on home page +paginate: 5 +``` + +--- + +## [More Theme Setup Goodness](http://mmistakes.github.io/hpstr-jekyll-theme/theme-setup/) + +To learn more about how to customize the theme, how feature images work, use the Grunt build script, and some other junk, [read up here](http://mmistakes.github.io/hpstr-jekyll-theme/theme-setup/). + +--- + +## Questions? + +Having a problem getting something to work or want to know why I setup something in a certain way? Ping me on Twitter [@mmistakes](http://twitter.com/mmistakes) or [file a GitHub Issue](https://github.com/mmistakes/hpstr-jekyll-theme/issues/new). And if you make something cool with this theme feel free to let me know. + +--- + +## License + +This theme is free and open source software, distributed under the [GNU General Public License](https://github.com/mmistakes/hpstr-jekyll-theme/blob/master/LICENSE) version 2 or later. So feel free to use this Jekyll theme on your site without linking back to me or including a disclaimer. diff --git a/about.md b/about.md index 29be2e5..9c99225 100644 --- a/about.md +++ b/about.md @@ -24,6 +24,7 @@ They say three times the charm, so here is another free responsive Jekyll theme * [Open Graph](https://developers.facebook.com/docs/opengraph/) and [Twitter Cards](https://dev.twitter.com/docs/cards) support for a better social sharing experience. * Simple [custom 404 page]({{ site.url }}/404.html) to get you started. * Stylesheets for Pygments and Coderay [syntax highlighting]({{ site.url }}/code-highlighting-post/) to make your code examples look snazzy +* Grunt build script for easy theme development
Install the Theme
diff --git a/theme-setup.md b/theme-setup.md index 09fb227..3062b7a 100644 --- a/theme-setup.md +++ b/theme-setup.md @@ -37,7 +37,6 @@ General notes and suggestions for customizing **HPSTR RDX**. {% highlight yaml %} title: Site Title description: Describe your website here. -logo: site-logo.png disqus_shortname: shortname url: http://your-website.com @@ -104,8 +103,10 @@ hpstr-rdx-theme/ ├── assets | ├── css # preprocessed less styles | ├── js -| | ├── main.js # concatenated vendor scripts -| | └── vendor # 3rd party scripts +| | ├── _main.js # plugin options +| | ├── scripts.min.js # concatenated and minifed site scripts +| | ├── plugins # plugin scripts +| | └── vendor # jQuery and Modernizr scripts | └── less ├── images # images for posts and pages ├── _config.yml # Jekyll options @@ -216,42 +217,23 @@ Link blog like a champ by adding `link: http://url-you-want-linked` to a post's --- -## Further Customization +## Theme Development -To make things easier I use LESS to build the theme's stylesheet. If you want to easily skin the colors and fonts, take a look at `variables.less` in `assets/less/`. Just compile `main.less` using your preprocessor of choice and off you go -- I like [CodeKit](http://incident57.com/codekit/) for OS X and [Prepros](http://alphapixels.com/prepros/) for Windows. [Grunt](http://gruntjs.com) and an assortment [Jekyll plugins](http://jekyllrb.com/docs/plugins/) are also an option for converting LESS files into CSS. +If you want to easily skin the themes' colors and fonts, take a look at `variables.less` in `assets/less/` and make the necessary changes to the color and font variables. To make development easier I setup a Grunt build script to compile/minify the LESS files into `main.min.css` and lint/concatenate/minify all scripts into `scripts.min.js`. [Install Node.js](http://nodejs.org/), then [install Grunt](http://gruntjs.com/getting-started), and then install the dependencies for the theme contained in `package.json`: -{% highlight css %} -// Colors -// -------------------------------------------------- -@base-font: 'Lato', Calibri, Arial, sans-serif; -@heading-font: @base-font; -@caption-font: @base-font; -@code-font: monospace; -@alt-font: serif; - -// Colors -// -------------------------------------------------- -@base-color : #222; -@body-color : #e8e8e8; -@text-color : #222; -@comp-color : spin(@base-color, 180); -@border-color : lighten(@base-color,60); -@white : #fff; -@black : #000; -@link-color : #222; - -@primary : @base-color; -@success : #5cb85c; -@warning : #dd8338; -@danger : #C64537; -@info : #308cbc; +{% highlight bash %} +npm install {% endhighlight %} +From the theme's root, use `grunt` to rebuild the CSS, concatenate JavaScript files, and optimize .jpg, .png, and .svg files in the `images/` folder. You can also use `grunt watch` in combination with `jekyll build --watch` to watch for updates to your LESS and JS files that Grunt will then automatically re-build as you write your code which will in turn auto-generate your Jekyll site when developing locally. + +And if the command line isn't your thing (you're using Jekyll so it probably is), [CodeKit](http://incident57.com/codekit/) for OS X and [Prepros](http://alphapixels.com/prepros/) for Windows are great alternatives. + --- ## Questions? -Having a problem getting something to work or want to know why I setup something in a certain way? Ping me on Twitter [@mmistakes](http://twitter.com/mmistakes) or [file a GitHub Issue](https://github.com/mmistakes/hpstr-rdx-theme/issues/new). And if you make something cool with this theme feel free to let me know. +Having a problem getting something to work or want to know why I setup something in a certain way? Ping me on Twitter [@mmistakes](http://twitter.com/mmistakes) or [file a GitHub Issue](https://github.com/mmistakes/hpstr-jekyll-theme/issues/new). And if you make something cool with this theme feel free to let me know. ---