diff --git a/plugins/osx/README.md b/plugins/osx/README.md
index 3c12b4d1..06d0816c 100644
--- a/plugins/osx/README.md
+++ b/plugins/osx/README.md
@@ -1,13 +1,42 @@
-Provides the following commands:
-
-- `tab` create a new tab (works in both _Terminal_ and _iTerm_).
-- `pfd` print current _Finder_ directory.
-- `pfs` print current _Finder_ selection.
-- `cdf` cd to current _Finder_ directory.
-- `pushdf` pushd to current _Finder_ directory.
-- `ql` quick look at files.
-- `manp` open MAN pages in _Preview.app_.
-- `manb` open MAN pages in _Bwana.app_.
-- `trash` move files and folders to _Trash_.
-- `rm-osx-cruft` delete .DS_Store, \__MACOSX cruft.
+OSX
+===
+Defines [Mac OS X][1] aliases and functions.
+
+Aliases
+-------
+ - `cdf`, `cd` to current _Finder_ directory.
+ - `pushdf`, `pushd` to current _Finder_ directory.
+ - `rm-osx-cruft`, delete .DS\_Store, \_\_MACOSX cruft.
+ - `ql`, quick look at files.
+
+Functions
+---------
+
+### manb
+Open `MAN` pages in [_Bwana.app_][2].
+
+### manp
+Open `MAN` pages in _Preview.app_.
+
+### pfd
+Print current _Finder_ directory.
+
+### pfs
+Print current _Finder_ selection.
+
+### tab
+Create a new tab (works in both _Terminal_ and [_iTerm_][3]).
+
+### trash
+Move files and folders to _Trash_.
+
+Authors
+-------
+*The authors of this plugin should be contacted via the github bug tracker.*
+
+ - [Sorin Ionescu](/sorin-ionescu)
+
+[1]: http://www.apple.com/macosx/
+[2]: http://bruji.com/bwana/
+[3]: http://www.iterm2.com/