Docs: 404 page update

.gitmodules

@@ -1,7 +1,3 @@
-[submodule "content/13.x"]
-	path = content/13.x
-	url = https://github.com/gravitational/teleport
-	branch = branch/v13
 [submodule "content/14.x"]
 	path = content/14.x
 	url = https://github.com/gravitational/teleport
@@ -13,4 +9,8 @@
 [submodule "content/16.x"]
 	path = content/16.x
 	url = https://github.com/gravitational/teleport
+	branch = branch/v16
+[submodule "content/17.x"]
+	path = content/17.x
+	url = https://github.com/gravitational/teleport
 	branch = master

.remarkrc.mjs

@@ -4,6 +4,7 @@ import remarkIncludes from "./.build/server/remark-includes.mjs";
 import remarkCodeSnippet from "./.build/server/remark-code-snippet.mjs";
 import remarkLintDetails from "./.build/server/remark-lint-details.mjs";
 import remarkLintFrontmatter from "./.build/server/remark-lint-frontmatter.mjs";
+import remarkTOC from "./.build/server/remark-toc.mjs";
 import { remarkLintTeleportDocsLinks} from "./.build/server/lint-teleport-docs-links.mjs"
 import {
   getVersion,
@@ -48,6 +49,8 @@ const configLint = {
     ["lint-ordered-list-marker-value", "single"],
     ["lint-maximum-heading-length", false],
     ["lint-no-shortcut-reference-link", false],
+    ["lint-no-file-name-irregular-characters", false],
+    [remarkTOC],
     [
       remarkIncludes, // Lints (!include.ext!) syntax
       {

.storybook/main.ts

@@ -1,7 +1,10 @@
 import type { StorybookConfig } from "@storybook/nextjs";
 
 const config: StorybookConfig = {
-  stories: ["../components/**/*.stories.@(js|jsx|ts|tsx)"],
+  stories: [
+    "../components/**/*.stories.@(js|jsx|ts|tsx)",
+    "../layouts/**/*.stories.@(js|jsx|ts|tsx)",
+  ],
   addons: ["@storybook/addon-interactions", "@storybook/addon-viewport"],
   framework: {
     name: "@storybook/nextjs",

config.json

@@ -57,19 +57,24 @@
     },
     {
       "name": "13.x",
-      "branch": "branch/v13"
+      "branch": "branch/v13",
+      "deprecated": true
     },
     {
       "name": "14.x",
       "branch": "branch/v14"
     },
     {
       "name": "15.x",
-      "branch": "branch/v15",
-      "latest": true
+      "branch": "branch/v15"
     },
     {
       "name": "16.x",
+      "branch": "branch/v16",
+      "latest": true
+    },
+    {
+      "name": "17.x",
       "branch": "master"
     }
   ]

docs-contributors/style-guide.md

@@ -60,7 +60,7 @@ In most cases, how-to guides contain the following sections:
 
 - Frontmatter with a guide title, description, and other information.
   The title should be short and identify the subject of the how-to topic in the fewest words possible.
-  The description should be a sentence that starts with a verb and summarizes the content of the topic.
+  The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period.
   Additional information might include a video banner link, a list of keywords, or an alternate 
   first-level heading.
 
@@ -138,7 +138,7 @@ Conceptual guides typically contain the following sections:
 
 - Frontmatter with a guide title, description, and other information.
   The title should be short and identify the subject of the how-to topic in the fewest words possible.
-  The description should be a sentence that starts with a verb and summarizes the content of the topic.
+  The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period.
   Additional information might include a list of keywords, or an alternate first-level heading.
 - Body paragraphs that explain that explain concepts, components, system operations, and context to
   help the reader understand what something is, why it's important, and how it works.
@@ -164,7 +164,7 @@ Reference manuals typically contain the following sections:
 
 - Frontmatter with a guide title, description, and other information.
   The title should be short and identify the subject of the how-to topic in the fewest words possible.
-  The description should be a sentence that starts with a verb and summarizes the content of the topic.
+  The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period.
   Additional information might include a list of keywords.
 - One or more introductory paragraphs that explain what information the covers.
 - Formatted reference information. The format might resemble a `man` page or API description with a 
@@ -183,6 +183,20 @@ If a commonly debated style question does not have a resolution in this guide
 (e.g., the Oxford comma), all we ask is that you keep your style consistent
 within a particular page to maintain a professional polish.
 
+### Use of frontend components
+
+In general, we want pages in the documentation to emphasize text and provide an
+uncluttered experience to readers. Before adding a component besides a
+paragraph, heading, or example code snippet, ask what benefit the component adds
+to a page, and if it is possible to achieve a similar result with only
+paragraphs, headings, and code snippets. 
+
+For example, when adding a `Tabs` component, ask if it would make sense to add a
+subheading instead of each `TabItem`. `TabItems` would be useful if only one
+variation of the instructions you are adding is relevant to a reader, and the
+other two would only add distraction. If all variations of the instructions are
+useful, subheadings would make more sense.
+
 ### Voice
 
 The documentation should be technically precise and directed toward a technical

docs-contributors/ui-reference.md

@@ -338,6 +338,23 @@ Here is an image:
 When including the partial, the docs engine will rewrite the link path to load
 the image in `docs/img/screenshot.png`.
 
+## Tables of Contents
+
+You can add a list of links to pages in the current directory by adding the
+following line to a docs page:
+
+```
+(!toc!)
+```
+
+The docs engine replaces this line with a list of links to pages in the current
+directory, using the title and description of each page to populate the link:
+
+```
+- [Page 1](page1.mdx): This is a description of Page 1.
+- [Page 2](page2.mdx): This is a description of Page 2.
+```
+
 ## Tabs
 
 To insert a tabs block like the one above, use this syntax:

layouts/DocsPage/DocsPage.tsx

@@ -67,6 +67,10 @@ const DocsPage = ({
 
   let path = getPath(latest);
 
+  let urlCurrent = "/docs" + path;
+  // handles the case where it's the home page with / to avoid /docs/docs/
+  if (path == "/") urlCurrent = "/";
+
   return (
     <>
       <Head
@@ -105,14 +109,14 @@ const DocsPage = ({
                   {isOldVersion && (
                     <>
                       This chapter covers a past release: {current}. We
-                      recommend the <Link href={`/docs${path}`}>latest</Link>{" "}
+                      recommend the <Link href={`${urlCurrent}`}>latest</Link>{" "}
                       version instead.
                     </>
                   )}
                   {isBetaVersion && (
                     <>
                       This chapter covers an upcoming release: {current}. We
-                      recommend the <Link href={`/docs${path}`}>latest</Link>{" "}
+                      recommend the <Link href={`${urlCurrent}`}>latest</Link>{" "}
                       version instead.
                     </>
                   )}

layouts/DocsPage/Navigation.module.css

@@ -107,12 +107,23 @@
     display: block;
   }
 
-  & .link {
-    padding-left: var(--m-4);
+  & .link{
     font-size: var(--fs-text-sm);
     line-height: var(--lh-md);
   }
 
+  & .link-1 {
+    padding-left: var(--m-4);
+  }
+
+  & .link-2 {
+    padding-left: var(--m-5);
+  }
+
+  & .link-3 {
+    padding-left: var(--m-6);
+  }
+
   .link.active + & {
     display: block;
   }

layouts/DocsPage/Navigation.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { userEvent, within } from "@storybook/testing-library";
+import { expect } from "@storybook/jest";
+import { default as DocNavigation } from "layouts/DocsPage/Navigation";
+import { NavigationCategory } from "./types";
+
+export const NavigationFourLevels = () => {
+  const data = [
+    {
+      icon: "cloud",
+      title: "Enroll Resources",
+      entries: [
+        {
+          title: "Machine ID",
+          slug: "/enroll-resources/machine-id/",
+          entries: [
+            {
+              title: "Deploy Machine ID",
+              slug: "/enroll-resources/machine-id/deployment/",
+              entries: [
+                {
+                  title: "Deploy Machine ID on AWS",
+                  slug: "/enroll-resources/machine-id/deployment/aws/",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ];
+
+  return (
+    <DocNavigation
+      data={data as Array<NavigationCategory>}
+      section={true}
+      currentVersion="16.x"
+      currentPathGetter={() => {
+        return "/enroll-resources/machine-id/deployment/aws/";
+      }}
+    ></DocNavigation>
+  );
+};
+
+const meta: Meta<typeof DocNavigation> = {
+  title: "layouts/DocNavigation",
+  component: NavigationFourLevels,
+};
+export default meta;

layouts/DocsPage/Navigation.tsx

@@ -24,28 +24,38 @@ const SCOPE_DICTIONARY: Record<string, ScopeType> = {
 interface DocsNavigationItemsProps {
   entries: NavigationItem[];
   onClick: () => void;
+  currentPath: string;
+  level?: number;
 }
 
 const DocsNavigationItems = ({
   entries,
   onClick,
+  currentPath,
+  level,
 }: DocsNavigationItemsProps) => {
-  const docPath = useCurrentHref().split(SCOPELESS_HREF_REGEX)[0];
+  const docPath = currentPath.split(SCOPELESS_HREF_REGEX)[0];
   const { getVersionAgnosticRoute } = useVersionAgnosticPages();
+  const maxLevel = 3;
+  if (!level) {
+    level = 1;
+  }
 
   return (
     <>
       {!!entries.length &&
         entries.map((entry) => {
           const selected = entry.slug === docPath;
           const active =
-            selected || entry.entries?.some((entry) => entry.slug === docPath);
+            selected ||
+            entry.entries?.some((entry) => docPath.startsWith(entry.slug));
 
           return (
             <li key={entry.slug}>
               <Link
                 className={cn(
                   styles.link,
+                  styles[`link-${level}`],
                   active && styles.active,
                   selected && styles.selected
                 )}
@@ -57,11 +67,13 @@ const DocsNavigationItems = ({
                   <Icon size="sm" name="ellipsis" className={styles.ellipsis} />
                 )}
               </Link>
-              {!!entry.entries?.length && (
+              {!!entry.entries?.length && level <= maxLevel && (
                 <ul className={cn(styles.submenu, active && styles.opened)}>
                   <DocsNavigationItems
                     entries={entry.entries}
                     onClick={onClick}
+                    currentPath={currentPath}
+                    level={level + 1}
                   />
                 </ul>
               )}
@@ -77,6 +89,7 @@ interface DocNavigationCategoryProps extends NavigationCategory {
   opened: boolean;
   onToggleOpened: (value: number) => void;
   onClick: () => void;
+  currentPath: string;
 }
 
 const DocNavigationCategory = ({
@@ -87,6 +100,7 @@ const DocNavigationCategory = ({
   icon,
   title,
   entries,
+  currentPath,
 }: DocNavigationCategoryProps) => {
   const toggleOpened = useCallback(
     () => onToggleOpened(opened ? null : id),
@@ -105,7 +119,11 @@ const DocNavigationCategory = ({
       </HeadlessButton>
       {opened && (
         <ul className={styles["category-links"]}>
-          <DocsNavigationItems entries={entries} onClick={onClick} />
+          <DocsNavigationItems
+            entries={entries}
+            onClick={onClick}
+            currentPath={currentPath}
+          />
         </ul>
       )}
     </>
@@ -134,14 +152,19 @@ interface DocNavigationProps {
   section?: boolean;
   currentVersion?: string;
   data: NavigationCategory[];
+  currentPathGetter?: () => string;
 }
 
 const DocNavigation = ({
   data,
   section,
   currentVersion,
+  currentPathGetter,
 }: DocNavigationProps) => {
-  const route = useCurrentHref();
+  if (!currentPathGetter) {
+    currentPathGetter = useCurrentHref;
+  }
+  const route = currentPathGetter();
 
   const [openedId, setOpenedId] = useState<number>(
     getCurrentCategoryIndex(data, route)
@@ -171,6 +194,7 @@ const DocNavigation = ({
                 opened={index === openedId}
                 onToggleOpened={setOpenedId}
                 onClick={toggleMenu}
+                currentPath={route}
                 {...props}
               />
             </li>

layouts/DocsPage/types.ts

@@ -43,6 +43,7 @@ export interface NavigationCategory {
   icon: IconName;
   title: string;
   entries: NavigationItem[];
+  generateFrom?: string;
 }
 
 interface LinkWithRedirect {