add readme as a sample blog post; easier to wip this way
This commit is contained in:
rzen
209
_blog/read-me.md
Normal file
209
_blog/read-me.md
Normal file
@@ -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
|
||||
|
||||
### <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 .
|
||||
```
|
||||
|
||||
### 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
Block a user