You’re right, the “Install It” section should make that clearer. Anyway, there is an explanation of basic usage if you follow the link to “CLI” (https://github.com/segmentio/metalsmith#cli) in that section. It says you can create a `metalsmith.json` file that lists source, destination, and plugins in the described format, and then run `metalsmith` from the command line to build your pages according to the configuration file. And I think you will probably also have to install any plugins you use beforehand. Plugin installation instructions are all in the plugin READMEs – they are basically all just `npm install <some-package-name>`.
But it’s harder to figure out how to create my own local plugins and make sure Metalsmith is able to see them. And the documentation should make it clearer how to use the JavaScript API, in the context of a static file generator, where most people are not thinking about writing a program. It took me a bit of thinking to realize that you would have to create a `whatever.js` file inside the directory containing JavaScript code with `Metalsmith(".")….build()`, and then just run it with `node whatever.js`.
Sorry about that! Just updated the Readme and website to hopefully make that clearer. And I've added Readme's to all of the examples[1] now too, some of which use the Javascript API and some the CLI.
