diff --git a/Shake.hs b/Shake.hs
index e7662b75e..0c7559ca8 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -146,6 +146,7 @@ main = do
         ,"site/csv-import.md"
         ,"site/account-aliases.md"
         ,"site/account-separator.md"
+        ,"site/investments.md"
         ]
 
       -- cookbook pages combined, ready for web output by hakyll
diff --git a/site/docs.md b/site/docs.md
index 0b6395bd2..4c01fca0e 100644
--- a/site/docs.md
+++ b/site/docs.md
@@ -97,6 +97,7 @@ Practical user recipes, including:
 [Convert CSV files](csv-import.html)\
 [Rewrite account names](account-aliases.html)\
 [Use another account separator character](account-separator.html)\
+[Track investments](investments.html)\
 
 </div>
 
diff --git a/site/investments.md b/site/investments.md
new file mode 100644
index 000000000..b56ab5108
--- /dev/null
+++ b/site/investments.md
@@ -0,0 +1,64 @@
+# Track investments
+
+A simple example using [prices](/journal.html#prices):
+
+```journal
+2017/1/1 opening balances
+  (assets:depot)  $3000
+
+2017/1/2 buy shares at $200
+  ; let's assume no fees
+  assets:shares   10 TSLA @ $200  ; transaction/purchase price
+  assets:depot
+
+; market price, has jumped since yesterday's purchase!
+P 2017/1/3 TSLA $250
+```
+
+Some reports.
+We start with $3000.
+After the 1/2 purchase, we have $1000 remaining and 10 TSLA shares:
+```shell
+$ hledger -f t.j bal assets --flat -HD
+Ending balances (historical) in 2017/01/01-2017/01/02:
+
+               ||  2017/01/01     2017/01/02 
+===============++============================
+ assets:depot  ||       $3000          $1000 
+ assets:shares ||           0        10 TSLA 
+---------------++----------------------------
+               ||       $3000 $1000, 10 TSLA 
+```
+
+Show the shares's value at cost, with [`-B/--cost`](/hledger.html#reporting-options):
+```shell
+$ hledger -f t.j bal assets --flat -HD -B
+Ending balances (historical) in 2017/01/01-2017/01/02:
+
+               ||  2017/01/01  2017/01/02 
+===============++=========================
+ assets:depot  ||       $3000       $1000 
+ assets:shares ||           0       $2000 
+---------------++-------------------------
+               ||       $3000       $3000 
+```
+
+Show the shares's value using the latest applicable market price, 
+with [`-V/--value`](/hledger.html#market-value).
+A $500 capital gain is apparent in the totals:
+```shell
+$ hledger -f t.j bal assets --flat -HD -V
+Ending balances (historical) in 2017/01/01-2017/01/02:
+
+               ||  2017/01/01  2017/01/02 
+===============++=========================
+ assets:depot  ||       $3000       $1000 
+ assets:shares ||           0       $2500 
+---------------++-------------------------
+               ||       $3000       $3500 
+```
+
+This is about the limit of hledger's 
+[value-reporting](https://github.com/simonmichael/hledger/issues/131) 
+[abilities](https://github.com/simonmichael/hledger/issues/329), 
+currently.