It was not clear (to me, at least) that non-ruby external commands should not contain a file suffix. Homebrew will ignore a file `cmd/brew-extcmd.sh` instead of printing a warning or registering it as `brew extcmd.sh`
Bare URLs are auto-linked on GitHub but not on docs.brew.sh, so I added
angle brackets around them where appropriate. Also converted
Markdown-linked URLs for clarity.
GitHub now nicely generates a documentation site for us at
http://brew.sh/brew based on our docs folder. Optimise the output of
this and the GitHub docs directory for readability and the various user
groupings.