jekyll-theme-isabelline/_blog

title	layout	date	tags
README	post	2019-07-22	readme global wip

jekyll-theme-isabelline

Simple clean mobile-friendly theme for long form blogging. Also good for private note taking.

Installation

Fundamentally setting up a jekyll website with a theme is a straightforward process.

1. Start with a website (new or existing).

2. Update Gemfile to reference the new theme and plugins it requires

3. (Optionally) Backup previous configs.

4. Copy isabelline's starter _config.yaml and customize it to your liking.

5. Run bundle install.

Docker cookbook

How to create a new jekyll website

 $ docker run --rm -it -v "$PWD:/srv/jekyll" jekyll/jekyll:3.8 jekyll new .

How to backup previous configs

isabelline needs the following files placed in the root directory of your jekyll website:

index.html

This is the entry page for the website. It lists out blogs and posts grouped by year.

_config.yaml

Global configurations for the website.

Gemfile

A Gemfile is a file which is used for describing gem dependencies for Ruby programs. A gem is a collection of Ruby code that is extracted into a “collection” which can be called later.

404.html

A page that is shown when the target for a link isnt available. Here's an example of a 404 link.

private.html

Index file for private notes. These notes will only render in local mode. That is when JEKYLL_ENV is set to local.

docker-compose.yaml

Useful helper for running development tasks.

Using docker-compose.yaml

To run jekyll in local development mode:

 $ docker-compose up jekyll-serve

To push gem to rubygems.org:

 $ docker-compose run gem-push
  Successfully built RubyGem
  Name: jekyll-theme-isabelline
  Version: 0.1.8
  File: jekyll-theme-isabelline-0.1.8.gem
Enter your RubyGems.org credentials.
Don't have an account yet? Create one at https://rubygems.org/sign_up
   Email:   your_rubygem_account@example.com
Password:   your_password

Signed in.
Pushing gem to https://rubygems.org...
Successfully registered gem: jekyll-theme-isabelline (0.1.8)

Maks sure to update version in jekyll-theme-isabelline.gemspec. Also, the script will prompt you to authenticate.

Additional helpers, to run jekyll directly, for example to create a new website:

 $ docker-compose run jekyll help
Fetching gem metadata from https://rubygems.org/.............
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...
[ .. skipping superfluous output for brevity .. ]
Using jekyll-theme-isabelline 0.1.8 (was 0.1.7) from source at `.`
Fetching jekyll-tidy 0.2.2
Installing jekyll-tidy 0.2.2
Bundle complete! 8 Gemfile dependencies, 43 gems now installed.
Bundled gems are installed into `/usr/local/bundle`
ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux-musl]
jekyll 3.8.6 -- Jekyll is a blog-aware, static site generator in Ruby

Usage:

  jekyll <subcommand> [options]

Options:
        -s, --source [DIR]  Source directory (defaults to ./)
        -d, --destination [DIR]  Destination directory (defaults to ./_site)
            --safe         Safe mode (defaults to false)
        -p, --plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]]  Plugins directory (defaults to ./_plugins)
            --layouts DIR  Layouts directory (defaults to ./_layouts)
            --profile      Generate a Liquid rendering profile
        -h, --help         Show this message
        -v, --version      Print the name and version
        -t, --trace        Show the full backtrace when an error occurs

Subcommands:
  docs
  import
  build, b              Build your site
  clean                 Clean the site (removes site output and metadata file) without building.
  doctor, hyde          Search site and print specific deprecation warnings
  help                  Show the help message, optionally for a given subcommand.
  new                   Creates a new Jekyll site scaffold in PATH
  new-theme             Creates a new Jekyll theme scaffold
  serve, server, s      Serve your site locally

To run gem:

 $ docker-compose run gem environment
RubyGems Environment:
  - RUBYGEMS VERSION: 3.0.4
  - RUBY VERSION: 2.6.3 (2019-04-16 patchlevel 62) [x86_64-linux-musl]
  - INSTALLATION DIRECTORY: /usr/gem
  - USER INSTALLATION DIRECTORY: /root/.gem/ruby/2.6.0
  - RUBY EXECUTABLE: /usr/local/bin/ruby
  - GIT EXECUTABLE: /usr/bin/git
  - EXECUTABLE DIRECTORY: /usr/gem/bin
  - SPEC CACHE DIRECTORY: /root/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /usr/local/etc
  - RUBYGEMS PLATFORMS:
    - ruby
    - x86_64-linux
  - GEM PATHS:
     - /usr/gem
     - /root/.gem/ruby/2.6.0
     - /usr/local/lib/ruby/gems/2.6.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
     - "install" => "--no-document"
     - "update" => "--no-document"
     - "gem" => "--no-ri --no-rdoc"
  - REMOTE SOURCES:
     - https://rubygems.org/
  - SHELL PATH:
     - /usr/jekyll/bin
     - /usr/local/bundle/bin
     - /usr/local/bundle/gems/bin
     - /usr/local/sbin
     - /usr/local/bin
     - /usr/sbin
     - /usr/bin
     - /sbin
     - /bin

And to run bundle:

 $ docker-compose run bundle help
 [ .. skipped budnle help output for brevity .. ]

Of course if docker isn't your thing, conventional development lifecycle is perfectly usable.

Basic customization

Simply follow instructions in _config.yaml.

Tweaking color scheme

isabelline is a pretty color but she likes to play. Copy _config.scss from the source and place it under _sass/_config.scss. Follow instructions in that file on how to adjust colors.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rzen/jekyll-theme-isabelline. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Development

To develop and test simply run from the root of a cloned jekyll-theme-isabelline project:

 $ docker-compose up jekyll-serve

License

The theme is available as open source under the terms of the MIT License.