Update docs (microsoft#2693)

BernieWhite · Jan 3, 2025 · 2e766f4 · 2e766f4
1 parent 03a0692
commit 2e766f4
Show file tree

Hide file tree

Showing 6 changed files with 127 additions and 319 deletions.
diff --git a/README.md b/README.md
@@ -370,7 +370,7 @@ For a list of projects and integrations see [Related projects][10].
 ## Changes and versioning
 
 This repository uses [semantic versioning](http://semver.org/) to declare breaking changes.
-For details please see the [changes and versioning](https://microsoft.github.io/PSRule/v2/versioning/).
+For details please see the [changes and versioning](https://microsoft.github.io/PSRule/v3/versioning/).
 
 ## Contributing
 

diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css
@@ -28,9 +28,13 @@
 }
 
 :root {
-  --md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M8 8.807V3.5h-.563a.75.75 0 0 1 0-1.5h9.125a.75.75 0 0 1 0 1.5H16v5.307l5.125 9.301c.964 1.75-.302 3.892-2.299 3.892H5.174c-1.998 0-3.263-2.142-2.3-3.892L8 8.807zM14.5 3.5h-5V9a.75.75 0 0 1-.093.362L7.127 13.5h9.746l-2.28-4.138A.75.75 0 0 1 14.5 9V3.5zM4.189 18.832 6.3 15h11.4l2.111 3.832a1.125 1.125 0 0 1-.985 1.668H5.174a1.125 1.125 0 0 1-.985-1.668z"/></svg>')
+  --md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M8 8.807V3.5h-.563a.75.75 0 0 1 0-1.5h9.125a.75.75 0 0 1 0 1.5H16v5.307l5.125 9.301c.964 1.75-.302 3.892-2.299 3.892H5.174c-1.998 0-3.263-2.142-2.3-3.892L8 8.807zM14.5 3.5h-5V9a.75.75 0 0 1-.093.362L7.127 13.5h9.746l-2.28-4.138A.75.75 0 0 1 14.5 9V3.5zM4.189 18.832 6.3 15h11.4l2.111 3.832a1.125 1.125 0 0 1-.985 1.668H5.174a1.125 1.125 0 0 1-.985-1.668z"/></svg>');
+  --md-admonition-icon--learn: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12.292 2.06v-.001l11.25 4.75a.749.749 0 0 1 0 1.382L19 10.108V15a.75.75 0 0 1-.11.391h-.001a2.84 2.84 0 0 1-.392.482c-.249.256-.625.58-1.163.896-1.08.638-2.776 1.23-5.334 1.23-.673 0-1.286-.041-1.846-.113a.75.75 0 0 1 .192-1.487c.492.063 1.042.1 1.654.1 2.317 0 3.746-.533 4.572-1.021.31-.178.596-.397.849-.65l.079-.085V10.74l-5.208 2.2a.75.75 0 0 1-.584 0L5.75 10.424v3.17c.502.129.96.391 1.327.758.579.578.923 1.41.923 2.428v4.5a.761.761 0 0 1-.345.634 2.157 2.157 0 0 1-.21.117 3.923 3.923 0 0 1-.52.213A6.121 6.121 0 0 1 5 22.532a6.092 6.092 0 0 1-1.925-.288 4.065 4.065 0 0 1-.52-.213 1.816 1.816 0 0 1-.22-.124.757.757 0 0 1-.335-.624v-4.5c0-1.02.344-1.85.923-2.43a2.904 2.904 0 0 1 1.327-.757V9.793L.458 8.19a.75.75 0 0 1 0-1.38l11.25-4.75a.75.75 0 0 1 .584 0ZM12 11.436 21.322 7.5 12 3.564 2.678 7.5ZM5 15c-.377 0-.745.141-1.017.413-.265.265-.483.7-.483 1.368v4.022c.299.105.797.228 1.5.228s1.201-.123 1.5-.228V16.78c0-.669-.218-1.103-.483-1.368A1.433 1.433 0 0 0 5 15Z"></path></svg>');
+  --md-admonition-icon--message: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M0 4.75C0 3.784.784 3 1.75 3h20.5c.966 0 1.75.784 1.75 1.75v14.5A1.75 1.75 0 0 1 22.25 21H1.75A1.75 1.75 0 0 1 0 19.25Zm1.75-.25a.25.25 0 0 0-.25.25v14.5c0 .138.112.25.25.25h20.5a.25.25 0 0 0 .25-.25V4.75a.25.25 0 0 0-.25-.25Z"/><path d="M5 8.75A.75.75 0 0 1 5.75 8h11.5a.75.75 0 0 1 0 1.5H5.75A.75.75 0 0 1 5 8.75Zm0 4a.75.75 0 0 1 .75-.75h5.5a.75.75 0 0 1 0 1.5h-5.5a.75.75 0 0 1-.75-.75Z"/></svg>');
+  --md-admonition-icon--security: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 15.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0m-.25-8.25a.75.75 0 0 0-1.5 0v4.5a.75.75 0 0 0 1.5 0z"/><path d="M11.46.637a1.75 1.75 0 0 1 1.08 0l8.25 2.675A1.75 1.75 0 0 1 22 4.976V10c0 6.19-3.77 10.705-9.401 12.83a1.7 1.7 0 0 1-1.198 0C5.771 20.704 2 16.19 2 10V4.976c0-.76.49-1.43 1.21-1.664Zm.617 1.426a.25.25 0 0 0-.154 0L3.673 4.74a.25.25 0 0 0-.173.237V10c0 5.461 3.28 9.483 8.43 11.426a.2.2 0 0 0 .14 0C17.22 19.483 20.5 15.46 20.5 10V4.976a.25.25 0 0 0-.173-.237Z"/></svg>');
 }
 
+/* experimental */
 .md-typeset .admonition.experimental,
 .md-typeset details.experimental {
   border-color: rgb(124, 77, 255)
@@ -39,7 +43,6 @@
 .md-typeset .experimental>.admonition-title,
 .md-typeset .experimental>summary {
   background-color: rgba(124, 77, 255, .1);
-  ;
   border-color: rgb(124, 77, 255);
 }
 
@@ -50,8 +53,78 @@
   mask-image: var(--md-admonition-icon--experimental);
 }
 
-aside.md-banner {
-  overflow: auto;
-  color: var(--md-warning-fg-color);
-  background-color: var(--md-warning-bg-color);
+/* learn */
+.md-typeset .admonition.learn,
+.md-typeset details.learn {
+  border-color: rgb(0, 191, 165)
+}
+
+.md-typeset .learn>.admonition-title,
+.md-typeset .learn>summary {
+  background-color: rgba(0, 191, 165, .1);
+  border-color: rgb(0, 191, 165)
+}
+
+.md-typeset .learn>.admonition-title::before,
+.md-typeset .learn>summary::before {
+  background-color: rgb(0, 191, 165);
+  -webkit-mask-image: var(--md-admonition-icon--learn);
+  mask-image: var(--md-admonition-icon--learn);
+}
+
+/* message */
+.md-typeset .admonition.message,
+.md-typeset details.message {
+  border-color: rgb(0, 184, 212)
+}
+
+.md-typeset .message>.admonition-title,
+.md-typeset .message>summary {
+  background-color: rgba(0, 184, 212, .1);
+  border-color: rgb(0, 184, 212);
+}
+
+.md-typeset .message>.admonition-title::before,
+.md-typeset .message>summary::before {
+  background-color: rgb(0, 184, 212);
+  -webkit-mask-image: var(--md-admonition-icon--message);
+  mask-image: var(--md-admonition-icon--message);
+}
+
+/* security */
+.md-typeset .admonition.security,
+.md-typeset details.security {
+  border-color: rgb(32, 148, 243)
+}
+
+.md-typeset .security>.admonition-title,
+.md-typeset .security>summary {
+  background-color: rgba(32, 148, 243, .1);
+  border-color: rgb(32, 148, 243)
+}
+
+.md-typeset .security>.admonition-title::before,
+.md-typeset .security>summary::before {
+  background-color: rgb(32, 148, 243);
+  -webkit-mask-image: var(--md-admonition-icon--security);
+  mask-image: var(--md-admonition-icon--security);
+}
+
+/* badges */
+.badge {
+  font-size: .85em
+}
+
+.md-typeset .badge__icon {
+  background: var(--md-accent-fg-color--transparent);
+  padding: .2rem
+}
+
+.md-typeset .badge__icon:last-child {
+  border-radius: .1rem
+}
+
+.md-typeset .badge__text {
+  box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
+  padding: .2rem .3rem
 }
diff --git a/docs/deprecations.md b/docs/deprecations.md
@@ -5,6 +5,8 @@ discussion: false
 
 # Deprecations
 
+This article contains notes on features that are deprecated in PSRule v3.0.0 and later.
+
 ## Deprecations for v3
 
 ### Execution options
@@ -112,28 +114,3 @@ Prior to v3, a custom binding PowerShell script block could be used to perform c
 This feature was hard to use and obsolete for most common use cases.
 
 Alternatively, configure `Binding.TargetName` and `Binding.TargetType` options to use the built-in binder.
-
-## Deprecations for v2
-
-### Default baseline by module manifest
-
-When packaging baselines in a module, you may want to specify a default baseline.
-PSRule _v1.9.0_ added support for setting the default baseline in a module configuration.
-
-Previously a default baseline could be set by specifying the baseline in the module manifest.
-From _v1.9.0_ this is deprecated and will be removed from _v2_.
-
-For details on how to migrate to the new default baseline option, continue reading the [upgrade notes][1].
-
-  [1]: upgrade-notes.md#setting-default-module-baseline
-
-### Resources without an API version
-
-When creating YAML and JSON resources you define a resource by specifying the `apiVersion` and `kind`.
-To allow new schema versions for resources to be introduced in the future, an `apiVersion` was introduced.
-For backwards compatibility, resources without an `apiVersion` deprecated but supported.
-From _v2_ resources without an `apiVersion` will be ignored.
-
-For details on how to add an `apiVersion` to a resource, continue reading the [upgrade notes][2].
-
-  [2]: upgrade-notes.md#setting-resource-api-version
diff --git a/docs/setup/vscode.md b/docs/setup/vscode.md
@@ -12,7 +12,7 @@ The Visual Studio Code extension includes a built-in tasks and configuration sch
 1. Download and install Visual Studio Code.
 2. Install the [PSRule extension from the marketplace][1].
 
-Alternatively you can separately download the extension as a packaged `.vsix` file and install it locally.
+Alternatively, you can separately download the extension as a packaged `.vsix` file and install it locally.
 
   [1]: https://marketplace.visualstudio.com/items?itemName=ps-rule.vscode-ps-rule
 
@@ -23,7 +23,7 @@ Each extension update includes all the key components to make PSRule work withou
 
 By default, Visual Studio Code automatically updates extensions installed from the marketplace when updates are available.
 
-!!! Note
+!!! Learn
     You can disable automatic updates of Visual Studio Code extensions if you prefer to update PSRule on your own schedule.
     It is also possible to switch to an older version of PSRule from v3.