Add README

README.md

@@ -41,6 +41,35 @@ The available configs are:
 - `typescript`
   - Useful rules when writing TypeScript.
 
+### Component mapping (Experimental)
+
+_Note: This is experimental and subject to change._
+
+The `react` config includes rules which target specific HTML elements. You may provide a mapping of custom components to an HTML element in your `eslintrc` configuration to increase linter coverage.
+
+For each component, you may specify a `default` and/or `props`. `default` may make sense if there's a 1:1 mapping between a component and an HTML element. However, if the HTML output of a component is dependent on a prop value, you can provide a mapping using the `props` key. To minimize conflicts and complexity, this currently only supports the mapping of a single prop type.
+
+```json
+{
+  "settings": {
+    "github": {
+      "components": {
+        "Box": { "default": "p" },
+        "Link": { "props": {"as": { "undefined": "a", "a": "a", "button": "button"}}},
+      }
+    }
+  }
+}
+```
+
+This config will be interpreted in the following way:
+
+- All `<Box>` elements will be treated as a `p` element type.
+- `<Link>` without a defined `as` prop will be treated as a `a`.
+- `<Link as='a'>` will treated as an `a` element type.
+- `<Link as='button'>` will be treated as a `button` element type.
+- `<Link as='summary'>` will be treated as the original `Link` element type because there is no matching mapping for `as='summary'`.
+
 ### Rules
 
 - [Array Foreach](./docs/rules/array-foreach.md)