├── .gitignore ├── CHANGELOG.md ├── Gemfile ├── LICENSE.txt ├── README.md ├── Rakefile ├── lib ├── octopress-debugger.rb └── octopress-debugger │ └── version.rb ├── octopress-debugger.gemspec └── test ├── _config.yml ├── _posts ├── 2015-01-12-posts-are-cool.markdown ├── 2015-01-12-testing-posts-again.markdown └── 2015-01-12-testing-posts.markdown ├── _site └── index.html └── index.html /.gitignore: -------------------------------------------------------------------------------- 1 | /.bundle/ 2 | /.yardoc 3 | /Gemfile.lock 4 | /_yardoc/ 5 | /coverage/ 6 | /doc/ 7 | /pkg/ 8 | /spec/reports/ 9 | /tmp/ 10 | *.bundle 11 | *.so 12 | *.o 13 | *.a 14 | mkmf.log 15 | _site 16 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ### 1.0.2 (2015-01-12) 4 | - New convenience methods 5 | - Documentation improvements 6 | 7 | ### 1.0.1 (2015-01-12) 8 | - Added scopes quick var 9 | - Improved docs 10 | 11 | ### 1.0.0 (2015-01-11) 12 | - Initial release 13 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | # Specify your gem's dependencies in octopress-debugger.gemspec 4 | gemspec 5 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2015 Brandon Mathis 2 | 3 | MIT License 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining 6 | a copy of this software and associated documentation files (the 7 | "Software"), to deal in the Software without restriction, including 8 | without limitation the rights to use, copy, modify, merge, publish, 9 | distribute, sublicense, and/or sell copies of the Software, and to 10 | permit persons to whom the Software is furnished to do so, subject to 11 | the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be 14 | included in all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 19 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 20 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 21 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 22 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Octopress Debugger 2 | 3 | A simple liquid tag for debugging Jekyll sites with a fancy debugger console. 4 | 5 | [![Gem Version](http://img.shields.io/gem/v/octopress-debugger.svg)](https://rubygems.org/gems/octopress-debugger) 6 | [![License](http://img.shields.io/:license-mit-blue.svg)](http://octopress.mit-license.org) 7 | 8 | ## Installation 9 | 10 | If you're using bundler add this gem to your site's Gemfile in the `:jekyll_plugins` group: 11 | 12 | group :jekyll_plugins do 13 | gem 'octopress-debugger' 14 | end 15 | 16 | Then install the gem with Bundler 17 | 18 | $ bundle 19 | 20 | To install manually without bundler: 21 | 22 | $ gem install octopress-debugger 23 | 24 | Then add the gem to your Jekyll configuration. 25 | 26 | gems: 27 | - octopress-debugger 28 | 29 | ## Usage 30 | 31 | Add the `{% debug %}` tag to any page to get access to the debugger console when that page is generated. 32 | 33 | This will launch an interactive debugging console where you can do some cool things. 34 | 35 | Some useful debugger commands: 36 | 37 | - `continue` - to go to the next `{% debug %}` tag, or step through a loop. 38 | - `abort` - to exit the debugger. 39 | - `help` - show manual for the debugger and learn other commands. 40 | 41 | I've added some convenience methods for working with the Liquid context. 42 | 43 | - `c` - Liquid's context 44 | - `site` - Jekyll's Site class instance. 45 | - `page` - Current Page class instance. 46 | - `scopes` - Scopes for local variables. 47 | 48 | You can pass strings to the `c` method to inspect variables. 49 | 50 | ```ruby 51 | c 'site' # => current site payload hash 52 | c 'page' # => current page payload hash 53 | ``` 54 | 55 | Dot notation works too: 56 | 57 | ```ruby 58 | c 'site.pages' # => Array of site posts 59 | c 'site.posts.first' # => First post instance in site posts array 60 | c 'page.layout' # => Read data from current page 61 | c 'foo' # => Read locally assigned vars 62 | ``` 63 | 64 | ### Example: 65 | 66 | Debugging is a great way to learn about how Jekyll works. For example, you can step through a for loop like this. 67 | 68 | ``` 69 | {% assign test='awesome' %} 70 | {% for post in site.posts %} 71 | {% debug %} 72 | {% endfor %} 73 | ``` 74 | 75 | In the debugger you can type `scopes` to see a hash representing variables in the for loop. Here's a look at what you might see: 76 | 77 | ``` 78 | [ 79 | { 80 | "post"=>, 81 | "forloop"=>{ 82 | { "name"=>"post-site.posts", "length"=>3, "index"=>1, … } 83 | }, 84 | { 85 | test=>'awesome' 86 | } 87 | ] 88 | ``` 89 | 90 | You can see the value of post and interact with the post instance with `scopes.first['post']` and even see all the available data on 91 | the for loop. 92 | 93 | Then you can type `continue` to step through the loop or go to the next `{% debug %}` tag. 94 | 95 | ## Contributing 96 | 97 | 1. Fork it ( https://github.com/octopress/debugger/fork ) 98 | 2. Create your feature branch (`git checkout -b my-new-feature`) 99 | 3. Commit your changes (`git commit -am 'Add some feature'`) 100 | 4. Push to the branch (`git push origin my-new-feature`) 101 | 5. Create a new Pull Request 102 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | require "bundler/gem_tasks" 2 | 3 | -------------------------------------------------------------------------------- /lib/octopress-debugger.rb: -------------------------------------------------------------------------------- 1 | require "octopress-debugger/version" 2 | require "jekyll" 3 | 4 | if RUBY_VERSION >= "2" 5 | require 'pry-byebug' 6 | else 7 | require 'pry-debugger' 8 | end 9 | 10 | module Octopress 11 | module Debugger 12 | class Tag < Liquid::Tag 13 | def render(context) 14 | @context = context 15 | 16 | # HELP: How does this work? 17 | # 18 | # Try these commands: 19 | # site => Jekyll's Site instance 20 | # page => Current Page instance 21 | # scopes => View local variable scopes 22 | # 23 | # Use `c` to read variables from Liquid's context 24 | # c 'site' => site hash 25 | # c 'page' => page hash 26 | # 27 | # Dot notation works too: 28 | # c 'site.posts.first' 29 | # c 'page.content' 30 | # c 'post.tags' 31 | 32 | binding.pry 33 | 34 | return '' # Debugger halts on this line 35 | end 36 | 37 | def c(var=nil) 38 | var.nil? ? @context : @context[var] 39 | end 40 | 41 | def site 42 | site = @context.registers[:site] 43 | end 44 | 45 | def page 46 | @page ||= site.pages.find{|p| p.url == c('page')['url'] } 47 | end 48 | 49 | def scopes 50 | @context.scopes 51 | end 52 | end 53 | end 54 | end 55 | 56 | Liquid::Template.register_tag('debug', Octopress::Debugger::Tag) 57 | 58 | if defined? Octopress::Docs 59 | Octopress::Docs.add({ 60 | name: "Octopress Debugger", 61 | gem: "octopress-debugger", 62 | version: Octopress::Debugger::VERSION, 63 | description: "Debug Jekyll sites with a fancy console.", 64 | path: File.expand_path(File.join(File.dirname(__FILE__), "../")), 65 | source_url: "https://github.com/octopress/debugger" 66 | }) 67 | end 68 | -------------------------------------------------------------------------------- /lib/octopress-debugger/version.rb: -------------------------------------------------------------------------------- 1 | module Octopress 2 | module Debugger 3 | VERSION = "1.0.2" 4 | end 5 | end 6 | -------------------------------------------------------------------------------- /octopress-debugger.gemspec: -------------------------------------------------------------------------------- 1 | # coding: utf-8 2 | lib = File.expand_path('../lib', __FILE__) 3 | $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) 4 | require 'octopress-debugger/version' 5 | 6 | Gem::Specification.new do |spec| 7 | spec.name = "octopress-debugger" 8 | spec.version = Octopress::Debugger::VERSION 9 | spec.authors = ["Brandon Mathis"] 10 | spec.email = ["brandon@imathis.com"] 11 | spec.summary = %q{A debugger for Jekyll templates} 12 | spec.homepage = "https://github.com/octopress/debugger" 13 | spec.license = "MIT" 14 | 15 | spec.files = `git ls-files`.split("\n").grep(%r{^(bin\/|lib\/|assets\/|changelog|readme|license)}i) 16 | spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } 17 | spec.require_paths = ["lib"] 18 | 19 | spec.add_runtime_dependency "jekyll" 20 | 21 | if RUBY_VERSION >= "2" 22 | spec.add_runtime_dependency "pry-byebug" 23 | else 24 | spec.add_runtime_dependency "pry-debugger" 25 | end 26 | 27 | spec.add_development_dependency "bundler", "~> 1.7" 28 | spec.add_development_dependency "rake", "~> 10.0" 29 | spec.add_development_dependency "octopress" 30 | end 31 | -------------------------------------------------------------------------------- /test/_config.yml: -------------------------------------------------------------------------------- 1 | gems: 2 | - octopress-debugger 3 | -------------------------------------------------------------------------------- /test/_posts/2015-01-12-posts-are-cool.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Posts Are Cool" 3 | date: 2015-01-12T01:54:09-06:00 4 | --- 5 | 6 | So cool. 7 | -------------------------------------------------------------------------------- /test/_posts/2015-01-12-testing-posts-again.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Testing Posts Again" 3 | date: 2015-01-12T01:54:02-06:00 4 | --- 5 | 6 | Yep it's a post 7 | -------------------------------------------------------------------------------- /test/_posts/2015-01-12-testing-posts.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Testing Posts" 3 | date: 2015-01-12T01:53:58-06:00 4 | --- 5 | 6 | Such post. Very words. 7 | -------------------------------------------------------------------------------- /test/_site/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /test/index.html: -------------------------------------------------------------------------------- 1 | --- 2 | info: whatever 3 | --- 4 | {% assign test = 'awesome' %} 5 | 6 | {% for post in site.posts %} 7 | {% debug %} 8 | {% endfor %} 9 | --------------------------------------------------------------------------------