htmllinter

html linter based on posthtml. shareable and plug-able linter made on top of posthtml

Table of Contents

• Installation
  • About the packages
• Usage
• CLI
  • Usage
• Node API
• Config File
  • 1. extend
  • 2. plugins
  • 2. rules
• Rules
• Creating your own rules or plugins
• Creating your own shareable config
• Contributing
• Note
• Inspiration/Thanks

Before we begin, in the docs whenever you read about custom rules and plugins, its basically same but sometimes, a plugin can have more have one rule definition. so we can say sometimes plugins is a rule or can say a plugin has group of rules. it doesnt matter once it goes through htmllinter as there, everything is a function to run !

Installation

npm install @htmllinter/core @htmllinter/basic-config --save-dev

About the packages

• @htmllinter/core is the linter which comes with its own CLI to run with. It supports pretty error display in table format. It has node API which can be use to linter node programs.

• @htmllinter/basic-config: it is the shareable config package which uses @htmllinter/basic-rules package to load rules and share it. Read more about it HERE

• @htmllinter/basic-rules : it is the rules package contains some basic rules. You dont need to install it explicitly as it comes with @htmllinter/basic-config

Usage

htmllinter can be configured through a config file name htmllinter.config.js . Create this file in your project and follow this guide to configure this file.

Add @htmllinter/basic-config in your htmllinter.config.js in extend property

htmllinter.config.js

module.exports : {
  extend : require('@htmllinter/basic-config')
}

And now you are ready to lint your html files using the following commands

htmllinter input.html

in this command, if your htmllinter.config.js file is present at the directory from where this command is being run, then it will load that config file and run the linter and check the input.html file. If you dont have any htmllinter.config.js file preset at the root, it will load the linter with default config which is {}, an empty object.

The input accepts a glob pattern, so it can be patterns like **/*.html, *.html etc. You can find more about these patterns here

You can use the --config or -c flag in order to specify the path to your htmllinter.config.js file. like this

htmllinter input.html -c ./path/to/config/folder

Note that the path passed the -c or --config must be to a directory instead of pointing to the config file.

Also, it should be relative from the directory where htmllinter is being run

Check the CLI Guide to know more about how to use the CLI and the option it takes

CLI

The CLI is one of the to run the htmllinter. It comes by default with htmllitner package so you dont need to install it seperately.

Usage

Usage :

htmllinter <input> [Options]

input           - it is the input(html) file name, it accepts glob pattern.
                example :
                  - "input.html"
                  - "input"
                  - "/*.html"
                  - "."

Options
  -c, --config    - path to htmllinter.config.js.
                    default is "."
                    example :
                    - '.'
                    - './dir/'

Example

    htmllinter input.html
    htmllinter input -c ../
    htmllinter **/*

Node API

REFER THIS

Config File

htmllinter can be configured through config file name htmllinter.config.js.

Note, the file name has to be htmllinter.config.js

There are three properties this config file exports

1. extend

Type : Object (modules) Default : none

This option extends the config which is passed here. A shareable config package is like an usual htmllinter.config.js. They exports properties like plugins , rules and they can even extend other config in extend property

htmllinter.config.js

module.exports = {
  extend: require('@htmllinter/basic-config'),
};

Learn more about creating your own shareable config rule packages here

2. plugins

Type : Array<Objects> Default : []

This accepts the array of plugins packages. This plugins are just packages exporting the rule defination and rule name. This rules are not turned on by default, you need to turn them on in the rules property of the config file.

EXAMPLE

htmllinter.config.js

module.exports = {
  plugins: [require('no-bool-true-explicit-define')],
};

And then you need to manually turn the rule on that is coming from the plugin ,(no-bool-true-explicit-define for this example)

module.exports = {
  plugins: [require('no-bool-true-explicit-define')],
  rules: {
    'no-bool-true-explicit-define': 'on',
  },
};

Learn more about creating a plugins here

learn more about rules here

2. rules

Type : Objects Default : {}

This is the list of the rules and there actionable value like whether they are turned on or off

module.exports = {
  plugins: [require('no-bool-true-explicit-define')],
  rules: {
    'no-bool-true-explicit-define': 'on',
    'no-empty-tag': 'off',
  },
};

CLICK HERE to know more about sharing data from config to rule's options

Rules

@htmllinter/core doesnt comes with any rules, it is recommended to use @htmllinter/basic-standard along with it in order to get the rules.

List of rules comes with @htmllinter/basic-rules

• no-empty-tag : Read [here] for more info about this
• no-duplicate-id : Read [here] for more info about this
• no-bool-true-explicit-define : Read [here] for more info about this

Creating your own rules or plugins

plugins/rules are nothing but a module which is exporting two things

• ruleName : string, as name suggests, it is the name of the rule

• rule : function, it is a function which takes three parameters (options, reporter, repoterNode) and returns a function which gets two parameters (tree,result)

CLICK HERE to read in details how to create a rule

Creating your own shareable config

A shareable config is nothing by a module exporting a htmllinter config properties which consist of plugins, rules and extend (which in turn exports a config)

CLICK HERE to read in details how to create a shareable config

Contributing

Feel free to submit PR with new features, bug fixes, docs update and other changes you think needs to be done. Also, submit an issue if you think needs to be corrected or implemented or needs a discussion

Note

This is still an early stage linter with not so advance rules. Please contribute so that we can get it stable and ready for v1.

Inspiration/Thanks

• A huge inspiration of this is stylelint.
• posthtml : as it is made on top of posthtml and it use the behavior of posthtml's plugins