diff --git a/docs/doc.md b/docs/doc.md
index d677ae5..64395b1 100644
--- a/docs/doc.md
+++ b/docs/doc.md
@@ -165,6 +165,8 @@ It is common to use an alias for the package name with new-style modules. Here a
 
 It's semi-standard to use 'M' or '_M' for the module alias; LDoc will recognize these automatically.
 
+By default, comments are treated verbatim and traditionally contain HTML. This is irritating for the human reader of the comments and tedious for the writer, so there is an option to use [Markdown](http://daringfireball.net/projects/markdown); `--format markdown`. This requires [markdown.lua](http://www.frykholm.se/files/markdown.lua) by Niklas Frykholm to be installed (this can be most easily done with `luarocks install markdown`.)  `format = 'markdown'` can be used in your `config.ld`.
+
 A special case is if you simply say 'ldoc .'. Then there _must_ be a `config.ld` file available in the directory, and it can specify the file:
 
     file = "mymod.lua"
diff --git a/readme.md b/readme.md
index 6668d06..43ccd01 100644
--- a/readme.md
+++ b/readme.md
@@ -21,7 +21,7 @@ LDoc is intended to be compatible with [LuaDoc](http://luadoc.luaforge.net/manua
 
 Tags such as `see` and `usage` are supported, and generally the names of functions and modules can be inferred from the code.
 
-LDoc is designed to give better diagnostics: if a '@see` reference cannot be found, then the line number of the reference is given.  LDoc knows about modules which do not use `module()` - this is important since this function has become deprecated in Lua 5.2. And you can avoid having to embed HTML in commments by using Markdown.
+LDoc is designed to give better diagnostics: if a `@see` reference cannot be found, then the line number of the reference is given.  LDoc knows about modules which do not use `module()` - this is important since this function has become deprecated in Lua 5.2. And you can avoid having to embed HTML in commments by using Markdown.
 
 LDoc will also work with Lua C extension code, and provides some convenient shortcuts.
 
@@ -29,7 +29,7 @@ An example showing the support for named sections and 'classes' is the [Winapi d
 
 ## Installation
 
-This is straightforward; the only external dependency is [Penlight](https://github.com/stevedonovan/Penlight), which in turn needs [LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present in Lua for Windows, and Penlight is also available through LuaRocks as 'luarocks install penlight'.
+This is straightforward; the only external dependency is [Penlight](https://github.com/stevedonovan/Penlight), which in turn needs [LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present in Lua for Windows, and Penlight is also available through LuaRocks as `luarocks install penlight`.
 
 Unpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either an excutable script called 'ldoc' like so: