html-proofer 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a20862d9eea9bea34c7c588fc12d7c24e8d986bf
-  data.tar.gz: bc596894692c2bfac98f8c01dec07f58abf6e1ea
+  metadata.gz: af929be3f389ca9ac9d1fc449552207eaf5d983a
+  data.tar.gz: 4197105516d8e7e6cf4768ca57d5e45996aef9ee
 SHA512:
-  metadata.gz: 661dd0af5bb80b2bcd233dabce2eddc4fa66b5fc488c0941c86edb6416324731fd56fc1d02fbc1d8e1eca77c2badbe1d6d53d6e3861c4bb10924065e0f6db642
-  data.tar.gz: 86c96ac6f0c6a43a65084a4bdd261685b296c4c181cfe5d2bf6966e1be58a9b3466e9d2a1593e5514a55a9d8b07057eeb763180664943d81389738f8827393a7
+  metadata.gz: 82d3cffe4c8295939d0140a5e0ad297fed56dfbf0031700eb28eeb2bebb9e187f5cfc7587042a23b9534276f7530f63aeddfb7635993426bbbc1476a3ab4c06f
+  data.tar.gz: d8a50d7cb65def4b4f7ca9be03d0ae1ceac83b495cb34f9d7501650a8cac2a1c072a2a25a8b186f1b5459a52559fb39afe8581f16ff388e4cbce4c21e8a91e06

data/.gitignore

@@ -0,0 +1,26 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+Gemfile.lock
+out/
+sample.rb
+run_sample.rb
+src/
+docs/
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+.DS_Store

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+before_install:
+  - export NOKOGIRI_USE_SYSTEM_LIBRARIES=true

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Garen Torikian
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+# HTML::Proofer
+
+If you generate HTML files, _then this tool might be for you_.
+
+`HTML::Proofer` is a set of tests to validate your HTML output. These tests check if your image references are legitimate, if they have alt tags, if your internal links are working, and so on. It's intended to be an all-in-one checker for your output.
+
+[![Build Status](https://travis-ci.org/gjtorikian/html-proofer.png?branch=master)](https://travis-ci.org/gjtorikian/html-proofer) [![Gem Version](https://badge.fury.io/rb/html-proofer.png)](http://badge.fury.io/rb/html-proofer)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'html-proofer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install html-proofer
+
+**NOTE:** When installation speed matters, set `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true` in your environment. This is useful for increasing the speed of your Continuous Integration builds.
+
+## Usage
+
+### Using in a script
+
+Require the gem; generate some HTML; create a new instance of the `HTML::Proofer` on
+your output folder; then `run` it. Here's a simple example:
+
+```ruby
+require 'html/proofer'
+require 'html/pipeline'
+require 'find'
+
+# make an out dir
+Dir.mkdir("out") unless File.exists?("out")
+
+pipeline = HTML::Pipeline.new [
+  HTML::Pipeline::MarkdownFilter,
+  HTML::Pipeline::TableOfContentsFilter
+], :gfm => true
+
+# iterate over files, and generate HTML from Markdown
+Find.find("./docs") do |path|
+  if File.extname(path) == ".md"
+    contents = File.read(path)
+    result = pipeline.call(contents)
+
+    File.open("out/#{path.split("/").pop.sub('.md', '.html')}", 'w') { |file| file.write(result[:output].to_s) }
+  end
+end
+
+# test your out dir!
+HTML::Proofer.new("./out").run
+```
+
+### Using on the command-line
+
+You'll get a new program called `htmlproof` with this gem. Jawesome!
+
+Use it like you'd expect to:
+
+``` bash
+htmlproof run ./out --swap wow:cow,mow:doh --ext .html.erb --ignore www.github.com
+```
+
+Note: since `swap` is a bit special, you'll pass in a pair of `RegEx:String` values.
+`htmlproof` will figure out what you mean.
+
+### Using with Jekyll
+
+Want to use HTML Proofer with your Jekyll site? Awesome. Simply add `gem 'html-proofer'`
+to your `Gemfile` as described above, and add the following to your `Rakefile`,
+using `rake test` to execute:
+
+```ruby
+require 'html/proofer'
+
+task :test do
+  sh "bundle exec jekyll build"
+  HTML::Proofer.new("./_site").run
+end
+```
+
+Don't have or want a `Rakefile`? You _could_ also do something like the following:
+
+```bash
+htmlproof ./_site
+```
+
+## What's Tested?
+
+### Images
+
+`img` elements:
+
+* Whether all your images have alt tags
+* Whether your internal image references are not broken
+* Whether external images are showing
+
+### Links
+
+`a`, `link` elements:
+
+* Whether your internal links are not broken; this includes hash references (`#linkToMe`)
+* Whether external links are working
+
+### Scripts
+
+`script` elements:
+
+* Whether your internal script references are not broken
+* Whether external scripts are loading
+
+## Configuration
+
+The `HTML::Proofer` constructor takes an optional hash of additional options:
+
+| Option | Description | Default |
+| :----- | :---------- | :------ |
+| `disable_external` | If `true`, does not run the external link checker, which can take a lot of time. | `false` |
+| `ext` | The extension of your HTML files including the dot. | `.html`
+| `favicon` | Enables the favicon checker. | `false` |
+| `followlocation` | Follows external redirections. Amends missing trailing slashes to internal directories. | `true` |
+| `as_link_array` | Assumes that you've passed in just an array of links to check. | `false` |
+| `href_ignore` | An array of Strings or RegExps containing `href`s that are safe to ignore. Certain URIs, like `mailto` and `tel`, are always ignored. | `[]` |
+| `alt_ignore` | An array of Strings or RegExps containing `img`s whose missing `alt` tags are safe to ignore. | `[]` |
+| `href_swap` | A hash containing key-value pairs of `RegExp => String`. It transforms links that match `RegExp` into `String` via `gsub`. | `{}` |
+| `verbose` | If `true`, outputs extra information as the checking happens. Useful for debugging. | `false` |
+
+You can also pass in any of Typhoeus' options for the external link check. For example:
+
+``` ruby
+HTML::Proofer.new("out/", {:ext => ".htm", :verbose = > true, :ssl_verifyhost => 2 })
+```
+
+This sets `HTML::Proofer`'s extensions to use _.htm_, and gives Typhoeus a configuration for it to be verbose, and use specific SSL settings. Check [the Typhoeus documentation](https://github.com/typhoeus/typhoeus#other-curl-options) for more information on what options it can receive.
+
+## Ignoring content
+
+Add the `data-proofer-ignore` attribute to any tag to ignore it from the checks.
+
+## Custom tests
+
+Want to write your own test? Sure! Just create two classes--one that inherits from `HTML::Proofer::Checkable`, and another that inherits from `HTML::Proofer::Checks::Check`. `Checkable` defines various helper methods for your test, while `Checks::Check` actually runs across your content. `Checks::Check` should call `self.add_issue` on failures, to add them to the list.
+
+Here's an example custom test that protects against `mailto` links:
+
+``` ruby
+class OctocatLink < ::HTML::Proofer::Checkable
+
+  def mailto?
+    return false if @data_ignore_proofer || @href.nil? || @href.empty?
+    return @href.match /^mailto\:/
+  end
+
+  def octocat?
+    return @href.match /\:octocat@github.com\Z/
+  end
+
+end
+
+class MailToOctocat < ::HTML::Proofer::Checks::Check
+
+  def run
+    @html.css('a').each do |l|
+      link = OctocatLink.new l, "octocat_link", self
+
+      if link.mailto? && link.octocat?
+        return self.add_issue("Don't email the Octocat directly!")
+      end
+    end
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/html-proofer.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "html-proofer"
+  gem.version       = "1.1.6"
+  gem.authors       = ["Garen Torikian"]
+  gem.email         = ["gjtorikian@gmail.com"]
+  gem.description   = %q{Test your rendered HTML files to make sure they're accurate.}
+  gem.summary       = %q{A set of tests to validate your HTML output. These tests check if your image references are legitimate, if they have alt tags, if your internal links are working, and so on. It's intended to be an all-in-one checker for your documentation output.}
+  gem.homepage      = "https://github.com/gjtorikian/html-proofer"
+  gem.license       = "MIT"
+  gem.executables   = ["htmlproof"]
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(spec)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "mercenary",       "~> 0.3.2"
+  gem.add_dependency "nokogiri",        "~> 1.5"
+  gem.add_dependency "colored",         "~> 1.2"
+  gem.add_dependency "typhoeus",        "~> 0.6.7"
+  gem.add_dependency "yell",            "~> 2.0"
+
+  gem.add_development_dependency "html-pipeline", "~> 1.8"
+  gem.add_development_dependency "escape_utils", "~> 1.0" # Ruby 2.1 fix
+  gem.add_development_dependency "rspec", "~> 2.13.0"
+  gem.add_development_dependency "rake"
+end

data/spec/html/proofer/favicon_spec.rb

@@ -0,0 +1,46 @@
+require "spec_helper"
+
+describe "Favicons test" do
+  it "ignores for absent favicon by default" do
+    absent = "#{FIXTURES_DIR}/favicon/favicon_absent.html"
+    output = capture_stderr { HTML::Proofer.new(absent).run }
+    output.should == ""
+  end
+
+  it "fails for absent favicon" do
+    absent = "#{FIXTURES_DIR}/favicon/favicon_absent.html"
+    output = capture_stderr { HTML::Proofer.new(absent, {:favicon => true}).run }
+    output.should match /no favicon specified/
+  end
+
+  it "fails for absent favicon but present apple touch icon" do
+    absent = "#{FIXTURES_DIR}/favicon/favicon_absent_apple.html"
+    output = capture_stderr { HTML::Proofer.new(absent, {:favicon => true}).run }
+    output.should match /no favicon specified/
+  end
+
+  it "fails for broken favicon" do
+    broken = "#{FIXTURES_DIR}/favicon/favicon_broken.html"
+    output = capture_stderr { HTML::Proofer.new(broken, {:favicon => true}).run }
+    output.should match /internally linking to asdadaskdalsdk.png/
+  end
+
+  it "passes for present favicon" do
+    present = "#{FIXTURES_DIR}/favicon/favicon_present.html"
+    output = capture_stderr { HTML::Proofer.new(present, {:favicon => true}).run }
+    output.should == ""
+  end
+
+  it "passes for present favicon with shortcut notation" do
+    present = "#{FIXTURES_DIR}/favicon/favicon_present_shortcut.html"
+    output = capture_stderr { HTML::Proofer.new(present, {:favicon => true}).run }
+    output.should == ""
+  end
+
+  it "passes for broken favicon with data-proofer-ignore" do
+    broken_but_ignored = "#{FIXTURES_DIR}/favicon/favicon_broken_but_ignored.html"
+    output = capture_stderr { HTML::Proofer.new(broken_but_ignored, {:favicon => true}).run }
+    output.should == ""
+  end
+
+end

data/spec/html/proofer/fixtures/favicon/favicon_absent.html

@@ -0,0 +1,4 @@
+<html>
+<body>
+</body>
+</html>

data/spec/html/proofer/fixtures/favicon/favicon_absent_apple.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+  <link rel="apple-touch-icon" href="gpl.png">
+</head>
+<body>
+</body>
+</html>

data/spec/html/proofer/fixtures/favicon/favicon_broken.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+  <link rel="icon" href="asdadaskdalsdk.png">
+</head>
+<body>
+</body>
+</html>

data/spec/html/proofer/fixtures/favicon/favicon_broken_but_ignored.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+  <link rel="icon" href="asdadaskdalsdk.png" data-proofer-ignore>
+</head>
+<body>
+</body>
+</html>

data/spec/html/proofer/fixtures/favicon/favicon_present.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+  <link rel="icon" href="../resources/gpl.png">
+</head>
+<body>
+</body>
+</html>

data/spec/html/proofer/fixtures/favicon/favicon_present_shortcut.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+  <link rel="shortcut icon" href="../resources/gpl.png">
+</head>
+<body>
+</body>
+</html>

data/spec/html/proofer/fixtures/images/existingImageExternal.html

@@ -0,0 +1,9 @@
+<html>
+
+<body>
+
+	<p>Blah blah blah. <img alt="An existing image" src="http://upload.wikimedia.org/wikipedia/en/thumb/2/22/Heckert_GNU_white.svg/256px-Heckert_GNU_white.svg.png" /> </p>
+
+</body>
+
+</html>

data/spec/html/proofer/fixtures/images/ignorableAltViaOptions.html

@@ -0,0 +1,13 @@
+<html>
+
+<body>
+
+
+<img src="gpl.png"/>Relative to self
+
+
+<p>Blah blah blah. <img src="//upload.wikimedia.org/wikipedia/en/thumb/2/22/Heckert_GNU_white.svg/256px-Heckert_GNU_white.svg.png" /> </p>
+
+</body>
+
+</html>

data/spec/html/proofer/fixtures/images/ignorableImages.html

@@ -0,0 +1,10 @@
+<html>
+
+<body>
+
+<p>Blah blah blah. <img alt="A broken image" src="http://www.whatthehell" data-proofer-ignore="true" /> </p>
+
+
+</body>
+
+</html>

data/spec/html/proofer/fixtures/images/ignoreAltButNotLink.html

@@ -0,0 +1,13 @@
+<html>
+
+<body>
+
+
+<img src="gpl.png"/>Image.
+
+
+<p>Blah blah blah. <a href="http://www.kakakakakaakkakakakakakakaakakak.biz.foo.net" /> </p>
+
+</body>
+
+</html>

data/spec/html/proofer/fixtures/images/image_missing_protocol_invalid.html

@@ -0,0 +1,9 @@
+<html>
+
+<body>
+
+<p>Blah blah blah. <img alt="An existing image" src="//upload.wikimedia.org/wikipedia/en/thumb/fooooof.png" /> </p>
+
+</body>
+
+</html>