161 lines
4.0 KiB
Markdown
161 lines
4.0 KiB
Markdown
# `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).
|