From 1b19eac7a6104e3cb2801dbcc8ff9d7ab828fb80 Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Tue, 27 Jan 2026 10:21:00 -0600
Subject: [PATCH] Update README and markdownlint rules (#12703)

* Update README and markdownlint rules

* Fix typos
---
 .markdownlint.yaml  | 36 ++++++++++++++----------------------
 reference/README.md | 24 ++++++++++++------------
 2 files changed, 26 insertions(+), 34 deletions(-)

diff --git a/.markdownlint.yaml b/.markdownlint.yaml
index 99e42414b5d0..1e299909a99e 100644
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -1,24 +1,11 @@
-docsmd.alert: true
-docsmd.codesnippet: true
-docsmd.column: true
-docsmd.image: true
-docsmd.moniker: true
-docsmd.no-loc: true
-docsmd.row: true
-docsmd.securelinks: true
-docsmd.syntax: true
-docsmd.video: true
-docsmd.xref: true
-docsmd.zone: true
-
 MD001: true  # header-increment
-# MD002      # first-header-h1 - Superceded by MD041
+# MD002      # first-header-h1 - Superseded by MD041
 MD003:       # header-style
   style: atx
 MD004:       # ul-style
   style: dash
 MD005: true  # list-indent
-# MD006      # ul-start-left - Superceded by MD007's start_indented option
+# MD006      # ul-start-left - Superseded by MD007
 MD007:       # ul-indent
   indent: 2
   start_indented: false
@@ -116,14 +103,19 @@ MD051: true  # link-fragments
 MD052: true  # reference-links-images
 MD053: true  # link-image-reference-definitions
 MD054:       # link-image-style
-  autolink: false
-  collapsed: false
-  full: true
-  inline: true
-  shortcut: false
-  url_inline: true
+  autolink:   false  # Allow autolinks (default true)
+  collapsed:  false  # Allow collapsed reference links and images (default true)
+  full:       true   # Allow full reference links and images (default true)
+  inline:     true   # Allow inline links and images (default true)
+  shortcut:   false  # Allow shortcut reference links and images (default true)
+  url_inline: true   # Allow URLs as inline links (default true)
 MD055:       # table-pipe-style
   style: leading_and_trailing
 MD056: true  # table-column-count
-# MD057      # undefined
+# MD057:     # not used by linter - never defined
 MD058: true  # blanks-around-tables
+MD059:       # descriptive-link-text
+  prohibited_texts: ["click here","here","link","more"]
+MD060:       # table-column-style
+  aligned_delimiter: false
+  style: any
diff --git a/reference/README.md b/reference/README.md
index 025027f790c9..0ad85f876349 100644
--- a/reference/README.md
+++ b/reference/README.md
@@ -1,13 +1,12 @@
 ---
-locale: en-us
-ms.date: 01/02/2026
-schema: 2.0.0
+ms.date: 01/27/2026
 title: README
 ---
 # PowerShell Reference
 
-Reference material is organized into release versions. The content for each
-version is organized by module name. `about_*` articles are in an `About` folder under the module folder they are related to. Most of them are under `Microsoft.PowerShell.Core/About`.
+Reference material is organized into release versions. The content for each version is organized by
+module name. The `about_*` articles are in an `About` folder under the module folder they're related
+to. Most of them are under `Microsoft.PowerShell.Core/About`.
 
 ## Modules
 
@@ -26,9 +25,6 @@ version is organized by module name. `about_*` articles are in an `About` folder
 | Microsoft.PowerShell.Security             |   X   |   X   |   X   |   X   |
 | Microsoft.PowerShell.Utility              |   X   |   X   |   X   |   X   |
 | Microsoft.WSMan.Management                |   X   |   X   |   X   |   X   |
-| PackageManagement                         |       |       |       |       |
-| PowershellGet                             |       |       |       |       |
-| PSDesiredStateConfiguration               |       |       |       |       |
 | PSDiagnostics                             |   X   |   X   |   X   |   X   |
 | PSReadLine                                |   X   |   X   |   X   |   X   |
 | PSScheduledJob                            |   X   |       |       |       |
@@ -38,7 +34,11 @@ version is organized by module name. `about_*` articles are in an `About` folder
 
 ## History
 
-- `PackageManagement` and `PowershellGet` content moved to the
-`PowerShell-Docs-PSGet` repository.
-- `PSDesiredStateConfiguration` content moved to the `PowerShell-Docs-DSC`
-repository with the release of PowerShell DSC 2.0.
+- `PackageManagement` and `PowerShellGet` content moved to the [PowerShell-Docs-PSGet][02]
+  repository.
+- `PSDesiredStateConfiguration` content moved to the [PowerShell-Docs-DSC][01] repository with the
+  release of PowerShell DSC 2.0.
+
+<!-- link references -->
+[01]: https://github.com/MicrosoftDocs/PowerShell-Docs-DSC
+[02]: https://github.com/MicrosoftDocs/PowerShell-Docs-PSGet