_ Git - blog/blob - README.md

   1 # Poole
   2
   3 *The Strange Case of Dr. Jeykll and Mr. Hyde* tells the story of a lawyer investigating the connection of two persons, Dr. Henry Jekyll and Mr. Edward Hyde. Chief among the novel's supporting cast is a man by the name of Mr. Poole, Dr. Jekyll's loyal butler.
   4
   5 -----
   6
   7 Poole is the butler for [Jekyll](http://jekyllrb.com), the static site generator. It's designed and developed by [@mdo](https://twitter.com/mdo) to provide a clear and concise foundational setup for any Jekyll site. It does so by furnishing a full vanilla Jekyll install with example templates, pages, posts, and styles.
   8
   9 ![Poole](https://f.cloud.github.com/assets/98681/1834359/71ae4048-73db-11e3-9a3c-df38eb170537.png)
  10
  11 See Poole in action with [the demo site](http://demo.getpoole.com).
  12
  13 There are currently two official themes built on Poole:
  14
  15 * [Hyde](http://hyde.getpoole.com)
  16 * [Lanyon](http://lanyon.getpoole.com)
  17
  18 Individual theme feedback and bug reports should be submitted to the theme's individual repository.
  19
  20
  21 ## Contents
  22
  23 - [Usage](#usage)
  24 - [Options](#options)
  25   - [Rems, `font-size`, and scaling](#rems-font-size-and-scaling)
  26 - [Development](#development)
  27 - [Author](#author)
  28 - [License](#license)
  29
  30
  31 ## Usage
  32
  33 ### 1. Install Jekyll
  34
  35 Poole is built for use with Jekyll, so naturally you'll need to install that. On Macs, it's rather straightforward:
  36
  37 ```bash
  38 $ gem install jekyll
  39 ```
  40
  41 **Windows users:** Windows users have a bit more work to do, but luckily [@juthilo](https://github.com/juthilo) has your back with his [Run Jekyll on Windows](https://github.com/juthilo/run-jekyll-on-windows) guide.
  42
  43 You may also need to install Pygments, the Python syntax highlighter for code snippets that plays nicely with Jekyll. Read more about this [in the Jekyll docs](http://jekyllrb.com/docs/templates/#code_snippet_highlighting).
  44
  45 ### 2a. Quick start
  46
  47 To help anyone with any level of familiarity with Jekyll quickly get started, Poole includes everything you need for a basic Jekyll site. To that end, just download Poole and start up Jekyll.
  48
  49 ### 2b. Roll your own Jekyll site
  50
  51 Folks wishing to use Jekyll's templates and styles can do so with a little bit of manual labor. Download Poole and then copy what you need (likely `_layouts/`, `*.html` files, `atom.xml` for RSS, and `public/` for CSS, JS, etc.).
  52
  53 ### 3. Running locally
  54
  55 To see your Jekyll site with Poole applied, start a Jekyll server. In Terminal, from `/Poole` (or whatever your Jekyll site's root directory is named):
  56
  57 ```bash
  58 $ jekyll serve
  59 ```
  60
  61 Open <http://localhost:4000> in your browser, and voilà.
  62
  63 ### 4. Serving it up
  64
  65 If you host your code on GitHub, you can use [GitHub Pages](https://pages.github.com) to host your project. Simply create a `gh-pages` branch in your repository and push it to GitHub. Then head to `http://username.github.io/repo-name`.
  66
  67 No matter your production or hosting setup, be sure to check your `baseurl` setting in the `_config.yml` file. For the above example, you'll want to change it from `/` to `/repo-name`. If you have a `CNAME` or host this at the root level of a domain, like `http://example.com`, there's no need to change anything. Not setting this correctly will mean broken styles on your site.
  68
  69
  70 ## Options
  71
  72 Poole includes some customizable options, typically applied via classes on the `<body>` element.
  73
  74
  75 ### Rems, `font-size`, and scaling
  76
  77 Poole is built almost entirely with `rem`s (instead of pixels). `rem`s are like `em`s, but instead of building on the immediate parent's `font-size`, they build on the root element, `<html>`.
  78
  79 By default, we use the following:
  80
  81 ```css
  82 html {
  83   font-size: 16px;
  84   line-height: 1.5;
  85 }
  86 @media (min-width: 38em) {
  87   html {
  88     font-size: 20px;
  89   }
  90 }
  91
  92 ```
  93
  94 To easily scale your site's typography and components, simply customize the base `font-size`s here.
  95
  96
  97 ## Development
  98
  99 Poole has two branches, but only one is used for active development.
 100
 101 - `master` for development.  **All pull requests should be to submitted against `master`.**
 102 - `gh-pages` for our hosted site, which includes our analytics tracking code. **Please avoid using this branch.**
 103
 104
 105 ## Author
 106
 107 **Mark Otto**
 108 - <https://github.com/mdo>
 109 - <https://twitter.com/mdo>
 110
 111
 112 ## License
 113
 114 Open sourced under the [MIT license](LICENSE.md).
 115
 116 <3