1 files changed, 86 insertions, 0 deletions
diff --git a/subplot.md b/subplot.md
index 9929e8b..129fc8b 100644
--- a/subplot.md
+++ b/subplot.md
@@ -3566,3 +3566,89 @@ This is a test file.
 ~~~{#expected.txt .file}
 This is a test file.
 ~~~
+## Mistakes in markdown
+
+When there are mistakes in the markdown input, Subplot should report
+the location (filename, line, column) where the mistake is, and what
+the mistake is. The scenarios in this section verify that.
+
+### Scenario before the first heading
+
+_Requirement: A scenario must follow a heading._
+
+Justification: the heading can be used as the title for the scenario.
+
+~~~scenario
+given an installed subplot
+given file scenario-before-heading.subplot
+given file scenario-before-heading.md
+when I try to run subplot docgen scenario-before-heading.subplot -o /dev/null
+then command fails
+then stderr contains "ERROR: scenario-before-heading.md:1:1: first scenario is before first heading"
+~~~
+
+~~~{#scenario-before-heading.subplot .file .yaml}
+title: Foo
+markdowns:
+  - scenario-before-heading.md
+~~~
+
+~~~~~~{#scenario-before-heading.md .file .markdown}
+~~~scenario
+~~~
+~~~~~~
+
+### Attempt to use definition list
+
+_Requirement: Attempt to use definition lists is reported._
+
+Justification: the markdown parser we use in Subplot doesn't support
+them, and it would be unhelpful to not tell the user if they try to
+use them.
+
+~~~scenario
+given an installed subplot
+given file dl.subplot
+given file dl.md
+when I try to run subplot docgen dl.subplot -o /dev/null
+then command fails
+then stderr contains "ERROR: dl.md:3:1: attempt to use definition lists in Markdown"
+~~~
+
+~~~{#dl.subplot .file .yaml}
+title: Foo
+markdowns:
+  - dl.md
+~~~
+
+~~~~~~{#dl.md .file .markdown}
+# Foo
+
+Some term
+: Definition of term.
+~~~~~~
+
+### Bad "add-newline" value
+
+_Requirement: Only specific values for the "add-newline" attribute are
+allowed for an embedded file._
+
+~~~scenario
+given an installed subplot
+given file add-newline.subplot
+given file add-newline.md
+when I try to run subplot docgen add-newline.subplot -o /dev/null
+then command fails
+then stderr contains "ERROR: add-newline.md:1:1: value of add-newline attribute is not understood: xyzzy"
+~~~
+
+~~~{#add-newline.subplot .file .yaml}
+title: Foo
+markdowns:
+  - add-newline.md
+~~~
+
+~~~~~~{#add-newline.md .file .markdown}
+~~~{#foo.txt .file add-newline=xyzzy}
+~~~
+~~~~~~