1 files changed, 43 insertions, 0 deletions
diff --git a/subplot.md b/subplot.md
index 7c72ea8..59e9736 100644
--- a/subplot.md
+++ b/subplot.md
@@ -736,6 +736,49 @@ given precondition foo
 ~~~~
 
 
+### Document titles
+
+The document and code generators require a document title, because
+it's a common user error to not have one, and Subplot should help make
+good documents. The Pandoc filter, however, mustn't require a document
+title, because it's used for things like formatting websites using
+ikiwiki, and ikiwiki has a different way of specifying page titles.
+
+#### Document generator gives an error if input document lacks title
+
+~~~scenario
+given file notitle.md
+when I try to run sp-docgen notitle.md -o foo.md
+then exit code is non-zero
+~~~
+
+~~~{.file #notitle.md .markdown .numberLines}
+---
+bindings: b.yaml
+functions: f.py
+...
+
+
+# Introduction
+
+This is a very simple Markdown file without a YAML metadata block,
+and thus also no document title.
+
+```scenario
+given precondition foo
+when I do bar
+then bar was done
+~~~
+
+#### Code generator gives an error if input document lacks title
+
+~~~scenario
+given file notitle.md
+when I try to run sp-codegen --run notitle.md -o test.py
+then exit code is non-zero
+~~~
+
+
 Using a Pandoc filter
 -----------------------------------------------------------------------------