# html-proofer
**Repository Path**: mirrors_debian/html-proofer
## Basic Information
- **Project Name**: html-proofer
- **Description**: Test your rendered HTML files to make sure they're accurate.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-11-30
- **Last Updated**: 2026-10-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# HTMLProofer
If you generate HTML files, _then this tool might be for you_.
## Project scope
HTMLProofer 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.
In scope for this project is any well-known and widely-used test for HTML document quality. A major use for this project is continuous integration -- so we must have reliable results. We usually balance correctness over performance. And, if necessary, we should be able to trace this program's detection of HTML errors back to documented best practices or standards, such as W3 specifications.
**Third-party modules.** We want this product to be useful for continuous integration so we prefer to avoid subjective tests which are prone to false positive results, such as spell checkers, indentation checkers, etc. If you want to work on these items, please see [the section on custom tests](#custom-tests) and consider adding an implementation as a third-party module.
**Advanced configuration.** Most front-end developers can test their HTML using [our command line program](#using-on-the-command-line). Advanced configuration will [require using Ruby](https://github.com/gjtorikian/html-proofer/wiki/Using-HTMLProofer-From-Ruby-and-Travis).
## Installation
Add this line to your application's Gemfile:
gem 'html-proofer'
And then execute:
$ bundle install
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.
## What's tested?
Below is mostly comprehensive list of checks that HTMLProofer can perform.
### Images
`img` elements:
* Whether all your images have alt tags
* Whether your internal image references are not broken
* Whether external images are showing
* Whether your images are HTTP
### Links
`a`, `link` elements:
* Whether your internal links are working
* Whether your internal hash references (`#linkToMe`) are working
* Whether external links are working
* Whether your links are HTTPS
* Whether CORS/SRI is enabled
### Scripts
`script` elements:
* Whether your internal script references are working
* Whether external scripts are loading
* Whether CORS/SRI is enabled
### Favicon
* Whether your favicons are valid.
### OpenGraph
* Whether the images and URLs in the OpenGraph metadata are valid.
### HTML
* Whether your HTML markup is valid. This is done via [Nokogiri](https://nokogiri.org/) to validate well-formed HTML5 markup.
## Usage
You can configure HTMLProofer to run on:
* a file
* a directory
* an array of directories
* an array of links
It can also run through the command-line, Docker, or as Rack middleware.
### Using in a script
1. Require the gem.
2. Generate some HTML.
3. Create a new instance of the `HTMLProofer` on your output folder.
4. `run` that instance.
Here's an example:
```ruby
require 'html-proofer'
require 'html/pipeline'
require 'find'
# make an out dir
Dir.mkdir("out") unless File.exist?("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!
HTMLProofer.check_directory("./out").run
```
### Checking a single file
If you simply want to check a single file, use the `check_file` method:
``` ruby
HTMLProofer.check_file('/path/to/a/file.html').run
```
### Checking directories
If you want to check a directory, use `check_directory`:
``` ruby
HTMLProofer.check_directory('./out').run
```
If you want to check multiple directories, use `check_directories`:
``` ruby
HTMLProofer.check_directories(['./one', './two']).run
```
### Checking an array of links
With `check_links`, you can also pass in an array of links:
``` ruby
HTMLProofer.check_links(['http://github.com', 'http://jekyllrb.com']).run
```
This configures Proofer to just test those links to ensure they are valid. Note that for the command-line, you'll need to pass a special `--as-links` argument:
**Note:** flags are different from the default ones provided above. The underscores are replaced with dashes.
`allow_hash_href` will be `--allow-hash-href`
``` bash
htmlproofer www.google.com,www.github.com --as-links
```
### Using on the command-line
You'll also get a new program called `htmlproofer` with this gem. Terrific!
Pass in options through the command-line as flags, like this:
``` bash
htmlproofer --extension .html.erb ./out
```
Use `htmlproofer --help` to see all command line options, or [take a peek here](https://github.com/gjtorikian/html-proofer/blob/main/bin/htmlproofer).
#### Special cases for the command-line
For options which require an array of input, surround the value with quotes, and don't use
any spaces. For example, to exclude an array of HTTP status code, you might do:
``` bash
htmlproofer --http-status-ignore "999,401,404" ./out
```
For something like `url-ignore`, and other options that require an array of regular expressions,
you can pass in a syntax like this:
``` bash
htmlproofer --url-ignore "/www.github.com/,/foo.com/" ./out
```
Since `url_swap` is a bit special, you'll pass in a pair of `RegEx:String`
values. The escape sequences `\:` should be used to produce literal
`:`s `htmlproofer` will figure out what you mean.
``` bash
htmlproofer --url-swap "wow:cow,mow:doh" --extension .html.erb --url-ignore www.github.com ./out
```
### 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"
options = { :assume_extension => true }
HTMLProofer.check_directory("./_site", options).run
end
```
Don't have or want a `Rakefile`? You can also do something like the following:
```bash
htmlproofer --assume-extension ./_site
```
#### Adjusting for a `baseurl`
If your Jekyll site has a `baseurl` configured, you'll need to adjust the
generated url validation to cope with that. The easiest way is using the
`url_swap` option.
For a `site.baseurl` value of `/BASEURL`, here's what that looks like on the
command line:
```bash
htmlproofer --assume-extension ./_site --url-swap '^/BASEURL/:/'
```
or in your `Rakefile`
```ruby
require 'html-proofer'
task :test do
sh "bundle exec jekyll build"
options = { :assume_extension => true, :url_swap => "^/BASEURL/:/" }
HTMLProofer.check_directory("./_site", options).run
end
```
### Using through Docker
If you have trouble with (or don't want to) install Ruby/Nokogumbo, the command-line tool can be run through Docker. See [klakegg/html-proofer](https://hub.docker.com/r/klakegg/html-proofer) for more information.
### Using as Rack middleware
You can run html-proofer as part of your Rack middleware to validate your HTML at runtime. For example, in Rails, add these lines to `config/application.rb`:
```ruby
config.middleware.use HTMLProofer::Middleware if Rails.env.test?
config.middleware.use HTMLProofer::Middleware if Rails.env.development?
```
This will raise an error at runtime if your HTML is invalid. You can choose to skip validation of a page by adding `?proofer-ignore` to the URL.
This is particularly helpful for projects which have extensive CI, since any invalid HTML will fail your build.
## Ignoring content
Add the `data-proofer-ignore` attribute to any tag to ignore it from every check.
``` html
Not checked.
```
This can also apply to parent elements, all the way up to the `` tag:
``` html
```
## Ignoring new files
Say you've got some new files in a pull request, and your tests are failing because links to those files are not live yet. One thing you can do is run a diff against your base branch and explicitly ignore the new files, like this:
```ruby
directories = %w(content)
merge_base = `git merge-base origin/production HEAD`.chomp
diffable_files = `git diff -z --name-only --diff-filter=AC #{merge_base}`.split("\0")
diffable_files = diffable_files.select do |filename|
next true if directories.include?(File.dirname(filename))
filename.end_with?('.md')
end.map { |f| Regexp.new(File.basename(f, File.extname(f))) }
HTMLProofer.check_directory('./output', { url_ignore: diffable_files }).run
```
## Configuration
The `HTMLProofer` constructor takes an optional hash of additional options:
| Option | Description | Default |
| :----- | :---------- | :------ |
| `allow_missing_href` | If `true`, does not flag `a` tags missing `href` (this is the default for HTML5). | `false` |
| `allow_hash_href` | If `true`, ignores the `href="#"`. | `false` |
| `alt_ignore` | An array of Strings or RegExps containing `img`s whose missing `alt` tags are safe to ignore. | `[]` |
| `assume_extension` | Automatically add extension (e.g. `.html`) to file paths, to allow extensionless URLs (as supported by Jekyll 3 and GitHub Pages) | `false` |
| `check_external_hash` | Checks whether external hashes exist (even if the webpage exists). This slows the checker down. | `false` |
| `check_favicon` | Enables the favicon checker. | `false` |
| `check_opengraph` | Enables the Open Graph checker. | `false` |
| `check_html` | Enables HTML validation errors from Nokogumbo | `false` |
| `check_img_http` | Fails an image if it's marked as `http` | `false` |
| `check_sri` | Check that `` and `