Metalsmith: How to use run()?

Question

The docs show a method run(files, fn):

Run all of the middleware functions on a dictionary of files and callback with fn(err, files), where files is the altered dictionary.

https://www.npmjs.com/package/metalsmith#runfiles-fn

How / When should it be used? I cannot find any more detailed information or examples.

Thanks for any hints :)