📖 [Docs]: YAML commands grouped by task with in-depth guides for each area

[Marius Storhaug (MariusStorhaug)]

The Yaml module's commands are now organised by what you are trying to do — convert values, work with files, or work with YAML streams — and each area has its own in-depth guide on the documentation site. The guides carry the long-form material that previously only existed in the repository README, plus a new reference that shows exactly what a parsed YAML document becomes in PowerShell. Nothing about how the commands behave has changed.

New: Task-oriented guides for each command area

The documentation site now has three landing pages, one per area:

• Conversion — ConvertFrom-Yaml and ConvertTo-Yaml. Moving data between YAML text and PowerShell values.
• Files — Import-Yaml and Export-Yaml. Path resolution, strict decoding, and atomic writes on top of conversion.
• Streams — Test-Yaml, Format-Yaml and Merge-Yaml. Working on YAML text at the representation level, never projecting to PowerShell objects.

Each page explains how that area works, when to reach for each command, and shows runnable examples.

New: Reference for the YAML to PowerShell projection

The Conversion guide answers the question "what will this document actually look like once I parse it?". It documents which scalar forms produce string, bool, Int32/Int64/BigInteger, Decimal/Double, $null and timestamps; which YAML 1.1-only forms such as yes, 0b1010 and bare dates deliberately stay strings; how mappings project to PSCustomObject versus -AsHashtable ordered dictionaries that can hold complex, null and numeric keys; how sequences and -NoEnumerate interact; how multi-document streams emit one object per document; how anchors and aliases preserve object identity, including recursive nodes; what !!set, !!omap, !!pairs and !!binary produce; and the four cases that deliberately fail rather than silently lose data.

A worked example shows a representative document alongside a diagram of the resulting PowerShell shape, so the types, nesting and shared references can be read off directly.

Changed: The README is a landing page again

The README keeps the overview, requirements, installation, the full command table, and a short taster for each area, then links onward to the guides. The long-form depth moved into the guides rather than being dropped.

Changed: Command documentation URLs now include the group

Because each command's generated page now lives under its group, the published address of a command page gains the group segment — for example psmodule.io/Yaml/Functions/Conversion/ConvertFrom-Yaml/. Every Get-Help -Online link and every in-repo cross-reference was updated to match.

---

Technical details

Purely organisational. No function body, parameter, or behaviour change: every source move is a pure git mv — git status reported 98 renames with zero content edits — and the only later source edits are single-line .LINK comment updates.

Public grouping (src/functions/public/):

Group	Commands
Conversion	ConvertFrom-Yaml, ConvertTo-Yaml
Files	Import-Yaml, Export-Yaml
Streams	Test-Yaml, Format-Yaml, Merge-Yaml

Streams is a behavioural domain, not a catch-all: Test-Yaml, Format-Yaml and Merge-Yaml all operate on YAML text at the representation level and never project to PowerShell objects, which is exactly what separates them from Conversion.

Private grouping (src/functions/private/, 91 files). Assignment was mechanical, not by taste: a reachability graph was computed from each public command through private call references, and each helper was placed in the single public domain that reaches it, or in a shared group when more than one domain reaches it.

Group	Count	Rule
Conversion	7	reached only from ConvertFrom-Yaml / ConvertTo-Yaml — the PowerShell object projector and serialization-graph helpers
Files	1	reached only from Import-Yaml / Export-Yaml — Get-YamlTextEncoding
Streams	16	reached only from Format-Yaml / Merge-Yaml — the merge engine and representation-text emitter
Engine	67	reached from more than one public domain

Engine was chosen over Core because the standard asks for resource or behaviour groups. Core names a position in the dependency tree; Engine names what the files are — the shared YAML processing engine of scanner, block and flow readers, composer, tag resolution, emitter primitives, diagnostics and resource limits. Only one shared group was introduced; no verb folders, no sub-grouping below the domain level.

Documentation mechanism. Document-PSModule's Build-PSModuleDocumentation publishes src/functions/public/<Group>/<Group>.md as that section's index.md, and relocates each generated command page to mirror the source layout. Command reference pages are generated separately from comment-based help, so the group pages are narrative only and contain no generated parameter tables, per the README guidance in Repository-Standard.md.

That relocation is why every canonical link had to move too. The framework's own PublicHelpLink source-code test caught this on the first CI run: it expects https://psmodule.io/Yaml/Functions/<Group>/<Name>/. All 98 .LINK values (7 public, 91 private helpers pointing at the public command they serve) were updated by scripted replacement, and cross-group links inside the three group pages use the same absolute published URLs rather than relative paths, because a relative .md link would not survive the index.md rename on the site.

README relocation. Moved out and absorbed: ## Parse YAML and ## Serialize PowerShell values into Conversion.md; ## Import YAML files and ## Export YAML files into Files.md; ## Format YAML streams, ## Merge YAML streams and ## Validate YAML into Streams.md. Kept in the README: the overview and layering paragraph, requirements, installation, the full command table (now grouped and linked), a short taster per group, and ## Data model and safety, ## Conformance corpus and ## Compatibility boundaries in full — those are repository-level compatibility claims about the artifact rather than task guidance, so they belong on the landing page. Nothing was deleted.

Verification of the new reference. Every factual claim in Conversion.md was executed against a module composed from this branch's source, not inferred from reading. That includes the scalar type table, Int32/Int64/BigInteger widening, Decimal versus Double selection, DateTime (Kind = Utc) versus DateTimeOffset for !!timestamp, [System.DBNull]::Value for null dictionary keys, ReferenceEquals identity through aliases, !!set/!!omap/!!pairs/!!binary projections, the pipeline record counts for -NoEnumerate, and the four error IDs YamlMappingKeyNotString, YamlPropertyNameCollision, YamlPropertyNameReserved and YamlDuplicateKey. Three drafting errors were caught this way and corrected: a wrong dictionary entry count, an Export-Yaml -LiteralPath example for a parameter that does not exist, and a $config.newKey = … example that a PSCustomObject rejects.

Tests changed. tests/Packaging.Tests.ps1, 'keeps the owned processor layers explicit and source-level' — the ten expected private paths now carry their domain folder (Engine\, Conversion\, Streams\). Two tests were added so the layout itself is enforced rather than only documented: 'groups every function file under a domain folder' (no loose .ps1 directly under public/private, and exactly one folder level) and 'ships a group overview page beside every public domain' (each public group has its <Group>.md). The whole tests/ tree was grepped for other hardcoded functions\public or functions\private paths; there were none.

Validation. Baseline on this branch point was 392 passed / 0 failed / 4 skipped across the nine functional suites; after the reorganisation the same nine suites report 392 / 0 / 4. Invoke-ScriptAnalyzer with .github/linters/.powershell-psscriptanalyzer.psd1 is clean on the changed test file. markdownlint-cli2, textlint (with textlint-rule-terminology) and codespell are clean on the four markdown files using the repository's own linter configs.

Process-PSModule only triggers on pull requests whose base is main, so this stacked pull request gets no automatic checks. It was validated by dispatching the full workflow against the branch: run 30756441401 is green end to end — Build-Module, Build-Docs, Lint-SourceCode, Test-SourceCode, Test-Module and every Test-ModuleLocal suite on Linux, macOS and Windows. Only Publish-Site and Publish-Module are skipped, as expected off main. The absence of PR checks on release-stacked branches is a workflow-trigger gap, not a gap in this change.

No src/manifest.psd1 was added; src/header.ps1 remains the source of truth for #Requires -Version 7.6 and #Requires -PSEdition Core.

Change type: Docs. The only user-visible outcome is documentation; the source reorganisation is internal upkeep with no shipped behaviour change. Docs and Maintenance both map to NoRelease, so the release impact is identical either way. The repository had no NoRelease label, so it was created to match the rest of the PSModule organisation.

Implementation plan progress: completes all four scope items in #50.

Changed surface	Standards checked	Framework docs checked	Result
src/functions/** (PowerShell)	Standards — Layout rules: group by domain, mirror public and private domains, group documentation pages with source	PSModule module source layout; Test-PSModule PublicHelpLink contract	Aligned
src/functions/public/*/*.md (docs)	Repository-Standard — README pages must not duplicate generated command documentation	Document-PSModule Build-PSModuleDocumentation section-index mechanism	Aligned
README.md	Repository-Standard — keep / trim / relocate only to a published home	PSModule Repository-Standard	Aligned
tests/**	Test-Specification	None (no framework-specific docs)	Aligned

Issue convergence sweep: scoped to open PSModule/Yaml issues touching module source layout and documentation structure. Only #50 is fully satisfied by this diff. #47 is the release pull request this one stacks on and is linked as context only.

Relevant issues (or links)

• Closes Align Yaml module source layout to PSModule domain-grouping standards #50
• 🌟 [Major]: New PowerShell module v1.0.0 with complete YAML 1.2.2 command suite #47

[Marius Storhaug (MariusStorhaug)]

Checks note for reviewers: this pull request targets release/v1.0.0, and Process-PSModule only triggers on pull requests based on main, so GitHub reports no checks here. The workflow was dispatched manually against this branch instead — run 30756441401 is green end to end across Linux, macOS and Windows, with only Publish-Site and Publish-Module skipped as expected off main. The trigger gap itself is tracked in #54.

Auto-merge is deliberately not enabled. This branch is stacked on #47; if #47 squash-merges into main first, release/v1.0.0 disappears and this pull request needs rebasing onto main rather than merging. Sequencing is for the release owner to decide.