From e0dea96d6c1e7d6f19040cafd9ffde432de330d8 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Wed, 22 Jun 2022 10:21:56 -0700
Subject: [PATCH] Improve documentation of horizontal rules and YAML metadata.
Horizontal rules should have blank space after them, or
pandoc may interpret them as beginning a YAML metadata
block or table.
Closes #8140.
---
MANUAL.txt | 19 +++++++++++++------
1 file changed, 13 insertions(+), 6 deletions(-)
diff --git a/MANUAL.txt b/MANUAL.txt
index ea7d4877e..ca10deb1e 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -4212,6 +4212,10 @@ A line containing a row of three or more `*`, `-`, or `_` characters
---------------
+We strongly recommend that horizontal rules be separated from
+surrounding text by blank lines. If a horizontal rule is not
+followed by a blank line, pandoc may try to interpret the
+lines that follow as a YAML metadata block or a table.
## Tables
@@ -4520,16 +4524,19 @@ will also have "Version 4.0" in the header.
A [YAML] metadata block is a valid YAML object, delimited by a line of three
hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots
-(`...`) at the bottom. A YAML metadata block may occur anywhere in the
-document, but if it is not at the beginning, it must be preceded by a blank
-line. (Note that, because of the way pandoc concatenates input files when
-several are provided, you may also keep the metadata in a separate YAML file
-and pass it to pandoc as an argument, along with your Markdown files:
+(`...`) at the bottom. The initial line `---` must not be followed by a blank
+line. A YAML metadata block may occur anywhere in the document, but if
+it is not at the beginning, it must be preceded by a blank line.
+
+Note that, because of the way pandoc concatenates input files
+when several are provided, you may also keep the metadata in a
+separate YAML file and pass it to pandoc as an argument, along
+with your Markdown files:
pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
Just be sure that the YAML file begins with `---` and ends with `---` or
-`...`.) Alternatively, you can use the `--metadata-file` option. Using
+`...`. Alternatively, you can use the `--metadata-file` option. Using
that approach however, you cannot reference content (like footnotes)
from the main markdown input document.