(fixup) Sync docs

Author: michaeltlombardi

dsc/docs-conceptual/dsc-3.0/concepts/configurations.md renamed to dsc/docs-conceptual/dsc-3.0/concepts/configuration-documents/overview.md

@@ -3,7 +3,7 @@ description: >-
   DSC configuration documents are YAML or JSON data files that define the desired state of a system
   declaratively. They are used to retrieve, validate, and enforce the state of multiple resource
   instances.
-ms.date: 03/04/2025
+ms.date: 03/18/2025
 title: DSC configuration documents
 ---
 
@@ -241,9 +241,9 @@ hadErrors: false
 - [DSC Configuration document schema reference][05]
 - [Command line reference for the 'dsc config' command][06]
 
-[01]: ./resources.md
-[02]: ../reference/schemas/config/metadata.md#microsoftdsc
-[03]: ../reference/schemas/config/document.md
-[04]: ./resources.md#resource-type-names
-[05]: ../reference/schemas/config/document.md
-[06]: ../reference/cli/config/command.md
+[01]: ../resources/index.md.md
+[02]: ../../reference/schemas/config/metadata.md#microsoftdsc
+[03]: ../../reference/schemas/config/document.md
+[04]: ../resources/index.md#resource-type-names
+[05]: ../../reference/schemas/config/document.md
+[06]: ../../reference/cli/config/command.md

dsc/docs-conceptual/dsc-3.0/concepts/enhanced-authoring.md

@@ -3,12 +3,14 @@ description: >-
   DSC configuration documents and resource manifests are YAML or JSON data files that adhere to a
   published JSON schema. You can use enhanced schemas when authoring these files for an improved
   experience.
-ms.date: 03/04/2025
+ms.date: 03/18/2025
 title:   Authoring with enhanced schemas
 ---
 
 # Authoring with enhanced schemas
 
+<!-- markdownlint-capture -->
+
 Working with Microsoft's Desired State Configuration (DSC) platform involves writing DSC
 [configuration documents][01] and [resource manifests][02]. Configuration documents are YAML or
 JSON data files that declare the desired state of a system. Resource manifests are JSON or YAML
@@ -48,7 +50,7 @@ schemas, see the `$schema` sections in [DSC Configuration document schema refere
 :::image type="complex" source="media/enhanced-authoring/hover-help.png" alt-text="This screenshot shows enhanced hover documentation.":::
    This screenshot shows enhanced hover documentation for the 'type' property in a configuration document. The documentation includes a link at the top to the online documentation, followed by prose explaining the syntax for the property.
 :::image-end:::
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 With the enhanced schemas, hovering on a property displays contextual help rendered from Markdown.
 When possible, the hover help includes a link to the online documentation.
@@ -59,7 +61,7 @@ When possible, the hover help includes a link to the online documentation.
 :::image type="complex" source="media/enhanced-authoring/peek-help.png" alt-text="This screenshot shows enhanced documentation with autocomplete.":::
    This screenshot shows the DSC Resource instance autocomplete option and contextual documentation in a configuration document. The contextual help is shown to the side of the completion option list. The help includes a link to the online documentation, the descriptive prose, and the required properties.
 :::image-end:::
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 When using IntelliSense while authoring with an enhanced schema, the quick info shown for the
 completion options displays as rendered Markdown. When possible, the quick info includes a link to
@@ -71,7 +73,7 @@ the online documentation.
 :::image type="complex" source="media/enhanced-authoring/enum-help.png" alt-text="This screenshot shows contextual documentation for an enum.":::
    This screenshot shows the contextual documentation for the 'return' property enum values in a resource manifest. The contextual help is shown beneath the enum list, describing the currently selected value.
 :::image-end:::
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 The enhanced schemas add documentation for enum values when using IntelliSense to select a valid
 value. By default, schemas can't provide per-enum documentation. They can only define documentation
@@ -87,7 +89,7 @@ for the property an enum belongs to.
 :::image type="complex" source="media/enhanced-authoring/snippet-completion.png" alt-text="This screenshot shows the editable output for the chosen snippet.":::
    This screenshot shows the editable output for the 'New metadata property (object)' snippet. It defined a new property named 'metadataName' with a nested key-value pair. The property name, key, and value are editable text that a user can tab through, like any other VS Code snippet.
 :::image-end:::
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 For common use cases, the enhanced schemas define sets of default snippets. These snippets are
 contextual and make it easier and faster to define the file. The snippets work like any other
@@ -99,7 +101,7 @@ snippets in VS Code.
 :::image type="complex" source="media/enhanced-authoring/error-messages.png" alt-text="This screenshot shows an enhanced error message for failed validation.":::
    This screenshot shows a contextual error message when the name property for a resource instance doesn't match the validating regular expression. The value is the string 'invalid?' and the error message says "Invalid value for instance name. An instance name must be a non-empty string containing only letters, numbers, and spaces."
 :::image-end:::
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 When defining values, the enhanced schemas have contextual error messages instead of the default
 error messages that JSON schema validation raises. This is particularly helpful for properties that
@@ -109,7 +111,7 @@ and lists the regular expression pattern.
 ## Using the enhanced configuration document schema
 
 To associate every configuration document with the enhanced schema, add the following snippet to
-your [settings.json] file in VS Code. You can define these options in your user settings or for a
+your `settings.json` file in VS Code. You can define these options in your user settings or for a
 specific workspace.
 
 <!-- markdownlint-disable MD013 -->
@@ -127,7 +129,7 @@ specific workspace.
     "https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}"
 }
 ```
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 These settings depend on the configuration documents having a name that ends with one of the
 following suffixes:
@@ -144,9 +146,9 @@ following comment to the top of the document:
 
 <!-- markdownlint-disable MD013 -->
 ```yml
-# yaml-language-server: $schema=aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
+# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
 ```
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-resore -->
 
 This option works regardless of the filename, but only for YAML files. To use the enhanced schema
 when authoring configuration documents in JSON, you must define the schema association in your
@@ -155,7 +157,7 @@ when authoring configuration documents in JSON, you must define the schema assoc
 ## Using the enhanced resource manifest schema
 
 To use the enhanced schema when authoring resource manifests, add the following snippet to
-your [settings.json] file in VS Code. You can define this option in your user settings or for a
+your `settings.json` file in VS Code. You can define this option in your user settings or for a
 specific workspace.
 
 <!-- markdownlint-disable MD013 -->
@@ -170,7 +172,7 @@ specific workspace.
     "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json": "**.dsc.resource.{yaml,yml}"
 }
 ```
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 To associate a specific resource manifest formatted as YAML with the enhanced schema, add the
 following comment to the top of the manifest:
@@ -179,13 +181,13 @@ following comment to the top of the manifest:
 ```yml
 # yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
 ```
-<!-- markdownlint-enable MD013 -->
+<!-- markdownlint-restore -->
 
 This option works regardless of the filename, but only for YAML files. To use the enhanced schema
 when authoring resource manifests in JSON, you must define the schema association in your
 `settings.json`.
 
-[01]: configurations.md
+[01]: ./configuration-documents/index.md
 [02]: ../resources/concepts/anatomy.md#dsc-resource-manifests
 [03]: ../reference/schemas/config/document.md#schema
 [04]: ../reference/schemas/resource/manifest/root.md#schema

dsc/docs-conceptual/dsc-3.0/concepts/output-accessibility.md

@@ -1,7 +1,9 @@
 ---
-description: This article aims to guide you through methods to output from PowerShell in formats that are friendly for screen readers, enhancing the accessibility of your scripts.
+description: >-
+  This article aims to guide you through methods to output from PowerShell in formats that are
+  friendly for screen readers, enhancing the accessibility of your scripts.
 ms.custom: experience
-ms.date: 09/12/2024
+ms.date: 03/18/2025
 title: Improve the accessibility of DSC output in PowerShell
 ---
 
@@ -102,8 +104,15 @@ dsc resource list -a Microsoft.Windows/WindowsPowerShell |
 
 ## Additional reading
 
-- [Improve the accessibility of output in PowerShell](/powershell/scripting/learn/shell/output-for-screen-reader)
-- [Out-GridView](xref:Microsoft.PowerShell.Utility.Out-GridView)
-- [Export-Csv](xref:Microsoft.PowerShell.Utility.Export-Csv)
-- [ConvertTo-Html](xref:Microsoft.PowerShell.Utility.ConvertTo-Html)
-- [about_Calculated_Properties](/powershell/module/microsoft.powershell.core/about/about_calculated_properties)
+- [Improve the accessibility of output in PowerShell][01]
+- [Out-GridView][02]
+- [Export-Csv][03]
+- [ConvertTo-Html][04]
+- [about_Calculated_Properties][05]
+
+<!-- Link reference definitions -->
+[01]: /powershell/scripting/learn/shell/output-for-screen-reader
+[02]: xref:Microsoft.PowerShell.Utility.Out-GridView
+[03]: xref:Microsoft.PowerShell.Utility.Export-Csv
+[04]: xref:Microsoft.PowerShell.Utility.ConvertTo-Html
+[05]: /powershell/module/microsoft.powershell.core/about/about_calculated_properties

dsc/docs-conceptual/dsc-3.0/resources/concepts/anatomy.md renamed to dsc/docs-conceptual/dsc-3.0/concepts/resources/anatomy.md

@@ -2,7 +2,7 @@
 description: >-
   Describes the components of a DSC command resource, how DSC uses them, and what's required
   of them.
-ms.date: 03/04/2025
+ms.date: 03/18/2025
 title:   Anatomy of a command-based DSC Resource
 ---
 
@@ -19,11 +19,17 @@ DSC command resources are defined with at least two files:
 
 ## DSC resource manifests
 
-DSC resource manifests are defined as JSON files. For DSC to recognize a JSON file as a manifest,
+DSC resource manifests are defined as data files. For DSC to recognize a data file as a manifest,
 the file must meet the following criteria:
 
+1. The data in the file must be formatted as YAML or JSON.
+1. The file must use UTF-8 encoding.
 1. The file must be discoverable in the `PATH` environment variable.
-1. The filename must end with `.dsc.resource.json`.
+1. The filename must end with one of the following suffixes:
+
+   - `.dsc.resource.json`
+   - `.dsc.resource.yaml`
+   - `.dsc.resource.yml`
 
 When DSC searches the local system for available command resources, it searches every folder in the
 `PATH` for files that use the DSC resource manifest naming convention. DSC then parses each of
@@ -72,9 +78,6 @@ The manifest may define:
 The manifest doesn't need to specify the same executable file for every operation. The definition
 for each operation is independent.
 
-<!-- For more information on authoring DSC Resource manifests, see
-[Authoring a DSC Resource Manifest][02]. -->
-
 ## DSC resource executables
 
 Command resources always require an executable file for DSC to run. The manifest doesn't need to be
@@ -86,9 +89,6 @@ the executable once per operation, using the exit code returned by the executabl
 the command was successful. DSC treats exit code `0` as a success and all other exit codes as an
 error.
 
-<!-- For more information about error handling, see
-[Handling errors in a DSC command resource][03]. -->
-
 ### Inputs
 
 DSC sends input to command resources as one of the following:
@@ -131,24 +131,18 @@ Command resources can report logging information to DSC by emitting JSON Lines t
 Each log entry must be a JSON object that includes two keys:
 
 1. The `message` key defines the human-readable string for the log entry.
-1. The `level` key defines whether the message represents an `error`, a `warning`, or `information`.
+1. The `level` key defines whether the message represents an `error`, a `warning`, or
+   `information`.
 
 DSC collects messages from resources and displays them in the results for a configuration
 operation. When DSC invokes a resource directly outside of a configuration, it doesn't collect the
 messages. Instead, DSC emits the messages to stderr.
 
-<!-- For more information about logging from command-based DSC Resources, see
-[Logging messages from a DSC command resources][05]. -->
-
 ## Related Content
 
-<!-- - [Authoring a DSC Resource Manifest][02] -->
-- [Write your first DSC Resource overview][06]
 - [DSC Resource Manifest schema reference][01]
+- [DSC Resources][02]
 
 [01]: ../../reference/schemas/resource/manifest/root.md
-<!-- [02]: authoring-a-manifest.md -->
-<!-- [03]: handling-errors.md -->
+[02]: index.md
 [04]: https://jsonlines.org/
-<!-- [05]: logging-messages.md -->
-[06]: ../tutorials/first-resource/overview.md