diff --git a/_blog/read-me.md b/_blog/read-me.md new file mode 100644 index 0000000..3584991 --- /dev/null +++ b/_blog/read-me.md @@ -0,0 +1,209 @@ +--- +title: Read me +layout: post +date: 2019-07-22 +tags: readme wip +categories: global +--- + +# 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](#how-to-create-new-jekyll-website) 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. 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). + +6. Run bundle install. + +## Docker cookbook + +### How to create a new jekyll website + +```sh + $ 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](/broken-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: + +```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 [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). \ No newline at end of file