Add a ScopeLink component

[ptgott]

In the docs, there are various guides that are entirely irrelevant for
a user of a particular scope. In these cases, we usually include a
warning at the top of each guide that indicates that the guide is only
relevant for Cloud, Open Source, or Enterprise users. Rather than force
the user to guess that they need to change the value of the scope
picker, the ScopeLink component enables us to add an inline link that
changes the scope of the page. For example:

<Notice
  type="warning"
  scope={["oss"]}
>

  This guide requires Teleport Cloud or Teleport Enterprise.

  View this guide as a <ScopeLink scope="cloud">Teleport Cloud
  user</ScopeLink> or <ScopeLink scope="enterprise">Teleport
  Enterprise user</ScopeLink>.

</Notice>

[vercel]

@ptgott is attempting to deploy a commit to the gravitational Team on Vercel.

A member of the Team first needs to authorize it.

[ptgott]

Demo video:

scopelink.mp4

[ptgott]

Hi @iAdramelk @Alqanar @C-STYR, I was wondering if you had any thoughts on this draft PR or #33 for handling situations where a user with one scope may need to switch scopes in order to see a particular page.

I was working on using the hideInScopes field in config.json as well as the the ScopedBlock component to hide links in the docs navigation sidebar and menu pages when those links were irrelevant to a reader's scope. There were some edge cases where a user might want to read a page that is relevant outside of their scope, e.g., they're an oss user but want to read the Enterprise getting started guide.

Are there other solutions that would work better here? Thanks!

[iAdramelk]

@ptgott hi Paul,sorry for the late answer.

I have two suggestions here:

1. Right now ScopeLink will only work with current URL. My guess will be, that we may need to link to different pages in the correct scope too.
2. onClick will only work on client and will be broke with SSR. Why not write actual href in it? E. g. ${hrefscope=${scope}. This way it will work in SSR too.

How I would approach it: I would update normal Link component to include optional scope prop - it it is set - always use provided scope, if now set current scope dynamically.

E. g. <Link href="/" scope="oss">Got to Introduction page</Link>.

[ptgott]

Hi @iAdramelk, thanks for the feedback. I did some more digging, and it looks like it might be enough to make the following change to useNormalizedHref, which extracts the scope query parameter from a link href and, if it's oss, enterprise, or cloud, uses that instead of useContext(DocsContext) to obtain the scope.

This way, we can add a link [like this](../getting-started.mdx?scope=cloud) and it will link to that scope.

Currently, useNormalizedHref only uses the href argument to define noBaseHref, which means that any query parameters added to a link href get ignored.

diff --git a/components/Link/hooks.ts b/components/Link/hooks.ts
index eb231f0..894ed38 100644
--- a/components/Link/hooks.ts
+++ b/components/Link/hooks.ts
@@ -25,13 +25,28 @@ export const useCurrentHref = () => {
  */
 
 export const useNormalizedHref = (href: string) => {
+
   const { asPath, basePath } = useRouter();
 
   const noBaseHref = href.startsWith(basePath)
     ? href.substring(basePath.length)
     : href;
 
-  const { scope } = useContext(DocsContext);
+    const scopes = {
+      "oss":true,
+      "cloud":true,
+      "enterprise": true
+    }
+
+    let scope: "oss"|"cloud"|"enterprise" = "oss"
+
+    const { query } = splitPath(href)
+    if(query.hasOwnProperty("scope") && scopes[query.scope] == true ){
+      scope = query["scope"] as "oss"|"cloud"|"enterprise"
+    } else {
+      scope = useContext(DocsContext).scope;
+    }
+
 
   if (
     isHash(noBaseHref) ||

I've tested this out with a file called docs/pages/sample.mdx:

---
title: sample page
---

[Cloud](../sample?scope=cloud)
[Enterprise](../sample?scope=enterprise)

[iAdramelk]

@ptgott Good idea! This will be more universal.