diff --git a/.aspelldict b/.aspelldict
index 43794ec..7a9fdc0 100644
--- a/.aspelldict
+++ b/.aspelldict
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 184 
+personal_ws-1.1 en 185 
 Babelmark
 BlockTree
 CDATA
@@ -43,6 +43,7 @@ accessor
 accessors
 apos
 argv
+arrayref
 atx
 autolink
 autolinks
diff --git a/lib/Markdown/Perl.pm b/lib/Markdown/Perl.pm
index 1722666..3d277ea 100644
--- a/lib/Markdown/Perl.pm
+++ b/lib/Markdown/Perl.pm
@@ -326,10 +326,15 @@ will replace whatever would have been used for the link content.
 
 =item *
 
-C<yaml_metadata>: this hook will trigger if there is valid (!) YAML metadata in 
-the file and will give you a hashref as an argument. If the hook throws a die(),
-the Markdown parsing will stop as the die() needs to be handled by your code. 
-This allows for conditional parsing based on values in the metadata section.
+C<yaml_metadata>: this hook will trigger if there is B<valid> YAML metadata at
+the beginning of the file. This also requires that the
+L<parse_file_metadata option|Markdown::Perl::Options/parse_file_metadata> is set
+to C<yaml> (which is the default in our default mode). The hook will receive a
+hashref or an arrayref with the content of the YAML document.
+
+To allow conditional parsing based on some metadata, if the hook dies, the
+exception will interrupt the processing and be propagated as-is to the initial
+caller.
 
 =back
 
diff --git a/lib/Markdown/Perl/BlockParser.pm b/lib/Markdown/Perl/BlockParser.pm
index 7374ad5..d9f4aaf 100644
--- a/lib/Markdown/Perl/BlockParser.pm
+++ b/lib/Markdown/Perl/BlockParser.pm
@@ -371,14 +371,14 @@ sub _parse_yaml_metadata {
     my $metadata = eval { YAML::Tiny->read_string($+{YAML}) };
     if ($EVAL_ERROR) {
       pos($this->{md}) = 0;
-      carp 'YAML Metadata (Markdown frontmatter) is invalid.';
-      return 1;
+      carp 'YAML Metadata (Markdown frontmatter) is invalid' if $this->get_warn_for_unused_input();
+      return;
     }
-    if(exists($this->{pmarkdown}{hooks}{yaml_metadata})) {
+    if (exists($this->{pmarkdown}{hooks}{yaml_metadata})) {
       $this->{pmarkdown}{hooks}{yaml_metadata}->($metadata->[0]);
     }
   }
-  return 1;
+  return;
 }
 
 # https://spec.commonmark.org/0.30/#atx-headings
diff --git a/lib/Markdown/Perl/Options.pm b/lib/Markdown/Perl/Options.pm
index bde11c4..223542c 100644
--- a/lib/Markdown/Perl/Options.pm
+++ b/lib/Markdown/Perl/Options.pm
@@ -181,8 +181,8 @@ sub _word_list {
 =head3 B<parse_file_metadata> I<(enum, default: yaml)>
 
 This option controls whether the parser accepts optional metadata at the
-beginning of the file. The module does nothing with the metadata itself but you
-can configure a hook to intercept the YAML.
+beginning of the file. The module currently does nothing with the metadata
+itself but you can configure a hook to receive the YAML content.
 
 The possible values are:
 
diff --git a/t/501-hooks-yaml-metadata.t b/t/500-hooks-yaml_metadata.t
similarity index 58%
rename from t/501-hooks-yaml-metadata.t
rename to t/500-hooks-yaml_metadata.t
index 17c6955..a7564e5 100644
--- a/t/501-hooks-yaml-metadata.t
+++ b/t/500-hooks-yaml_metadata.t
@@ -3,9 +3,7 @@ use warnings;
 use utf8;
 
 use Markdown::Perl 'convert', 'set_hooks';
-use Test::More;
-use Test2::Tools::Warnings;
-use Test2::Tools::Exception;
+use Test2::V0;
 
 my $p = Markdown::Perl->new();
 my $page = <<EOF;
@@ -19,6 +17,16 @@ number: 42
 I repeat: "Mark is down!"
 EOF
 
+my $list_yaml = <<EOF;
+---
+- abc
+- def
+---
+# Mark is down!
+
+I repeat: "Mark is down!"
+EOF
+
 my $invalid_page = <<EOF;
 ---
 name: Mark is down
@@ -30,36 +38,37 @@ name: Mark is down
 I repeat: "Mark is down!"
 EOF
 
-# Test 1: Check if we can get a string value
+# Check that we can read a hash-map for map document.
 {
-  sub hook_is_name_mark {
-    my $x = shift;
-    ok(exists($x->{name}) && $x->{name} eq 'Mark is down', "key 'name' was retrieved and validated as being 'Mark is down'");
+  sub hook_hash {
+    is($_[0], {name => 'Mark is down', draft => 'false', number => 42}, 'read map YAML');
   }
-  $p->set_hooks(yaml_metadata => \&hook_is_name_mark);
+  $p->set_hooks(yaml_metadata => \&hook_hash);
   $p->convert($page);
 }
 
-# Test 2: Validate that hook is not called if yaml is invalid
+# Check if we can get a string value
 {
-  my $hook_called = 0;
-  sub hook_called {
-    $hook_called = 1;
+  sub hook_list {
+    is($_[0], [qw(abc def)], 'read list YAML');
   }
-  $p->set_hooks(yaml_metadata => \&hook_called);
-  ok(!$hook_called, "Hook was not called because metadata was invalid.");
-  $p->convert($invalid_page);
+  $p->set_hooks(yaml_metadata => \&hook_list);
+  $p->convert($list_yaml);
 }
 
-# Test 3: Validate that invalid yaml causes a carp()
+# Validate that hook is not called if yaml is invalid and that this causes a
+# call to carp().
 {
-  sub hook {
+  my $hook_called = 0;
+  sub hook_called {
+    $hook_called = 1;
   }
-  $p->set_hooks(yaml_metadata => \&hook);
+  $p->set_hooks(yaml_metadata => \&hook_called);
   like(warning { $p->convert($invalid_page) }, qr/invalid/, "Got expected warning");
+  ok(!$hook_called, "Hook was not called because metadata was invalid.");
 }
 
-# Test 4: What happens if inside the hook we die()
+# Hook exceptions are propagated
 {
   sub hook_die {
     die "last words";