diff --git a/cranelift/docs/heap.dot b/cranelift/docs/heap.dot
new file mode 100644
index 000000000000..1c46f22b321d
--- /dev/null
+++ b/cranelift/docs/heap.dot
@@ -0,0 +1,8 @@
+digraph {
+        node [
+              shape=record,
+              fontsize=10,
+              fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans"
+        ]
+        "static" [label="mapped\npages|unmapped\npages|offset_guard\npages"]
+}
diff --git a/cranelift/docs/heap.svg b/cranelift/docs/heap.svg
new file mode 100644
index 000000000000..e668f3e8deae
--- /dev/null
+++ b/cranelift/docs/heap.svg
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.42.3 (0)
+ -->
+<!-- Title: %3 Pages: 1 -->
+<svg width="209pt" height="45pt"
+ viewBox="0.00 0.00 209.00 45.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 41)">
+<title>%3</title>
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-41 205,-41 205,4 -4,4"/>
+<!-- static -->
+<g id="node1" class="node">
+<title>static</title>
+<polygon fill="none" stroke="black" points="0,-0.5 0,-36.5 201,-36.5 201,-0.5 0,-0.5"/>
+<text text-anchor="middle" x="28" y="-21.5" font-family="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans" font-size="10.00">mapped</text>
+<text text-anchor="middle" x="28" y="-10.5" font-family="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans" font-size="10.00">pages</text>
+<polyline fill="none" stroke="black" points="56,-0.5 56,-36.5 "/>
+<text text-anchor="middle" x="90" y="-21.5" font-family="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans" font-size="10.00">unmapped</text>
+<text text-anchor="middle" x="90" y="-10.5" font-family="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans" font-size="10.00">pages</text>
+<polyline fill="none" stroke="black" points="124,-0.5 124,-36.5 "/>
+<text text-anchor="middle" x="162.5" y="-21.5" font-family="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans" font-size="10.00">offset_guard</text>
+<text text-anchor="middle" x="162.5" y="-10.5" font-family="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans" font-size="10.00">pages</text>
+</g>
+</g>
+</svg>
diff --git a/cranelift/docs/ir.md b/cranelift/docs/ir.md
index b9882151dc33..d4625621f239 100644
--- a/cranelift/docs/ir.md
+++ b/cranelift/docs/ir.md
@@ -95,11 +95,12 @@ execution can never fall through to the next EBB without an explicit branch.
 
 A `.clif` file consists of a sequence of independent function definitions:
 
-.. productionlist::
-    function_list : { function }
-    function      : "function" function_name signature "{" preamble function_body "}"
-    preamble      : { preamble_decl }
-    function_body : { extended_basic_block }
+```
+function_list : { function }
+function      : "function" function_name signature "{" preamble function_body "}"
+preamble      : { preamble_decl }
+function_body : { extended_basic_block }
+```
 
 ### Static single assignment form
 
@@ -397,14 +398,15 @@ be known when the function call is compiled. The function signature describes
 how to call the function, including parameters, return values, and the calling
 convention:
 
-.. productionlist::
-    signature    : "(" [paramlist] ")" ["->" retlist] [call_conv]
-    paramlist    : param { "," param }
-    retlist      : paramlist
-    param        : type [paramext] [paramspecial]
-    paramext     : "uext" | "sext"
-    paramspecial : "sret" | "link" | "fp" | "csr" | "vmctx" | "sigid" | "stack_limit"
-    callconv     : "fast" | "cold" | "system_v" | "fastcall" | "baldrdash_system_v" | "baldrdash_windows"
+```
+signature    : "(" [paramlist] ")" ["->" retlist] [call_conv]
+paramlist    : param { "," param }
+retlist      : paramlist
+param        : type [paramext] [paramspecial]
+paramext     : "uext" | "sext"
+paramspecial : "sret" | "link" | "fp" | "csr" | "vmctx" | "sigid" | "stack_limit"
+callconv     : "fast" | "cold" | "system_v" | "fastcall" | "baldrdash_system_v" | "baldrdash_windows"
+```
 
 A function's calling convention determines exactly how arguments and return
 values are passed, and how stack frames are managed. Since all of these details
@@ -620,16 +622,7 @@ returns a pointer that is guaranteed to trap. Heap addresses can be smaller than
 the native pointer size, for example unsigned `i32` offsets on a 64-bit
 architecture.
 
-.. digraph:: static
-    :align: center
-    :caption: Heap address space layout
-
-    node [
-        shape=record,
-        fontsize=10,
-        fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans"
-    ]
-    "static" [label="mapped\npages|unmapped\npages|offset_guard\npages"]
+![Heap address space layout](./heap.svg)
 
 A heap appears as three consecutive ranges of address space: