This commit is contained in:
@@ -0,0 +1,160 @@
|
||||
# `jekyll_plugin_logger` [](https://badge.fury.io/rb/jekyll_plugin_logger)
|
||||
|
||||
`jekyll_plugin_logger` is a Jekyll plugin, packaged as a Ruby gem, that provides colored console logs for Jekyll plugins.
|
||||
It is based on the standard Ruby [`Logger`](https://ruby-doc.org/stdlib-3.1.0/libdoc/logger/rdoc/Logger.html) class.
|
||||
|
||||
Log levels are normally set from `_config.yml`:
|
||||
|
||||
* 0: `debug`
|
||||
* 1: `info`
|
||||
* 2: `warn`
|
||||
* 3: `error`
|
||||
* 4: `fatal`
|
||||
* 5: `unknown` (displays as `ANY`)
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
The [`demo/_plugins/`](demo/_plugins/) directory demonstrates two ways of working with `jekyll_plugin_logger`:
|
||||
|
||||
* `liquid_tag.rb`, a Jekyll plugin subclassed from
|
||||
[`Liquid::Tag`](https://jekyllrb.com/docs/plugins/tags/).
|
||||
* `support_tag.rb`, a Jekyll plugin subclassed from
|
||||
[`JekyllSupport::JekyllTag`](https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html).
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
### To A Jekyll Website
|
||||
|
||||
Add the following to your Jekyll website's `Gemfile`:
|
||||
|
||||
```ruby
|
||||
group :jekyll_plugins do
|
||||
gem 'jekyll_plugin_logger'
|
||||
end
|
||||
```
|
||||
|
||||
Install all of the dependent gems of your Jekyll website by typing:
|
||||
|
||||
```shell
|
||||
$ bundle
|
||||
```
|
||||
|
||||
### To A Jekyll Plugin Packaged As A Gem
|
||||
|
||||
Add the following to your Gem’s `.gemspec`:
|
||||
|
||||
```ruby
|
||||
Gem::Specification.new do |spec|
|
||||
spec.add_dependency 'jekyll_plugin_logger'
|
||||
end
|
||||
```
|
||||
|
||||
Install all of the dependent gems of your Gem by typing:
|
||||
|
||||
```shell
|
||||
$ bundle
|
||||
```
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
The default log level is `info`.
|
||||
You can change the log level by editing `_config.yml` and adding a `plugin_loggers` section.
|
||||
Within that section, add an entry for the fully qualified name of your plugin class.
|
||||
|
||||
For example, the fully qualified class names of the Jekyll plugins provided in `demo/_plugins/`
|
||||
are `Raw::InlineTag` and `Support::InlineTag`, respectively.
|
||||
Their log levels can be set to `debug` with the following entries in [`_config.yml`](demo/_config.yml):
|
||||
|
||||
```yaml
|
||||
plugin_loggers:
|
||||
Raw::InlineTag: debug # Notice the module name is specified as well as the class name
|
||||
Support::InlineTag: debug # Notice the module name is specified as well as the class name
|
||||
```
|
||||
|
||||
|
||||
## Run the Demo
|
||||
|
||||
Run the demo by typing:
|
||||
|
||||
```shell
|
||||
$ demo/_bin/debug -r
|
||||
```
|
||||
|
||||
See what happens to the output when you edit the logging levels in the `plugin_loggers` section of `_config.yml`.
|
||||
You will have to restart the demo after each modification to `_config.yml`
|
||||
in order to see the output change.
|
||||
|
||||
|
||||
## Additional Information
|
||||
|
||||
More information is available on Mike Slinn's web site about
|
||||
[Jekyll plugins](https://www.mslinn.com/jekyll/10100-custom-logging-in-jekyll-plugins.html).
|
||||
|
||||
|
||||
## Development
|
||||
|
||||
After checking out the `jekyll_plugin_logger` repository,
|
||||
run `bin/setup` to install dependencies,
|
||||
which includes development dependencies.
|
||||
|
||||
You can then run `bin/console` for an interactive prompt that will allow you to experiment.
|
||||
|
||||
|
||||
### Build and Install Locally
|
||||
|
||||
To build and install this gem onto your local machine, run:
|
||||
|
||||
```shell
|
||||
$ bundle exec rake install
|
||||
jekyll_plugin_logger 1.0.0 built to pkg/jekyll_plugin_logger-0.1.0.gem.
|
||||
jekyll_plugin_logger (1.0.0) installed.
|
||||
```
|
||||
|
||||
Examine the newly built gem:
|
||||
|
||||
```shell
|
||||
$ gem info jekyll_plugin_logger
|
||||
|
||||
*** LOCAL GEMS ***
|
||||
|
||||
jekyll_plugin_logger (1.0.0)
|
||||
Author: Mike Slinn
|
||||
Homepage:
|
||||
https://github.com/mslinn/jekyll_plugin_logger
|
||||
License: MIT
|
||||
Installed at: /home/mslinn/.gems
|
||||
|
||||
Generates a Jekyll logger with colored output.
|
||||
```
|
||||
|
||||
|
||||
### Build and Push to RubyGems
|
||||
|
||||
To release a new version,
|
||||
|
||||
1. Update the version number in `version.rb`.
|
||||
2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
|
||||
3. Run the following:
|
||||
|
||||
```shell
|
||||
$ bundle exec rake release
|
||||
```
|
||||
|
||||
The above creates a git tag for the version, commits the created tag,
|
||||
and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the project
|
||||
2. Create a descriptively named feature branch
|
||||
3. Add your feature
|
||||
4. Submit a pull request
|
||||
|
||||
|
||||
## License
|
||||
|
||||
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
||||
Reference in New Issue
Block a user