Skip to content

Latest commit

 

History

History
128 lines (80 loc) · 4.16 KB

README.md

File metadata and controls

128 lines (80 loc) · 4.16 KB
Raw

jekyll-pre-commit

Build Status Gem Version

A Jekyll plugin to make sure your post is really ready for publishing.

Terminal showing failed check

Installation

Add this line to your Gemfile:

group :jekyll_plugins do
  gem 'jekyll-pre-commit'
end

Then execute the bundle command to install the gem.

Next run bundle exec jekyll pre-commit init in the root of your Jekyll site.

This will symlink this plugin's pre-commit file to the .git/hooks/ directory of your project.

If you provide the --force flag when running bundle exec jekyll pre-commit init any existing pre-commit file will be deleted.

Usage

Once installed you may choose the pre-commit checks you would like to use by listing them in your site's _config.yml.

pre-commit:
  - check: FrontMatterVariableExists
    variables: ['description', 'image']
  - check: FrontMatterVariableIsNotDuplicate
    variables: ['description']
  - check: FrontMatterVariableMeetsLengthRequirements
    variables: ['description', 'title']
  - check: NoDuplicateTags

NOTE: Depending on your configuration, you may need use bundle exec git commit to ensure Ruby libraries are properly loaded to run the pre-commit checks.

Available Checks

FrontMatterVariableExists

This check ensures that any listed variables exist in the front matter of any post that is staged to be committed.

FrontMatterVariableIsNotDuplicate

This check ensures that any listed variables are unique amongst all the posts on your site in the front matter of any post that is staged to be committed.

FrontMatterVariableMeetsLengthRequirements

This check ensures that any listed variables meet the length requirements (in number of characters) in the front matter of any post that is staged to be committed.

This check includes the following defaults:

title

  • max: 59

description

  • min: 145
  • max: 165

These can be overridden, or requirements can be specified for other variables in the following format...

  • variable|min|max

For example...

- check: FrontMatterVariableMeetsLengthRequirements
  variables: ['title||50']

In the above, there would be a maximum length of 50 characters for the title (rather than the default of 59)

NoDuplicateTags

Checks that you have not accidentally introduced a duplicate tag. For example, if you have posts that are already using "MySQL" as a tag and you attempt to commit a post with the tag "mysql" (notice the difference in case-sensitivity) you will not be allowed to commit.

NoTodos

This check ensures that you haven't left and "todos" in your post. It does so by doing a case-insensitive check against the entire post content for the string "todo".

Roll Your Own

You can also add your own checks. To do so, create a class in the Jekyll::PreCommit::Checks module and and define a check method. Your class should extend the Jekyll::PreCommit::Checks::Check class and return the @result instance variable.

For example...

module Jekyll
  module PreCommit
    module Checks
      class DoesNothing < Check
        def check(staged, not_staged, site, args)
          @result
        end
      end
    end
  end
end

Put this file in your plugins_path (which is _plugins by default) and jekyll-pre-commit will load it automatically. Then just specify that you'd like to run this check in your front matter.

pre-commit:
  - check: DoesNothing

As you can probably tell by the name, this check doesn't actually do anything. Review the checks in lib/jekyll-pre-commit/checks for some more useful examples.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mpchadwick/jekyll-pre-commit.

Please ensure tests pass (using rspec) before submitting a pull request and provide test coverage for any new features.

License

The gem is available as open source under the terms of the MIT License.