Skip to content

Latest commit

 

History

History
51 lines (26 loc) · 2.74 KB

guide.md

File metadata and controls

51 lines (26 loc) · 2.74 KB

Plugins - Guide

A PostHTML plugin is a function that receives and, usually, transforms a HTML AST from the PostHTML parser. HTML AST has the PostHTML Tree format. Read more about PostHTML Tree.

The rules below are mandatory for all PostHTML plugins.

Name with posthtml- prefix

The plugin’s purpose should be clear just by reading its name. If you wrote a transpiler for HTML Custom Elements, posthtml-custom-elements would be a good name. If you wrote a plugin to support BEM, posthtml-bem would be a good name.

The prefix posthtml- shows that the plugin is part of the PostHTML ecosystem.

This rule is not mandatory for plugins that can run as independent tools, without the user necessarily knowing that it is powered by PostHTML, e.g htmlnano.

Do one thing, and do it well

Do not create multitool plugins. Several small, one-purpose plugins bundled into a plugin pack is usually a better solution.

Plugin must be tested

A CI service like Travis is also recommended for testing code in different environments. You should test in (at least) Node.js v0.12 and stable.

Use only the public PostHTML API

PostHTML plugins must not rely on undocumented properties or methods, which may be subject to change in any minor release. The public API is described in API docs.

Document in English

PostHTML plugins must have their README.md written in English. Do not be afraid of your English skills, as the open source community will fix your errors.

Of course, you are welcome to write documentation in other languages; just name them appropriately (e.g. README.ja.md).

Include Examples (Input && Output)

The plugin's README.md must contain example input and output HTML. A clear example is the best way to describe how your plugin works.

The first section of the README.md is a good place to put examples. See posthtml-expressions for an example.

Of course, this guideline does not apply if your plugin does not transform the HTML.

Maintain a CHANGELOG

PostHTML plugins must describe the changes of all their releases in a separate file, such as CHANGELOG.md, History.md, or GitHub Releases. Visit Keep A Changelog for more information about how to write one of these.

Of course, you should be using semver.

Include posthtml-plugin keyword in package.json

PostHTML plugins written for npm must have the posthtml-plugin keyword in their package.json. This special keyword will be useful for feedback about the PostHTML ecosystem.

For packages not published to npm, this is not mandatory, but is recommended if the package format can contain keywords.