rzen/jekyll-theme-isabelline
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
3de7d3b62e
jekyll-theme-isabelline/_pages/getting-started.md
rzen 98ab475ef5 wip
2020-08-31 21:07:53 -04:00

272 lines
7.9 KiB
Markdown
Raw Blame History

---
title: Getting Started
layout: page
date: 2019-07-22
tags: isabelline install
permalink: /getting-started/
categories: global
sort_order: 1
---
# Jekyll theme: «Isabelline»
Simple clean mobile-friendly theme for long form blogging. Also good for private note taking.
{% include image.html name="undraw_browsing_online_sr8c.svg" caption="Welcome to «Isabelline»!" %}
## Features
- Compatible with Jekyll 4.0
- Mobile friendly & responsive
- Semantic lightweight markup, super fast
- Customizable color scheme
- Reserved, minimalistic, elegant design
- Conventional image or image include
- Content features: Quote, Aside, Image, ...
- Fully personalizable
## Installation
Read
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:
```sh
# ...
gem "jekyll-theme-isabelline", "~> 1.0.0"
group :jekyll_plugins do
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).
Reference in New Issue View Git Blame Copy Permalink