1 files changed, 47 insertions, 3 deletions
diff --git a/docs/README.md b/docs/README.md
index 0ebcd23a..dfc7f934 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,4 @@
-# chisel3/docs/README.md
+# Chisel 3 Documentation
 
 This directory contains documentation on the code within this repository.
 Documents can either be written directly in markdown, or
@@ -26,8 +26,52 @@ Our documentation strategy for this repository is as follows:
  * Old documentation is contained in the `src/wiki-deprecated` directory and is being incrementally converted to these
  categories.
 
-To build the documentation, run `docs/mdoc` from SBT in the root directory. The generated documents
+This documentation is hosted on the Chisel [website](https://www.chisel-lang.org).
+
+## mdoc
+
+### Basic Use
+
+To build the documentation, run `docs/mdoc` via SBT in the root directory. The generated documents
 will appear in the `docs/generated` folder. To iterate on the documentation, you can run `docs/mdoc --watch`. For
 more `mdoc` instructions you can visit their [website](https://scalameta.org/mdoc/).
 
-This documentation is hosted on the Chisel [website](https://www.chisel-lang.org).
+### Custom `verilog` modifier
+
+mdoc supports [custom modifiers](https://scalameta.org/mdoc/docs/modifiers.html#postmodifier).
+We have created a custom `verilog` modifier to enable displaying the Verilog output of Chisel.
+
+Example use:
+````
+```scala mdoc:silent
+class MyModule extends RawModule {
+  val in = IO(Input(UInt(8.W)))
+  val out = IO(Output(UInt(8.W)))
+  out := in + 1.U
+}
+```
+```scala mdoc:verilog
+ChiselStage.emitVerilog(new MyModule)
+```
+````
+The `verilog` modifier tells mdoc to run the Scala block, requiring that each Statement returns a String.
+It will then concatenate the resulting Strings and wrap them in triple backticks with the language set to `verilog`:
+````
+```scala
+class MyModule extends RawModule {
+  val in = IO(Input(UInt(8.W)))
+  val out = IO(Output(UInt(8.W)))
+  out := in + 1.U
+}
+```
+```verilog
+module MyModule(
+  input  [7:0] in,
+  output [7:0] out
+);
+  assign out = in + 8'h1; // @[main.scala 9:13]
+endmodule
+```
+````
+
+Note that `imports` are okay in `mdoc:verilog` blocks, but any utility Scala code should be in a separate block.