jekyll-theme-isabelline/_pages/read-me.md

---
title: README
layout: page
date: 2019-07-22
tags: readme wip
permalink: /readme/
categories: xglobal
---

# jekyll-theme-isabelline

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

## Installation

Start with a jekyll website ([new](#how-to-create-new-jekyll-website) or existing).

Update Gemfile to reference the new theme and plugins it requires:

```ruby
# ...
gem "jekyll-theme-isabelline", "~> 1.0.0"

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.6"
  gem 'jekyll-tidy'
  gem 'jekyll-tagging'
  gem 'jekyll-mentions'
  gem 'jekyll-sitemap'
  gem 'jekyll-feed'
  gem 'jekyll-seo-tag'
end
# ...
```

(Optionally) Backup your `_config.yaml`, e.g.:

```sh
cp _config.yaml _config.yaml.backup
```

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

```sh
curl https://git.rzen.dev/rzen/jekyll-theme-isabelline/raw/branch/master/_config.yaml -o _config.yaml
```

Create the following folders for your future contents: `_blog`, `_drafts`, `_pages`, `_posts`, and `_private`. The latter is for private notes which will only be rendered in [local mode](#local-mode):

```sh
mkdir _blog _drafts _pages _posts _private
```

Also note that `/_private` is included in `.gitignore` (along with `_drafts`).

Copy `docker-compose.yaml`, `.gitignore` and `index.html` file into the root of your website:

```sh
curl https://git.rzen.dev/rzen/jekyll-theme-isabelline/raw/branch/master/docker-compose.yaml -o docker-compose.yaml
curl https://git.rzen.dev/rzen/jekyll-theme-isabelline/raw/branch/master/.gitignore -o .gitignore
curl https://git.rzen.dev/rzen/jekyll-theme-isabelline/raw/branch/master/index.html -o index.html
```

Run bundle install:

```sh
docker-compose run bundle install
```

## Docker cookbook

### <a id="how-to-create-new-jekyll-website"></a>How to create a new jekyll website

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

ALternatively you may run this command using docker compose:

```sh
docker-compose run 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](/broken-link).

<a id="local-mode"></a>`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:

```sh
docker-compose up jekyll-serve
```

To push gem to [rubygems.org](https://rubygems.org):

```sh
 $ 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:

```sh
 $ 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:

```sh
 $ 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:

```sh
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](http://contributor-covenant.org) code of conduct.


## Development

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

```sh
docker-compose up jekyll-serve
```

## License

The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).