rzen 297be0928b alternate readme, to be reconsiled with the post

2019-09-06 07:17:53 -04:00

7.5 KiB

Raw Blame History

title	layout	date	tags	permalink	categories
README	page	2019-07-22	readme wip	/readme/	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 or existing).

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

# ...
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.:

cp _config.yaml _config.yaml.backup

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

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:

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:

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:

docker-compose 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 .

ALternatively you may run this command using docker compose:

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.
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.

7.5 KiB Raw Blame History