An HTML linter for Bootstrap projects
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.
Bootlint assumes that your webpage is already valid HTML5. If you need to check HTML5 validity, we recommend tools like vnu.jar, grunt-html, or grunt-html-validation.
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.
To use Bootlint with Grunt, use the official Grunt plugin: grunt-bootlint
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.
Use the CDN provided by the fine folks at BootstrapCDN, or download the code, and insert a <script> tag for Bootlint into your webpage.
Then check the JavaScript console for lint warning messages.
Bootlint is a CommonJS module.
Bootlint represents the lint problems it reports using the LintError and LintWarning classes:
LintWarning- Represents a potential error. It may have false-positives.
- Constructor:
LintWarning(id, message) - Properties:
id- Unique string ID for this type of lint problem. Of the form "W###" (e.g. "W123").message- Human-readable string describing the problem
LintError- Represents an error. Under the assumptions explained in the above "Caveats" section, it should never have any false-positives.
- Constructor:
LintError(id, message) - Properties:
id- Unique string ID for this type of lint problem. Of the form "E###" (e.g. "E123").message- Human-readable string describing the problem
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.
Bootlint exports a bootlint property on the global window object.
In a browser environment, the following public APIs are available:
bootlint.lintCurrentDocument(reporter, disabledIds): Lints the HTML of the current document and calls thereporter()function repeatedly with each lint problem as an argument.reporteris a reporter function (see above for a definition). It will be called repeatedly with each lint problem as an argument.disabledIdsis an array of string linter IDs to disable- Returns nothing (i.e.
undefined)
bootlint.showLintReportForCurrentDocument(disabledIds): Lints the HTML of the current document and reports the linting results to the user.- If there are any lint warnings, one general notification message will be
window.alert()-ed to the user. Each warning will be output individually usingconsole.warn(). disabledIdsis an array of string linter IDs to disable- Returns nothing (i.e.
undefined)
- If there are any lint warnings, one general notification message will be
In a browser environment, after Bootlint has loaded, bootlint.showLintReportForCurrentDocument([]) will be executed once.
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 argumentIn a Node.js environment, Bootlint exposes the following public API:
bootlint.lintHtml(html, reporter, disabledIds): Lints the given HTML for a webpage and returns the linting results.htmlis the HTML to lint, as a stringreporteris a reporter function (see above for a definition). It will be called repeatedly with each lint problem as an argument.disabledIdsis an array of string linter IDs to disable- Returns nothing (i.e.
undefined)
The project's coding style is laid out in the JSHint, ESLint, and JSCS configurations. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Also, please don't edit files in the "dist" subdirectory as they are generated via Grunt. You'll find source code in the "src" subdirectory!
See the GitHub Releases page for detailed changelogs.
- 2014-09-26 - v0.3.0: Several bug fixes and enhancements. Not backward compatible
- 2014-09-23 - v0.2.0: First formal release. Announcement: http://blog.getbootstrap.com/2014/09/23/bootlint/
Copyright (c) 2014 Christopher Rebert. Licensed under the MIT license.