Add Test-Markdown function for structural validation

[MariusStorhaug]

CommonMark and GitHub Flavored Markdown are forgiving by design — almost any input renders as something — but real-world Markdown still has structural problems: malformed frontmatter, unterminated fenced code blocks, table rows with mismatched column counts, broken link references. A Test-Markdown function gives scripts a way to catch these before publishing.

This sets the same pattern as PowerShell's Test-Json: returns [bool], writes specific errors to the error stream when invalid.

Request

Desired capability

Test-Markdown -Path README.md          # validate a file
$content | Test-Markdown                # validate a string
'```\nunterminated' | Test-Markdown     # returns $false, writes error

Parameters

Parameter	Description
-Path	File path to validate (parameter set: Path)
-LiteralPath	Literal path (parameter set: LiteralPath)
-InputObject	String to validate (ValueFromPipeline, default set)
-Strict	Fail on lint-style issues (e.g., trailing whitespace, mixed list markers) in addition to structural errors

Validation scope (default — without -Strict)

• Unterminated fenced code blocks
• Malformed YAML frontmatter (when present and parseable by ConvertFrom-Yaml)
• Broken link reference definitions (e.g., [link][undefined-ref])
• Inconsistent table column counts within a table

Acceptance criteria

• Returns $true when content is structurally valid Markdown
• Returns $false when content has structural errors; specific errors written to the error stream
• Accepts pipeline input as a string
• Mirrors Test-Json parameter shape and behavior

---

Technical decisions

Scope clarification: Markdown has no formal validation grammar. This function checks for structural problems that are unambiguously wrong (per CommonMark spec), not stylistic preferences. Stylistic linting (heading style, list-marker consistency) is opt-in via -Strict.

Implementation: Reuses ConvertFrom-Markdown (per #8) parser. Catches structural exceptions and writes them as non-terminating errors.

Function placement: src/functions/public/Test-Markdown.ps1.

Output type: [bool] only.

Overlap with external linters: markdownlint and similar tools cover stylistic linting more comprehensively. Test-Markdown complements rather than replaces them — it provides a pure-PowerShell, no-dependency entry point for CI scripts.

---

Implementation plan

• Add Test-Markdown in src/functions/public/Test-Markdown.ps1
• Add Pester tests — valid string, unterminated code fence, malformed frontmatter, broken link reference, valid file, pipeline input, error-stream contents
• Add -Strict mode tests once stylistic rules are defined (separate sub-task)
• Update README with usage example

Related

• Add ConvertFrom-Markdown and ConvertTo-Markdown to parse and generate markdown #8 — ConvertFrom-Markdown (prerequisite for parser-driven validation)