Add Format-Markdown function for normalization

[MariusStorhaug]

Hand-written and machine-generated Markdown often has inconsistent heading styles, list markers, table column padding, and trailing whitespace. A Format-Markdown function normalizes the text without changing the rendered output — equivalent to ConvertFrom-Markdown | ConvertTo-Markdown but expressed as a single ergonomic call.

Sister modules already follow this pattern: Format-Json and Format-Hashtable.

Request

Desired capability

Get-Content README.md -Raw | Format-Markdown
Format-Markdown -Path README.md

Parameters

Parameter	Description
-InputObject	String to format (ValueFromPipeline, default set)
-Path	File path to read and format
-LiteralPath	Literal file path
-HeadingStyle	ATX (default, # heading) or Setext (heading\n=======)
-ListMarker	Dash (default, -), Asterisk (*), or Plus (+) for unordered lists
-TablePadding	Pad table cells with spaces for column alignment (default: $true)

Acceptance criteria

• Format-Markdown $s produces canonical-form Markdown for $s
• Idempotent: Format-Markdown (Format-Markdown $s) equals Format-Markdown $s
• Rendered output is unchanged: ConvertFrom-Markdown $s and ConvertFrom-Markdown (Format-Markdown $s) produce equivalent document models
• -HeadingStyle, -ListMarker, -TablePadding control specific normalization behaviors

---

Technical decisions

Implementation: Parses input with ConvertFrom-Markdown (per #8) and re-emits with ConvertTo-Markdown using the requested style options. Reuses existing logic — no new parser or emitter.

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

Parameter sets: InputObject (default, pipeline) and Path / LiteralPath for file input.

Frontmatter: Preserved as-is by default; YAML frontmatter pretty-printing follows the same rules as Format-Yaml (when available) — out of scope for v1.

Overlap with external tools: Tools like prettier and markdownlint --fix cover similar territory. Format-Markdown provides a pure-PowerShell entry point for CI scripts that need predictable, dependency-free formatting.

---

Implementation plan

• Add Format-Markdown in src/functions/public/Format-Markdown.ps1
• Add Pester tests — basic format, -HeadingStyle, -ListMarker, -TablePadding, idempotent round-trip, frontmatter preservation
• Update README and examples/General.ps1

Related

• Add a specification-compliant markdown object hierarchy with ConvertFrom-Markdown and ConvertTo-Markdown #8 — ConvertFrom-Markdown / ConvertTo-Markdown (prerequisite)
• Add frontmatter support to ConvertFrom-Markdown and ConvertTo-Markdown #21 — Frontmatter support (affects formatting of frontmatter blocks)