Add docs about .custom builder

README.md

@@ -137,6 +137,65 @@ npm install --save-dev rollup-plugin-babel@3 babel-preset-env babel-plugin-exter
 }
 ```
 
+## Custom plugin builder
+
+`rollup-plugin-babel` exposes a plugin-builder utility that allows users to add custom handling of Babel's configuration for each file that it processes.
+
+`.custom` accepts a callback that will be called with the loader's instance of `babel` so that tooling can ensure that it using exactly the same `@babel/core` instance as the loader itself.
+
+It's main purpose is to allow other tools for configuration of transpilation without forcing people to add extra configuration but still allow for using their own babelrc / babel config files.
+
+### Example
+
+```js
+import babel from 'rollup-plugin-babel';
+
+export default babel.custom(babelCore => {
+	function myPlugin() {
+		return {
+			visitor: {},
+		};
+	}
+
+	return {
+		// Passed the plugin options.
+		options({ opt1, opt2, ...pluginOptions }) {
+			return {
+				// Pull out any custom options that the plugin might have.
+				customOptions: { opt1, opt2 },
+
+				// Pass the options back with the two custom options removed.
+				pluginOptions,
+			};
+		},
+
+		config(cfg /* Passed Babel's 'PartialConfig' object. */, { code, customOptions }) {
+			if (cfg.hasFilesystemConfig()) {
+				// Use the normal config
+				return cfg.options;
+			}
+
+			return {
+				...cfg.options,
+				plugins: [
+					...(cfg.options.plugins || []),
+
+					// Include a custom plugin in the options.
+					myPlugin,
+				],
+			};
+		},
+
+		result(result, { code, customOptions, config, transformOptions }) {
+			return {
+				...result,
+				code: result.code + '\n// Generated by some custom loader',
+			};
+		},
+	};
+});
+```
+
 ## License
 
 MIT