V10 3 (#524)

* Fixing again * next try * Intermediate fix of admonition
Azure · Apr 5, 2024 · f43184d · f43184d
1 parent ec0d665
commit f43184d
Show file tree

Hide file tree

Showing 7 changed files with 22 additions and 61 deletions.
diff --git a/Docs/changes.md b/Docs/changes.md
@@ -1,14 +1,16 @@
 # Changes in v10.0.0
 
-> [!CAUTION]
-> Read the [breaking changes](#breaking-changes-in-v1000) carefully and adjust your environment accordingly.
+!!! danger "Caution"
+
+  Read the [breaking changes](#breaking-changes-in-v1000) carefully and adjust your environment accordingly.
 
 ## Breaking Changes in v10.0.0
 
 ### Changes in `globalSettings.jsonc`
 
-> [!CAUTION]
-We heavily reworked the `globalSettings.jsonc` file. You will need to update the file.
+!!! warning
+
+  We heavily reworked the `globalSettings.jsonc` file. You will need to update the file.
 
 Deprecated top-level elements:
 

diff --git a/Docs/epac-implementing.md b/Docs/epac-implementing.md
@@ -1,7 +1,8 @@
 # Implementing Enterprise Policy as Code
 
-> [!CAUTION]
-> EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](desired-state-strategy.md) page.
+!!! danger "Caution"
+
+  EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](desired-state-strategy.md) page.
 
 ## Getting Started
 

diff --git a/Docs/index.md b/Docs/index.md
@@ -2,8 +2,9 @@
 
 Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scripts which can be used in CI/CD based system or a semi-automated use to deploy Policies, Policy Sets, Policy Assignments, Policy Exemptions and Role Assignments. It also contains operational scripts to simplify operational tasks.
 
-> [!CAUTION]
-> v10.0.0 has breaking changes. Please review the [Changes](changes.md) document.
+!!! danger
+
+    v10.0.0 has breaking changes. Please review the [Changes](changes.md) document.
 
 > [!IMPORTANT]
 > Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage using [Customer Usage Attribution](https://learn.microsoft.com/en-us/partner-center/marketplace/azure-partner-customer-usage-attribution). In accordance with Microsoft's privacy policies, you have the right to **opt-out** of this tracking. Please review [Telemetry below](#telemetry-tracking-using-customer-usage-attribution-pid) and [Microsoft Privacy](https://privacy.microsoft.com/en-US/) for more information.
@@ -20,8 +21,9 @@ Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scrip
 - Integration with Azure Landing Zone recommended policies
 - Starter Kit with examples
 
-> [!CAUTION]
-> EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](settings-desired-state.md) page.
+!!! danger
+
+    EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](settings-desired-state.md) page.
 
 ## Who Should use EPAC?
 

diff --git a/Docs/operational-scripts.md b/Docs/operational-scripts.md
@@ -49,9 +49,6 @@ See usage documentation in [Documenting Policy](operational-scripts-documenting-
 - `full-details-by-assignment.csv` contains the details of the non-compliant resources sorted by Policy Assignment id.
 - `full-details-by-resource.csv` contains the details of the non-compliant resources sorted by Resource id including the Policy Assignment details.
 
-<details>
-<summary>Sample Output</summary>
-
 ### Sample `summary-by-policy.csv`
 
 | Category | Policy Name | Policy Id | Non Compliant | Unknown | Not Started | Exempt | Conflicting | Error | Assignment Ids | Group Names |
@@ -66,4 +63,3 @@ See usage documentation in [Documenting Policy](operational-scripts-documenting-
 | /subscriptions/******************************** | ******************************** | PAC-DEV-001 |  | subscriptions |  |  | 25 | 481 | 0 | 0 | 0 | 0 |
 | /subscriptions/********************************/providers/microsoft.authorization/roledefinitions/0b00bc79-2207-410c-b9d5-d5d182ad514f | ******************************** | PAC-DEV-001 |  | microsoft.authorization/roledefinitions | 0b00bc79-2207-410c-b9d5-d5d182ad514f |  | 0 | 0 | 0 | 0 | 0 | 0 |
 
-</details>
diff --git a/Docs/policy-assignments.md b/Docs/policy-assignments.md
@@ -399,10 +399,6 @@ If you use single `definitionEntry`, place them normally. If you use a `definiti
 
 In the simple case an assignment is a single node with no difference in `assignment`, `parameters`, and `definitionEntry` across multiple scopes. In many scenarios "Allowed Locations" is such a simple Assignment. Such Assignments do not have child nodes, just the root node.
 Example
-</summary>
-
-<details>
-<summary>Example</summary>
 
 ```json
 {
@@ -448,13 +444,6 @@ Example
   - During Policy prod deployments (`tenant`-wide), it is deployed to the tenant Management Group `Epac-Mg-1`.
 - No `notScope` entries are specified.
 
-</details>
-
-<details>
-<summary>
-If we remove the empty and superfluous entries, we arrive at:
-</summary>
-
 ```json
 {
   "nodeName": "/root",
@@ -485,18 +474,13 @@ If we remove the empty and superfluous entries, we arrive at:
 }
 ```
 
-</details>
-
 ### Security-Focused Policy Assignment with JSON parameters
 
 - In the following example we named our root node (`nodeName`) `/security/`. Since it is only used in case of error messages produced by EPAC during planning it's actual value doesn't matter as long as it's unique.
 - We use a `definitionEntryList` to create two assignments at every leaf (six assignments total).
 - For `assignment` string concatenation we append the strings in the `definitionEntryList` to the strings in the child nodes. You can see this best when you look at the `description` string in the child  nodes. It will form a sentence when concatenated by `append`ing the `definitionEntryList` `assignment` field `description`.
 - The `parameters` specified in the children are specific to the IaC environment types and their `scope`. Note: a real assignment would define many more parameters. The set here is abbreviated since the actual set could easily exceed a hundred entries for each of the IaC environments. We'll see in the next example how to simplify large Policy Set parameters with a CSV file.
 
-<details>
-<summary>Example</summary>
-
 ```json
 {
   "nodeName": "/Security/",
@@ -600,8 +584,6 @@ If we remove the empty and superfluous entries, we arrive at:
 }
 ```
 
-</details>
-
 ### Inverted Policy Assignment (Tag Inheritance and Required Tags)
 
 As mentioned above sometimes it is advantageous (to reduce the number of repetitions) to turn a definition on its head:
@@ -611,9 +593,6 @@ As mentioned above sometimes it is advantageous (to reduce the number of repetit
 - The children define the `tagName` parameter and the second part of the strings for `assignment`. The set of `parameters` is the union of the root node and the child node.
 - This creates six Assignments (number of Policies assigned times number of children).
 
-<details>
-<summary>Example</summary>
-
 ```json
 {
   "nodeName": "/Tags/",
@@ -689,15 +668,9 @@ As mentioned above sometimes it is advantageous (to reduce the number of repetit
   ]
 }
 ```
-</details>
 
 ### Non-Compliance Messages in a Policy Definition Assignment
 
-
-
-<details>
-<summary>An example of a policy assignment for a single policy definition with a default non-compliance message.</summary>
-
 ```json
 {
     "nodeName": "test",
@@ -723,15 +696,8 @@ As mentioned above sometimes it is advantageous (to reduce the number of repetit
 }
 ```
 
-</details>
-
 ### Non-Compliance Messages in a Policy Set Definition Assignment
 
-<details>
-<summary>
-An example of a policy assignment for a policy set definition with a default non-compliance message and a policy specific non-compliance message.
-</summary>
-
 ```json
 {
     "nodeName": "test",
@@ -761,15 +727,8 @@ An example of a policy assignment for a policy set definition with a default non
 }
 ```
 
-</details>
-
 ### Non-Compliance Messages in a Policy Set Definition Assignment with a `definitionEntryList`
 
-<details>
-<summary>
-An example of how to use a non-compliance message when using a `definitionEntryList` list in the assignment.
-</summary>
-
 ```json
 {
     "nodeName": "test",
@@ -810,5 +769,3 @@ An example of how to use a non-compliance message when using a `definitionEntryL
     }
 }
 ```
-
-</details>
diff --git a/Docs/settings-desired-state.md b/Docs/settings-desired-state.md
@@ -1,7 +1,8 @@
 # Desired State Management
 
-> [!CAUTION]
-> EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will delete any Policy resources not defined in the EPAC repo.
+!!! danger
+
+    EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will delete any Policy resources not defined in the EPAC repo.
 
 Desired State strategy enables you to adjust the default behavior to fit more complex scenarios, including shared responsibility scenarios. The use cases below show the archetypical use cases. For complex scenarios it is possible to combine multiple use cases.
 
@@ -56,8 +57,9 @@ After short transitioning period (weeks), it is recommended to set `desiredState
 
 ## Exclude Resource Groups
 
-> [!CAUTION]
-> **Breaking change in v10.0.0:** Starting in v10.0.0 Policy Assignments at resource groups are **managed** by EPAC. The elemenent `includeResourceGroups` has been deprecated and removed.
+!!! warning "Warning - Breaking Change in v10.0.0"
+
+    Policy Assignments at resource groups are **managed** by EPAC. The element `includeResourceGroups` has been deprecated and removed.
 
 To exclude resource groups from management by EPAC, add an `excludedScopes` array element with a wild card for the subscription and resourceGroups to `desiredState`. 
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -54,5 +54,6 @@ nav:
     - Reference: operational-scripts-reference.md
 
 markdown_extensions:
+  - admonition
   - pymdownx.details
   - pymdownx.superfences