Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mslinn/jekyll_plugin_logger

Colored Jekyll logging for plugins.
https://github.com/mslinn/jekyll_plugin_logger

jekyll jekyll-plugin logging

Last synced: 2 months ago
JSON representation

Colored Jekyll logging for plugins.

Awesome Lists containing this project

README 

        
# `jekyll_plugin_logger` [![Gem Version](https://badge.fury.io/rb/jekyll_plugin_logger.svg)](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).