feat: parse markdown and custom directives into one representation

core/src/error.rs

@@ -25,6 +25,37 @@ pub enum Error {
     /// the registry's full id set, which is what tells an operator whether the
     /// name is a typo or a missing cargo feature.
     UnknownFormat { listener: String, format: String, available: Vec<String> },
+
+    /// An include or ASCII-art target cannot be used. `path` is where the
+    /// directive actually pointed, resolved, which is the thing an author needs
+    /// to see when a relative target is wrong.
+    Include { path: PathBuf, reason: IncludeReason },
+}
+
+/// Why a directive's target was refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum IncludeReason {
+    /// Resolved outside the content root, or is not a regular file.
+    Outside,
+    Missing,
+    /// Already being expanded further up the stack.
+    Circular,
+    TooDeep,
+    /// The expansion exceeded its line or byte budget.
+    TooLarge,
+}
+
+impl fmt::Display for IncludeReason {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let text = match self {
+            IncludeReason::Outside => "is outside the content root",
+            IncludeReason::Missing => "does not exist",
+            IncludeReason::Circular => "is already being included",
+            IncludeReason::TooDeep => "includes nest too deeply",
+            IncludeReason::TooLarge => "expands to more than the size limit",
+        };
+        f.write_str(text)
+    }
 }
 
 impl fmt::Display for Error {
@@ -37,6 +68,9 @@ impl fmt::Display for Error {
             Error::DuplicateHost { host, first, second } => {
                 write!(f, "host '{host}' is claimed by both site '{first}' and site '{second}'")
             }
+            Error::Include { path, reason } => {
+                write!(f, "include target {} {reason}", path.display())
+            }
             Error::UnknownFormat { listener, format, available } => write!(
                 f,
                 "listener '{listener}' wants format '{format}', which this build does not \