add readme as a sample blog post; easier to wip this way
This commit is contained in:
rzen
parent
af5e6e9b5a
commit
f70e53f03f
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).
|
||||||
Loading…
Reference in New Issue
Block a user