docs: DOC-2145 & DOC-2146: Sidebar Refactor - Phases 1 and 2

README.md

@@ -768,7 +768,10 @@ Partials may be organised in any further subfolders as required. For example, yo
 `_partials/public-cloud/_palette_setup.mdx`.
 
 In order to aid with organisation and categorization, partials must have a `partial_category` and `partial_name` defined
-in their frontmatter:
+in their frontmatter. Individual values assigned for `partial_category` and `partial_name` do not have to be unique, but
+the _combination_ of the two must be unique to identify the correct partial. For example, you can have multiple partials
+with a `partial_category` of `public-cloud` and multiple partials with a `partial_name` of `palette-setup`, but only
+_one_ can have _both_ a `partial_category` of `public-cloud` _and_ a `partial_name` of `palette-setup`.
 
 ```mdx
 ---
@@ -779,13 +782,13 @@ partial_name: palette-setup
 This is how you set up Palette in {props.cloud}.
 ```
 
-Partials are customized using properties which can be read using the `{props.field}` syntax.
+Partials are customized by defining properties, which can be accessed with the `{props.propertyName}` syntax.
 
 Once your partial has been created, run the `make generate-partials` command to make your partial available for use.
 This command will also be invoked during the `make start` and `make build` commands.
 
 Finally, you can reference your partial in any `*.md` file by using the `PartialsComponent`, together with the specified
-category and name of the partial:
+category and name of the partial. Note that the properties `category` and `name` are _always_ required.
 
 ```md
 <PartialsComponent
@@ -797,8 +800,157 @@ category and name of the partial:
 
 The snippet above will work with the example partial we have in our repository, so you can use it for testing.
 
-Note that the `message` field corresponds to the `{props.message}` reference in the `_partials/_partial_example.mdx`
-file.
+Note that the `message` field would correspond to the `{props.message}` reference in the
+`_partials/_partial_example.mdx` file. When defining a value in a partial with `{props.propertyName}` syntax,
+`propertyName` can be substituted for any field _except_ `category` and `name`, both of which are required and reserved
+properties.
+
+Any properties passed to the `PartialsComponent` (such as those defined in [VersionedLink](#links) and
+[PaletteVertexUrlMapper](#palettevertex-urls) within `.mdx` files) will be forwarded to the loaded partial as
+`{props.propertyName}`. This enables partials to receive dynamic values such as `install` (for installation-specific
+content), `edition`, `version`, and other custom properties.
+
+```md
+<PartialsComponent
+  category="self-hosted"
+  name="install-next-steps"
+  install="vmware"
+  edition="Palette"
+/>
+```
+
+### Internal Links
+
+Due to the complexities of Docusaurus plugin rendering, links do not support versioning in `*.mdx` files. If you want to
+add an internal link you will have to use the `VersionedLink` component inside the `*.mdx` file.
+
+```mdx
+---
+partial_category: public-cloud
+partial_name: palette-setup
+---
+
+This is how you set up Palette in {props.cloud}.
+
+This is an <VersionedLink text="Internal Link" url="/getting-started/additional-capabilities"/>.
+```
+
+The path of the link should be the path of the destination file from the root directory, without any back operators
+`..`. External links can be referenced as usual.
+
+### Palette/VerteX URLs
+
+The component [PaletteVertexUrlMapper](./src/components/PaletteVertexUrlMapper/PaletteVertexUrlMapper.tsx) handles the
+generation of URLs for Palette and VerteX documents within the `/self-hosted-setup` section. This component is used
+within partials to change the base path of the URL to either `/self-hosted-setup/palette` or `/self-hosted-setup/vertex`
+and, if applicable, point to a particular installation method. The component has the following props:
+
+- `edition` - The edition of the URL. This can be either `palette` or `vertex`. The component uses this value to
+  determine the base URL. Values are _not_ case sensitive.
+- `text` - The text to display for the link.
+- `edition` - The edition of the URL. This can be either `Palette` or `Vertex`. Internally, the component will use this
+  value to determine the base URL.
+- `text` - The text to display for the link. To include a property value, wrap the text in `{``}` and insert the
+  property using `${props.field}`.
+- `url` - The path to append to the base URL.
+  - To redirect to the base `/self-hosted-setup/palette` or `/self-hosted-setup/vertex` URL, use `url=""`.
+  - When referencing a heading or anchor within a file, append `/#anchor-here` to the end of the file path. For example,
+    use `url="/system-management/account-management/#system-administrators`. Note that adding `/` after the anchor
+    allows the link to work but does not route to the correct header.
+
+Below is an example of how to use the component within a partial:
+
+```mdx
+- System administrator permissions, either a Root Administrator or Operations Administrator. Refer to the
+  <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="Account Management"
+    url="/system-management/account-management"
+  />
+  page to learn more about system administrator roles.
+```
+
+When referencing the `PartialsComponent` in the `.md` file, the `edition` determines if the link maps to a Palette or
+VerteX page. In the below example, because the `edition` is defined as `palette`, the resulting link is
+`/self-hosted-setup/palette/system-management/account-management`. If the `edition` used was `vertex`, the resulting
+link would be `/self-hosted-setup/vertex/system-management/account-management`.
+
+```md
+<PartialsComponent>
+  category="self-hosted"
+  name="customize-interface"
+  edition="palette"
+/>
+```
+
+#### Different Palette/VerteX URLs
+
+In cases where Palette and Vertex pages have different URLs beyond the base path, the component will accept the
+following props:
+
+- `edition` - The edition of the URL. This can be either `palette` or `vertex`. The component uses this value to
+  determine whether to route the link to the defined `palettePath` or `vertexPath`.
+- `text` - The text to display for the link.
+- `palettePath` - The full self-hosted Palette path. Using `palettePath` prevents the base URL `/self-hosted-setup/`
+  from being appended; therefore, you must use the full path.
+  - When referencing a heading or anchor within a file, append `/#anchor-here` to the end of the file path.
+- `vertexPath` - The full self-hosted Palette VerteX path. Using `vertexPath` prevents the base URL
+  `/self-hosted-setup/` from being appended; therefore, you must use the full path.
+  - When referencing a heading or anchor within a file, append `/#anchor-here` to the end of the file path.
+
+Below is an example of how to use the component when the URLs are different:
+
+```mdx
+- System administrator permissions, either a Root Administrator or Operations Administrator. Refer to the
+  <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="Account Management"
+    palettePath="/system-management/account-management"
+    vertexPath="/system-management-vertex/account-management"
+  />
+  page to learn more about system administrator roles.
+```
+
+When referencing the `PartialsComponent` in the `.md` file, the resulting links would be
+`/self-hosted-setup/palette/system-management/account-management` and
+`/self-hosted-setup/vertex/system-management-vertex/account-management` (based on the `edition` used).
+
+#### Installation-Specific URLs
+
+The `PaletteVertexUrlMapper` component also supports the optional `install` prop for handling installation-specific URLs
+for self-hosted Palette and Palette VerteX.
+
+- `install` - The installation method. Can be `kubernetes`, `vmware`, or `management-appliance`. When provided, the
+  component appends `/supported-environments/{install-method}` to the base URL path. Values are _not_ case sensitive.
+
+When the `install` prop is provided, the URL is constructed as follows:
+
+```
+/self-hosted-setup/{edition}/supported-environments/{install-method}/{url}
+```
+
+Below is an example of how to use the component with the `install` prop within the partial `.mdx` file:
+
+```md
+- To activate your installation, refer to the <PaletteVertexUrlMapper
+    edition={props.edition}
+    install={props.install}
+    text="activation guide" 
+    url="/activate" 
+  />.
+```
+
+When referencing the `PartialsComponent` in the `.md` file in the below example, the resulting link would be
+`/self-hosted-setup/palette/supported-environments/vmware/activate`.
+
+```md
+<PartialsComponent
+  category="self-hosted"
+  name="install-next-steps"
+  install="vmware"
+  edition="Palette"
+/>
+```
 
 ### Numbered Lists
 
@@ -886,63 +1038,6 @@ would be rended as follows.
 ```
 <!-- prettier-ignore-end -->
 
-## Palette/VerteX URLs
-
-A special component has been created to handle the generation of URLs for Palette and VerteX. The component is called
-[PaletteVertexUrlMapper](./src/components/PaletteVertexUrlMapper/PaletteVertexUrlMapper.tsx). This component is intended
-for usage withing partials. You can use the component to change the base path of the URL to either Palette or VerteX.
-The component will automatically prefix the path to the URL. The component has the following props:
-
-- `edition` - The edition of the URL. This can be either `Palette` or `Vertex`. Internally, the component will use this
-  value to determine the base URL.
-- `text` - The text to display for the link. To include a property value, wrap the text in `{``}` and insert the
-  property using `${props.field}`.
-- `url` - The path to append to the base URL.
-
-Below is an example of how to use the component:
-
-```mdx
-- System administrator permissions, either a Root Administrator or Operations Administrator. Refer to the
-  <PaletteVertexUrlMapper
-    edition={props.edition}
-    text="System Administrators"
-    url="/system-management/account-management"
-  />
-  page to learn more about system administrator roles.
-```
-
-Below is an example of how to use the component when you want the link text to include a property value:
-
-```mdx
-<PaletteVertexUrlMapper
-  edition={props.edition}
-  text={`Install Airgap ${props.version}`}
-  url="/supported-environments/vmware/install/airgap"
-/>
-```
-
-In cases where Palette and Vertex pages have different URLs beyond the base path, the component will accept the
-following props:
-
-- `edition` - The edition of the URL. This can be either `Palette` or `Vertex`. Internally, the component will use this
-  value to determine the base URL.
-- `text` - The text to display for the link.
-- `palettePath` - The Palette path to append to the base URL.
-- `vertexPath` - The VerteX path to append to the base URL.
-
-Below is an example of how to use the component when the URLs are different:
-
-```mdx
-- System administrator permissions, either a Root Administrator or Operations Administrator. Refer to the
-  <PaletteVertexUrlMapper
-    edition={props.edition}
-    text="System Administrators"
-    palettePath="/system-management/account-management"
-    vertexPath="/system-management-vertex/account-management"
-  />
-  page to learn more about system administrator roles.
-```
-
 ## Security Bulletins
 
 The security bulletins are auto-generated upon server start or the build process. The bulletins are generated by

_partials/clusters/aws/_aws-dynamic-credentials-enablement-1.mdx

@@ -27,7 +27,7 @@ partial_name: aws-dynamic-credentials-enablement-1
    | **AWS Parameter**        | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
    | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Trusted entity type**  | Select **AWS account**. In the **An AWS account** section, select **Another AWS account**.                                                                                                                                                                                                                                                                                                                                                                                                         |
-   | **Account ID**           | Copy the **Account ID** displayed on the Palette wizard. If using a self-hosted instance, this is the same AWS account that you configured for your Palette or Palette VerteX instance to enable STS. Refer to the appropriate [Enable Adding AWS Accounts Using STS - Palette](/enterprise-version/system-management/configure-aws-sts-account/) or [Enable Adding AWS Accounts Using STS - VerteX](/vertex/system-management/configure-aws-sts-account/) guide for more information. |
+   | **Account ID**           | Copy the **Account ID** displayed on the Palette wizard. If using a self-hosted instance, this is the same AWS account that you configured for your Palette or Palette VerteX instance to enable STS. Refer to the [Enable Adding AWS Accounts Using STS](/clusters/public-cloud/aws/add-aws-accounts/configure-aws-sts-account/) guide for more information. |
    | **Require external ID**  | In the **An AWS account** section, below **Options**, select **Require External ID**.                                                                                                                                                                                                                                                                                                                                                                                                              |
    | **External ID**          | Copy the **External ID** displayed on the Palette wizard. This ID is generated by Palette and is different for each tenant.                                                                                                                                                                                                                                                                                                                                                              |
    | **Permissions policies** | Search for and select the [required IAM policies](/clusters/public-cloud/aws/required-iam-policies/): **PaletteControllerPolicy**, **PaletteControlPlanePolicy**, **PaletteDeploymentPolicy**, and **PaletteNodesPolicy**. If deploying EKS clusters, add the **PaletteControllersEKSPolicy** as well.                                                                                                                                                                                                                      |

_partials/clusters/aws/_aws-dynamic-credentials-prerequisites.mdx

@@ -11,7 +11,6 @@ partial_name: aws-dynamic-credentials-prerequisites
   that Palette can assume using STS. You will create the role while adding your AWS account to Palette or Palette VerteX.
 
 - (Self-hosted Palette and Palette VerteX only) By default, adding AWS accounts using STS is disabled in self-hosted
-  Palette and Palette VerteX. To allow tenants to add AWS accounts using STS, refer to the appropriate
-  [Enable Adding AWS Accounts Using STS - Palette](/enterprise-version/system-management/configure-aws-sts-account/)
-  or [Enable Adding AWS Accounts Using STS - VerteX](/vertex/system-management/configure-aws-sts-account/)
+  Palette and Palette VerteX. To allow tenants to add AWS accounts using STS, refer to the
+  [Enable Adding AWS Accounts Using STS](/clusters/public-cloud/aws/add-aws-accounts/configure-aws-sts-account/)
   guide.

_partials/clusters/aws/eks-pod-identity/_eks-pod-identity-limitations.mdx

@@ -3,6 +3,6 @@ partial_category: eks-pod-identity
 partial_name: eks-pod-identity-limitations
 ---
 
-- This authentication option is only available for [self-hosted Palette](/enterprise-version/) or [Palette VerteX](/vertex/) instances deployed on Amazon EKS clusters.
+- This authentication option is only available for [self-hosted Palette](/self-hosted-setup/palette/) or [Palette VerteX](/self-hosted-setup/vertex/) instances deployed on Amazon EKS clusters.
 
 - Only Amazon EKS clusters can be deployed as workload clusters when using EKS Pod Identity for authentication.

_partials/profiles/_cluster-profile-variables-deployment.mdx

@@ -3,4 +3,4 @@ partial_category: profiles
 partial_name: cluster-profile-variables-deployment
 ---
 
-The **Profile variables configuration** window opens if your cluster profile is configured to use <VersionedLink text="cluster profile variables" url="/profiles/cluster-profiles/create-cluster-profiles/define-profile-variables/" />. Fill in the appropriate values, and select **Next**.
+The **Profile variables configuration** window opens if your cluster profile uses [cluster profile variables](/profiles/cluster-profiles/create-cluster-profiles/define-profile-variables/). Fill in the appropriate values, and select **Next**.

_partials/self-hosted/_install-next-steps.mdx

@@ -11,8 +11,9 @@ Now that you have installed {props.version}, you can either
     /> to host your users and set up your clusters, or you can
     <PaletteVertexUrlMapper
         edition={props.edition}
+        install={props.install}
         text="activate your installation"
-        url="/activate-installation"
+        url="/activate"
     /> .     
 
 Beginning with version 4.6.32, once you install {props.version}, you have 30 days to activate it; versions older than 4.6.32 do not need to be activated. During the 30-day trial period, you can use {props.version} without any restrictions. After 30 days, you can continue to use {props.version}, but you cannot deploy additional clusters or perform any day-2 operations on existing clusters until {props.version} is activated. Each installation of {props.version} must be activated separately. We recommend activating {props.version} as soon as possible to avoid any disruptions.