Drop frontmatter extraction; require valid YAML input and tolerate document markers

Author: MariusStorhaug

README.md

@@ -1,6 +1,13 @@
-# {{ NAME }}
+# Yaml
 
-{{ DESCRIPTION }}
+A PowerShell module for working with YAML — parse YAML strings into PowerShell objects and serialize PowerShell objects back into YAML.
+
+The module ships two cmdlets that mirror PowerShell's built-in `ConvertFrom-Json` / `ConvertTo-Json`, so the experience is familiar:
+
+- `ConvertFrom-Yaml` — parses a YAML string into a `[PSCustomObject]` (or an ordered hashtable with `-AsHashtable`).
+- `ConvertTo-Yaml` — serializes a PowerShell object, hashtable, or array into a YAML-formatted string.
+
+No external dependencies — pure PowerShell. Aligned with the [YAML 1.2.2 core schema](https://yaml.org/spec/1.2.2/#103-core-schema).
 
 ## Prerequisites
 
@@ -13,18 +20,21 @@ This uses the following external resources:
 To install the module from the PowerShell Gallery, you can use the following command:
 
 ```powershell
-Install-PSResource -Name {{ NAME }}
-Import-Module -Name {{ NAME }}
+Install-PSResource -Name Yaml
+Import-Module -Name Yaml
 ```
 
 ## Usage
 
 The module provides two cmdlets that mirror PowerShell's built-in `ConvertFrom-Json` / `ConvertTo-Json`:
 
-| Cmdlet              | Alias            | Purpose                                |
-| ------------------- | ---------------- | -------------------------------------- |
-| `ConvertFrom-Yaml`  | `ConvertFrom-Yml` | Parse a YAML string into an object.   |
-| `ConvertTo-Yaml`    | `ConvertTo-Yml`  | Serialize an object into a YAML string. |
+| Cmdlet              | Alias             | Purpose                                  |
+| ------------------- | ----------------- | ---------------------------------------- |
+| `ConvertFrom-Yaml`  | `ConvertFrom-Yml` | Parse a YAML string into an object.      |
+| `ConvertTo-Yaml`    | `ConvertTo-Yml`   | Serialize an object into a YAML string.  |
+
+> [!IMPORTANT]
+> The input to `ConvertFrom-Yaml` must be a valid YAML string. The cmdlet does not read files or extract YAML frontmatter from markdown — that is the caller's responsibility (for example, using a Markdown module to extract frontmatter, then piping the result into `ConvertFrom-Yaml`).
 
 ### YAML specification
 
@@ -37,7 +47,7 @@ Practical implications of the core schema:
 - Integers and floats parse to their native types using invariant culture.
 - Anything else is a string. Quoted strings (`'...'`, `"..."`) always preserve the string type.
 
-The supported YAML subset covers block-style mappings, block-style sequences, nested structures, single- and double-quoted scalars (with `\n`, `\t`, `\r`, `\\`, `\"` escapes in double quotes), and full-line / inline `#` comments. Flow style (`[a, b]`, `{a: 1}`), block scalars (`|`, `>`), anchors, aliases, tags, multi-document streams, and `!!timestamp` are not yet supported.
+The supported YAML subset covers block-style mappings, block-style sequences, nested structures, single- and double-quoted scalars (with `\n`, `\t`, `\r`, `\\`, `\"` escapes in double quotes), document start (`---`) and end (`...`) markers, and full-line / inline `#` comments. Flow style (`[a, b]`, `{a: 1}`), block scalars (`|`, `>`), anchors, aliases, tags, multi-document streams, and `!!timestamp` are not yet supported.
 
 ### Example 1: Parse a YAML string
 
@@ -59,13 +69,7 @@ $yaml | ConvertFrom-Yaml
 Get-Content config.yaml -Raw | ConvertFrom-Yaml -AsHashtable
 ```
 
-### Example 3: Parse YAML frontmatter from a markdown file
-
-```powershell
-Get-Content post.md -Raw | ConvertFrom-Yaml
-```
-
-### Example 4: Convert an object to YAML
+### Example 3: Convert an object to YAML
 
 ```powershell
 [ordered]@{
@@ -74,7 +78,7 @@ Get-Content post.md -Raw | ConvertFrom-Yaml
 } | ConvertTo-Yaml
 ```
 
-### Example 5: Force a top-level YAML sequence
+### Example 4: Force a top-level YAML sequence
 
 ```powershell
 Get-Process | Select-Object -First 3 Name, Id | ConvertTo-Yaml -AsArray

examples/General.ps1

@@ -22,30 +22,16 @@ $person.skills[0]   # PowerShell
 $hash = $yaml | ConvertFrom-Yaml -AsHashtable
 $hash['age']        # 30
 
-# 3. Parse YAML frontmatter from a markdown document
-$markdown = @'
----
-title: Hello world
-draft: false
----
-# Body
-
-Markdown content here.
-'@
-
-$frontmatter = $markdown | ConvertFrom-Yaml
-$frontmatter.title  # Hello world
-
-# 4. Convert an object to YAML
+# 3. Convert an object to YAML
 [ordered]@{
     name   = 'Alice'
     age    = 30
     skills = @('PowerShell', 'YAML')
 } | ConvertTo-Yaml
 
-# 5. Force a top-level sequence with -AsArray
+# 4. Force a top-level sequence with -AsArray
 Get-Process | Select-Object -First 3 Name, Id | ConvertTo-Yaml -AsArray
 
-# 6. Round-trip
+# 5. Round-trip
 $obj = [ordered]@{ a = 1; b = @('x', 'y') }
 $obj | ConvertTo-Yaml | ConvertFrom-Yaml -AsHashtable

src/functions/private/ConvertFrom-YamlFrontmatter.ps1

@@ -47,6 +47,12 @@
             continue
         }
 
+        # Skip YAML document markers: --- (start) and ... (end).
+        $trimmed = $stripped.Trim()
+        if ($trimmed -eq '---' -or $trimmed -eq '...') {
+            continue
+        }
+
         $result.Add([pscustomobject]@{
                 Indent  = $indent
                 Content = $stripped.TrimEnd()

src/functions/private/ConvertFrom-YamlLineStream.ps1

@@ -7,15 +7,18 @@
         Parses a YAML document and returns a `[PSCustomObject]` (default) or an
         `[ordered]` hashtable when `-AsHashtable` is specified.
 
-        Supports a useful subset of YAML 1.2:
+        Supports a useful subset of YAML 1.2.2 (core schema):
           - Block-style mappings (key: value)
           - Block-style sequences (- item)
           - Nested structures
-          - Scalars: strings, integers, floats, booleans, null
+          - Scalars: strings, integers, floats, booleans (`true`/`false`), null (`null`/`~`/empty)
           - Single- and double-quoted strings (with `\n`, `\t`, `\r`, `\\`, `\"` in double quotes)
-          - YAML frontmatter delimited by `---` (typical in markdown)
+          - Document start (`---`) and end (`...`) markers are tolerated
           - Full-line comments (`#`) and inline comments after values
 
+        Input must be a valid YAML string. Reading frontmatter out of a markdown
+        document is the responsibility of the caller (see the Markdown module).
+
         Out of scope for this version: flow style (`[a, b]`, `{a: 1}`), block scalars
         (`|`, `>`), anchors/aliases, tags, multi-document streams, and `!!timestamp`.
 
@@ -42,11 +45,6 @@
 
         Reads a YAML file and returns it as an ordered hashtable.
 
-        .EXAMPLE
-        Get-Content post.md -Raw | ConvertFrom-Yaml
-
-        Extracts and parses the YAML frontmatter from a markdown file.
-
         .OUTPUTS
         System.Management.Automation.PSCustomObject
 
@@ -92,10 +90,7 @@
             return $null
         }
 
-        # Strip frontmatter delimiters: leading "---" line and trailing "---" line.
-        $text = ConvertFrom-YamlFrontmatter -Text $text
-
-        # Pre-process into logical lines (drop comments and blank lines, keep indentation).
+        # Pre-process into logical lines (drop comments, blank lines, and document markers).
         $lines = ConvertFrom-YamlLineStream -Text $text
         if ($lines.Count -eq 0) {
             return $null