diff --git a/readme.md b/readme.md
index e8596d9..f89a799 100644
--- a/readme.md
+++ b/readme.md
@@ -211,10 +211,19 @@ type HtmlOptions = Record<string, Handle>
 
 ## Authoring
 
+When authoring markdown with directives, keep in mind that they don’t work in
+most places.
+On your own site it can be great!
+
 ## HTML
 
+You can define how directives are turned into HTML.
+If directives are not handled, they do not emit anything.
+
 ## CSS
 
+How to display directives is left as an exercise for the reader.
+
 ## Syntax
 
 The syntax looks like this: