The Jekyll Butler. A no frills responsive Jekyll blog theme.

  • By Poole
  • Last update: Jan 8, 2023
  • Comments: 15

Poole

The Strange Case of Dr. Jekyll 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.


Poole is the butler for Jekyll, the static site generator. It's designed and developed by @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.

Poole

See Poole in action with the demo site.

There are currently two official themes built on Poole:

Individual theme feedback and bug reports should be submitted to the theme's individual repository.

Contents

Usage

1. Install dependencies

Poole is built on Jekyll and uses its built-in SCSS compiler to generate our CSS. Before getting started, you'll need to install the Jekyll gem and related dependencies:

$ gem install jekyll jekyll-gist jekyll-sitemap jekyll-seo-tag

Windows users: Windows users have a bit more work to do, but luckily @juthilo has your back with his Run Jekyll on Windows guide.

Need syntax highlighting? Poole includes support for Pygments or Rouge, so install your gem of choice to make use of the built-in styling. Read more about this in the Jekyll docs.

2a. Quick start

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.

2b. Roll your own Jekyll site

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 assets/ for CSS, JS, etc.).

3. Running locally

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):

$ jekyll serve

Open http://localhost:4000 in your browser, and voilà.

4. Serving it up

If you host your code on GitHub, you can use GitHub Pages to host your project.

  1. Fork this repo and switch to the gh-pages branch.
  2. If you're using a custom domain name, modify the CNAME file to point to your new domain.
  3. If you're not using a custom domain name, modify the baseurl in _config.yml to point to your GitHub Pages URL. Example: for a repo at github.com/username/poole, use http://username.github.io/poole/. Be sure to include the trailing slash.
  4. Done! Head to your GitHub Pages URL or custom domain.

No matter your production or hosting setup, be sure to verify the baseurl option file and CNAME settings. Not applying this correctly can mean broken styles on your site.

Development

Poole has two branches, but only one is used for active development.

  • master for development. All pull requests should be to submitted against master.
  • gh-pages for our hosted site, which includes our analytics tracking code. Please avoid using this branch.

CSS is handled via Jeykll's built-in Sass compiler. Source Sass files are located in _sass/, included into styles.scss, and compile to styles.css.

Author

Mark Otto

License

Open sourced under the MIT license.

<3

Github

https://github.com/poole/poole

Comments(15)

  • 1

    Insecure CSS and page jumping up/down?

    Hello,

    When I try and load the page over https, I get an insecure content warning that I have to manually allow to see the page render correctly. The errors chrome console gives me are:

    The page at 'https://diego898.github.io/' was loaded over HTTPS, but ran insecure content from 'http://diego898.github.io/public/css/poole.css': this content should also be loaded over HTTPS.
    The page at 'https://diego898.github.io/' was loaded over HTTPS, but ran insecure content from 'http://diego898.github.io/public/css/syntax.css': this content should also be loaded over HTTPS.
    

    Also, when clicking the navigation bar, the page shifts either up or down, and this happens in both chrome and IE

    http://diego898.github.io

    Any recommendations?

  • 2

    How to move index page to site/blog?

    I want to make static index page and move current index page to blog page.

    I've created copy of index.html (blog.html). But template engine can't find any posts on site/blog. There is just empty page with two buttons (newer and older). Link.

  • 3

    Page "jumping" around

    @mdo I finally made a gif of what I mean. When clicking around page titles I see this:

    shifting

    Note that the first three links are ok, but for some reason the last two cause a slight right shift. When I click on the first three again, I shift back to the left.

    This happens to me in both chrome 40 and IE 11. Should I make a separate issue for just this jumping around?

    Note: this was also posted on a closed issue but I wasnt sure if it was seen

  • 4

    `Related Article` links are wrong?

    Hi,

    I have poole demo blog up and running but when I click on any demo related article links, it showed wrong path. I thought the issue is fixed at #41. But it seems not to work for me.

    For example:

    # Example content 01 Jan 2014
    http://0.0.7.222/01/01/example-content/
    
  • 5

    Line numbering for code blocks

    This theme is great, but it should be nice to be able to enable line numbering for code blocks like Octopress (http://octopress.org/docs/plugins/codeblock/)

  • 6

    Media query flickering in Safari

    When checking the responsiveness of Lanyon (in Safari 7.0), I noticed that the page would flicker between two media query states. So rapidly that it would consume about 80% of a single core.

    I have traced the issue back to the following lines in poole's css:

    html {
      font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
      font-size: 16px;
      line-height: 1.5;
    }
    @media (min-width: 38rem) {
      html {
        font-size: 20px;
      }
    }
    

    It is not a stretch to think that Safari is evaluating the minimum width as 608px (16 * 38) AND 760px (16 * 20). Indeed, after a quick check, the issue does occur between those window sizes.

    Clearly this is caused by the fact that REMs are being used, and that the HTML font-size is being changed by the mentioned media query.

    The issue does not appear to occur in Chrome or Firefox.

  • 7

    2a. Quickstart in README requires context or more info.

    The README implies that getting started is easy, but there must be a missing step or some context that is required:

    2a. Quick start

    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.

    Following this instruction results in:

    Configuration file: /Users/itsme/source/jekyll/poole-master/_config.yml
           Deprecation: You appear to have pagination turned on, but you haven't included the `jekyll-paginate` gem. Ensure you have `gems: [jekyll-paginate]` in your configuration file.
                Source: /Users/itsme/source/jekyll/poole-master
           Destination: /Users/itsme/source/jekyll/poole-master/_site
     Incremental build: disabled. Enable with --incremental
          Generating...
      Liquid Exception: Liquid syntax error: Unknown tag 'gist' in /Users/itsme/source/jekyll/poole-master/_posts/2014-01-01-example-content.md/#excerpt
      Liquid Exception: Liquid syntax error: Unknown tag 'gist' in _layouts/post.html
    jekyll 3.0.0 | Error:  Liquid syntax error: Unknown tag 'gist'
    
  • 8

    Add Sass support

    This overhauls everything and adds Sass support to the styles.

    • .scss files are stored in _scss.
    • css/styles.scss compiles into _site/css/styles.css.
    • This replaces the Liquid includes I was previously using for the syntax highlighting.
    • Reduces two CSS calls—one for poole.css and one for the syntax—into a single file.
    • Breaks styles up into individual .scss files.

    This PR represents the bulk of the work going into v2.

  • 9

    Use SCSS with Jekyll 2

    GitHub Pages now uses Jekyll 2.x, which supports SCSS, SASS, and CoffeeScript assets. I think it would be great if the styles could be switched to SCSS. It makes it easier to make code more modular, and configuration would be easier through variables and mixins.

    Additionally, it is fairly easy to concatenate files with SCSS by simplifying including an SCSS file that only imports other files. Lowering the number of requests made is often very helpful for improving performance.

    Note: I would also like to see this with the Hyde and Layon themes. I personally only use Hyde right now, though I'm hoping this was the right repo to mention the issue in, since it's related to the Poole project in general.

  • 10

    in `require': cannot load such file -- yajl/2.0/yajl (LoadError)

    On my machine, I can use Jekyll with my own gh-pages and with jekyll-bootstrap, but Jekyll doesn't like Poole (on Windows, Ruby 2.0.0, Jekyll freshly installed today). What do you make of this error?

    C:\Dev\poole-master>jekyll serve
    Configuration file: C:/Dev/poole-master/_config.yml
       Deprecation: The 'pygments' configuration option has been renamed to 'highlighter'.
    Please update your config file accordingly. The allowed values are 'rouge', 'pygments' or null.
            Source: C:/Dev/poole-master
       Destination: C:/Dev/poole-master/_site
      Generating...
    Liquid Exception: cannot load such file -- yajl/2.0/yajl in _posts/2014-01-01-example-content.md
    C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require': cannot load
    such file -- yajl/2.0/yajl (LoadError)
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/yajl-ruby-1.1.0-x86-mingw32/lib/yajl/yajl.rb:2:in `<top (required)>'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/yajl-ruby-1.1.0-x86-mingw32/lib/yajl.rb:1:in `<top (required)>'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:135:in `require'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:135:in `rescue in require'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:144:in `require'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/pygments.rb-0.6.0/lib/pygments/popen.rb:3:in `<top (required)>'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/pygments.rb-0.6.0/lib/pygments.rb:1:in `<top (required)>'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/2.0.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/tags/highlight.rb:61:in `render_pygments'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/tags/highlight.rb:49:in `render'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/liquid-2.6.1/lib/liquid/block.rb:109:in `block in render_all'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/liquid-2.6.1/lib/liquid/block.rb:96:in `each'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/liquid-2.6.1/lib/liquid/block.rb:96:in `render_all'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/liquid-2.6.1/lib/liquid/block.rb:82:in `render'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/liquid-2.6.1/lib/liquid/template.rb:128:in `render'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/liquid-2.6.1/lib/liquid/template.rb:138:in `render!'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/convertible.rb:96:in `render_liquid'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/convertible.rb:199:in `do_layout'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/post.rb:266:in `render'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/site.rb:261:in `block in render'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/site.rb:260:in `each'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/site.rb:260:in `render'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/site.rb:43:in `process'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/command.rb:53:in `process_site'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/commands/build.rb:50:in `build'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/commands/build.rb:33:in `process'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/lib/jekyll/commands/serve.rb:24:in `block (2 levels) 
        in init_with_program'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/mercenary-0.3.3/lib/mercenary/command.rb:220:in `call'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/mercenary-0.3.3/lib/mercenary/command.rb:220:in `block in execute'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/mercenary-0.3.3/lib/mercenary/command.rb:220:in `each'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/mercenary-0.3.3/lib/mercenary/command.rb:220:in `execute'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/mercenary-0.3.3/lib/mercenary/program.rb:35:in `go'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/mercenary-0.3.3/lib/mercenary.rb:22:in `program'
        from C:/Dev/Ruby200/lib/ruby/gems/2.0.0/gems/jekyll-2.1.0/bin/jekyll:18:in `<top (required)>'
        from C:/Dev/Ruby200/bin/jekyll:23:in `load'
        from C:/Dev/Ruby200/bin/jekyll:23:in `<main>'
    
  • 11

    Preceding slash in asset urls doesn't work with Github Pages

    Just an FYI really - I'm playing around with Github Pages, Jeykll and Poole, and I had to remove the preceding slash in the asset urls to get them working. For example...

    This doesn't work:

    <link rel="stylesheet" href="/public/css/poole.css">
    

    But this does:

    <link rel="stylesheet" href="public/css/poole.css">
    

    It's obviously because of the way GH Pages urls work, i.e. `http://[username].github.io/[repo-name]. Adding a preceding slash makes the browser look for the assets in the root, whereas it should be looking one level down in the repo directory.

  • 12

    Bump addressable from 2.7.0 to 2.8.1

    Bumps addressable from 2.7.0 to 2.8.1.

    Changelog

    Sourced from addressable's changelog.

    Addressable 2.8.1

    • refactor Addressable::URI.normalize_path to address linter offenses (#430)
    • remove redundant colon in Addressable::URI::CharacterClasses::AUTHORITY regex (#438)
    • update gemspec to reflect supported Ruby versions (#466, #464, #463)
    • compatibility w/ public_suffix 5.x (#466, #465, #460)
    • fixes "invalid byte sequence in UTF-8" exception when unencoding URLs containing non UTF-8 characters (#459)
    • Ractor compatibility (#449)
    • use the whole string instead of a single line for template match (#431)
    • force UTF-8 encoding only if needed (#341)

    #460: sporkmonger/addressable#460 #463: sporkmonger/addressable#463 #464: sporkmonger/addressable#464 #465: sporkmonger/addressable#465 #466: sporkmonger/addressable#466

    Addressable 2.8.0

    • fixes ReDoS vulnerability in Addressable::Template#match
    • no longer replaces + with spaces in queries for non-http(s) schemes
    • fixed encoding ipv6 literals
    • the :compacted flag for normalized_query now dedupes parameters
    • fix broken escape_component alias
    • dropping support for Ruby 2.0 and 2.1
    • adding Ruby 3.0 compatibility for development tasks
    • drop support for rack-mount and remove Addressable::Template#generate
    • performance improvements
    • switch CI/CD to GitHub Actions
    Commits
    • 8657465 Update version, gemspec, and CHANGELOG for 2.8.1 (#474)
    • 4fc5bb6 CI: remove Ubuntu 18.04 job (#473)
    • 860fede Force UTF-8 encoding only if needed (#341)
    • 99810af Merge pull request #431 from ojab/ct-_do_not_parse_multiline_strings
    • 7ce0f48 Merge branch 'main' into ct-_do_not_parse_multiline_strings
    • 7ecf751 Merge pull request #449 from okeeblow/freeze_concatenated_strings
    • 41f12dd Merge branch 'main' into freeze_concatenated_strings
    • 068f673 Merge pull request #459 from jarthod/iso-encoding-problem
    • b4c9882 Merge branch 'main' into iso-encoding-problem
    • 08d27e8 Merge pull request #471 from sporkmonger/sporkmonger-enable-codeql
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

  • 13

    Add workflow to publish gem

    https://rubygems.org/gems/poole-for-jekyll-test - example of the publish.

    This PR adds a Github workflow to automatically publish the poole gem on git push --tags.

    This PR requires some prework before being able to succeed:

    1. Create a Rubygems API key with the following scopes
    image
    1. Create a repository secret RUBYGEMS_AUTH_TOKEN with the value of the API key generated in step 1.
  • 14

    Page build failed for the `gh-pages` branch

    As instructed, I forked this repo and switched to the gh-pages branch, then edited the _config.yml file to change the baseurl to https://j-rahman.github.io/ (which includes the trailing slash). I get the following error message from Github.

    Your site is using the relative_permalinks configuration option. This setting is deprecated as has been removed from the latest version of Jekyll. To ensure your site continues to build as expected, remove the option from your site's configuration and update any post or page permalinks to be absolute to the site root, not the parent folder. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#relative-permalinks-configured.

    For information on troubleshooting Jekyll see: https://docs.github.com/articles/troubleshooting-jekyll-builds

    If you have any questions you can submit a request at https://support.github.com/contact?repo_id=355320140&page_build_id=244814184

    An easy fix is to set relative_permalinks = false.

  • 15

    Bump kramdown from 2.1.0 to 2.3.1

    Bumps kramdown from 2.1.0 to 2.3.1.

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.