search

twbs / bootlint

HTML linter for Bootstrap projects
MIT License
2.4k stars 313 forks source link
bookmarklet bootlint bootstrap html linter

readme

Bootlint

NPM version Build Status Coverage Status Development Status :: 5 - Production/Stable MIT License Dependency Status devDependency Status

An HTML linter for Bootstrap projects

What's Bootlint?

Bootlint is a tool that checks for several common HTML mistakes in webpages that are using Bootstrap in a fairly "vanilla" way. Vanilla Bootstrap's components/widgets require their parts of the DOM to conform to certain structures. Bootlint checks that instances of Bootstrap components have correctly-structured HTML. Optimal usage of Bootstrap also requires that your pages include certain <meta> tags, an HTML5 doctype declaration, etc.; Bootlint checks that these are present.

Caveats

Bootlint assumes that your webpage is already valid HTML5. If you need to check HTML5 validity, we recommend tools like vnu.jar or grunt-html.

Bootlint assumes that you are using Bootstrap's default class names in your webpage, as opposed to taking advantage of the "mixins" functionality of Less or Sass to map them to custom class names. If you are using mixins, Bootlint may report some false-positive warnings. However, there are some Bootlint checks that are applicable even if you are using mixins pervasively.

Getting Started

Via Grunt

To use Bootlint with Grunt, use the official Grunt plugin: grunt-bootlint.

Via Gulp

If you want to use Bootlint with Gulp, there is an unofficial Gulp plugin: gulp-bootlint

On the command line

Install the module with: npm install -g bootlint

Run it on some HTML files:

bootlint /path/to/some/webpage.html another_webpage.html [...]

This will output the lint warnings applicable to each file.

The CLI also accepts a --disable (or -d) option to disable certain lint checks. --disable takes a comma-separated list of lint problem IDs. Here's an example:

bootlint -d W002,E020 /path/to/some/webpage.html another_webpage.html [...]

The CLI will also process stdin input which means that you can pipe into Bootlint:

cat mypage.html | bootlint

Or you could use a heredoc (mostly useful for quick testing):

bootlint << EOF
<button class="btn btn-default">Is this correct Bootstrap markup, Bootlint?</button>
EOF

In the browser

Bootlint can run directly in the browser! This is accomplished by using a bookmarklet, which appends bootlint to the body of the active page. There are a few nice benefits of running bootlint directly in the browser. They include:

  1. Evaluating page markup after AJAX requests complete.
  2. Evaluating pages that are dynamically created server-side (ex: CMS).
  3. Evaluating pages/sites that do not have a build script.

How to install the bookmarklet

Please follow the instructions below to get up and running:

  1. Create a new bookmark in your browser
  2. Set the name/title equal to something that is easy to remember. Ex: Run Bootlint
  3. Set the URL equal to
javascript:(function(){var s=document.createElement("script");s.onload=function(){bootlint.showLintReportForCurrentDocument([]);};s.src="https://stackpath.bootstrapcdn.com/bootlint/latest/bootlint.min.js";document.body.appendChild(s)})();

Note: The snippet above will ensure you are always running the latest version of bootlint. If you want to reference a specific version of bootlint please see the BootstrapCDN. Copy the URL and update s.src="https://github.com/twbs/bootlint/raw/master/PASTE-ME-HERE".

How to use the bookmarklet

  1. Click the bookmark you created above
  2. A popup will appear informing you if issues were detected
  3. If issues exist, please open the developer tools and select the console tab

Alternative Options

Browser ready script

You can manually download the browser-ready version of Bootlint.

Lint problem explanations

For detailed explanations of each lint problem, look up the IDs (for example, E001 or W002) in our wiki.

API Documentation

Bootlint is a CommonJS module.

Bootlint represents the lint problems it reports using the LintError and LintWarning classes:

Bootlint defines the following public utility class:

A reporter is a function that accepts exactly 1 argument of type LintWarning or LintError. Its return value is ignored. It should somehow record the problem or display it to the user.

Browser

Bootlint exports a bootlint property on the global window object. In a browser environment, the following public APIs are available:

Node.js

Example:

var bootlint = require('bootlint');

function reporter(lint) {
    console.log(lint.id, lint.message);
}

bootlint.lintHtml("<!DOCTYPE html><html>...", reporter, []); // calls reporter() repeatedly with each lint problem as an argument

In a Node.js environment, Bootlint exposes the following public API:

HTTP API

Bootlint can also be run as an HTTP server that exposes a very simple API. See https://github.com/twbs/bootlint-server.

Contributing

The project's coding style is laid out in the ESLint configuration. Add unit tests for any new or changed functionality. Lint and test your code using the npm scripts.

Also, please don't edit files in the "dist" subdirectory as they are generated via npm run dist. You'll find the source code in the "src" subdirectory!

Release History

See the GitHub Releases page for detailed changelogs.

License

Copyright (c) 2014-2019 The Bootlint Authors. Licensed under the MIT License.