layout-linter
v0.0.4
Published
Lint your HTML according to your own HTML rules
Downloads
10
Readme
Layout-Linter 
Create your own custom rules, using CSS selectors, to lint an HTML page and make sure it follows your HTML/CSS conventions (classes, attributes, tags, structure etc.)
Screenshot Of A Linted Page
How To Use
Install The Linter In Your App
go to your app's folder and run npm i layout-linter
Set Up Your Linting Rules
- create a file containing your own custom linting rules as a json
- these linting rules are based on CSS selectors (read more about them here), and can be as simple as the name of a tag (e.g.
div) or very elaborate. - here is a guide on how to set up the contents of your json file:
{
"rules": [{
"selector": /*
a CSS selector indicating the element(s) that will be tested
as to whether they adhere to the rules below,
e.g. ".some-class"
*/
"is": /*
(rule)
a tag name indicating what type the element must be,
e.g. "img"
*/,
"direct": /*
(rule)
an array of CSS selectors indicating direct children the element must contain,
e.g. ["#id-x", ".class-b"]
*/,
"contains": /*
(rule)
an array of CSS selectors indicating children (direct or indirect, it doesn't matter)
the element must contain,
e.g. ["#id-x", ".class-b"]
*/,
"attrs": /*
(rule)
an array indicating attributes the element must have,
e.g. ['attr-a', 'attr-b="xx"']
*/,
"parent": /*
(rule)
a CSS selector indicating a direct parent that the linted element must have
e.g. '.some-parent'
*/,
"parents": /*
(rule)
an array of CSS selectors indicating a set of (direct or indirect) parents that the linted element must have
e.g. ['.some-parent-a', '.some-parent-b']
*/,
"siblings": /*
(rule)
an array of CSS selectors indicating a set of siblings that the linted element must have
e.g. ['.some-sibling-a', '.some-sibling-b']
*/,
"not": {
/*
any of the above rules (is, direct, contains, attrs, parent, parents, siblings), wrapped inside this `not`,
indicating that these must NOT be true this time
*/
}
}, {
"selector": "....",
/* rule */,
/* rule */,
.....
..
}]
}- click here for a real example of such a file
- name the file
.layoutrc(recommended) or whatever you like
Using The Linting Function
- require the linting function anywhere your like by doing
const lintLayout = require('layout-linter'); - use the function as follows:
const lintLayout = require('layout-linter');
let result = lintLayout({
/*
- optional
- [String]
- an absolute (or relative to the curret directory) path to a json file
containing the linting rules
- if omitted, the linter will look for a `.layoutrc` file in your app's
root folder only (it will not look for it in any of its subfolders)
*/
layoutrc: '/some/custom/rules.config',
/*
- optional
- refers to the CSS that will be used to style the linting errors that
will appear in the linted HTML
- [String]
- an absolute (or relative to the curret directory) path to a .css file
- will use the default CSS (provided by layout-linter internally) if omitted
- can alse be set to false, in which case no CSS will be used
*/
css: '/some/custom.css',
/*
- mandatory
- [String]
- an absolute (or relative to the curret directory) path to the .html file you want to lint
- OR a valid HTML string (e.g. "<div>....</div>" or "<html>....</html>" etc..) that you want to lint
*/
source: './source.html',
;
/*
- optional
- [Boolean]
- the `html` key, of the object returned by this function, will always consist of a complete HTML document,
as a string, whether the function is passed an HTML fragment or a complete HTML document
- if the function is passed an HTML fragment and this property is set to true,
the `html` key, of the object returned by this function, will consist of the linted HTML fragment (as a string)
and not of a complete HTML document containing that fragment
- if the function is passed a complete HTML document setting this property to true or false will have no effect
*/
fragment: true
});The function will return an object containing the following keys:
{
html: /* the linted HTML as a string */,
errors: /* the total number of errors found in HTML */,
log: /*
an array of objects, each object consisting of:
- a string, indicating the problematic element
- an array of error messages for that element
e.g. [{
element: '<p class="this"></p>',
errors: ['this element has this error', 'this element has this other error', ...]
}, {
element: '<div class="that"></div>',
errors: ['that element has this error', 'that element has this other error', ...]
}]
*/
}How To Contribute
git clone [email protected]:peopledoc/layout-linter.git
cd ./layout-linter/
make installRead how to write tests for your rules.
How To Try The Demo
In layout-linter/ project directory, run:
make run-demoYou will see an HTML page linted using the following set of rules (based on the Bootstrap framework HTML rules).
:information_source: You can use DEBUG=true to show more information.
DEBUG=true make run-demoHow To Run Tests
In layout-linter/ project directory, run:
make testLicense
This project is licensed under the MIT License.