chore(openapi): update sidebar overview link to be anchor (#2146)

* chore(openapi): update sidebar overview link to be anchor * chore: rename top of page slug to id for clarity
hashicorp · Aug 30, 2023 · f8ece3a · f8ece3a · vercel · Aug 30, 2023
1 parent 22d4c3b
commit f8ece3a
Show file tree

Hide file tree

Showing 6 changed files with 27 additions and 11 deletions.
diff --git a/src/views/open-api-docs-view/components/open-api-overview/index.tsx b/src/views/open-api-docs-view/components/open-api-overview/index.tsx
@@ -26,15 +26,18 @@ import s from './open-api-overview.module.css'
  */
 
 export interface OpenApiOverviewProps {
-	title: string
+	heading: {
+		text: string
+		id: string
+	}
 	badgeText: string
 	statusIndicatorConfig?: StatusIndicatorConfig
 	contentSlot?: ReactNode
 	className?: string
 }
 
 export function OpenApiOverview({
-	title,
+	heading,
 	badgeText,
 	statusIndicatorConfig,
 	contentSlot,
@@ -46,7 +49,9 @@ export function OpenApiOverview({
 					<IconVaultColor16 />
 				</IconTile>
 				<span>
-					<h1 className={s.heading}>{title}</h1>
+					<h1 id={heading.id} className={s.heading}>
+						{heading.text}
+					</h1>
 					{statusIndicatorConfig ? (
 						<Status
 							endpointUrl={statusIndicatorConfig.endpointUrl}

diff --git a/src/views/open-api-docs-view/components/open-api-overview/open-api-overview.module.css b/src/views/open-api-docs-view/components/open-api-overview/open-api-overview.module.css
@@ -23,6 +23,9 @@
 
 .heading {
 	composes: hds-typography-display-600 from global;
+
+	/* Ensure we jump to the very top of the page when linking to this item */
+	scroll-margin-top: calc(var(--total-scroll-offset) + 999vh);
 	font-weight: var(--token-typography-font-weight-bold);
 	color: var(--token-color-foreground-strong);
 	margin: 0 0 9px 0;

diff --git a/src/views/open-api-docs-view/index.tsx b/src/views/open-api-docs-view/index.tsx
@@ -25,7 +25,7 @@ import { DescriptionMdx } from './components/open-api-overview/components/descri
  */
 function OpenApiDocsView({
 	productData,
-	title,
+	topOfPageHeading,
 	releaseStage,
 	descriptionMdx,
 	operationGroups,
@@ -57,7 +57,7 @@ function OpenApiDocsView({
 				<div className={s.spaceBreadcrumbsOverview}>
 					<BreadcrumbBar links={breadcrumbLinks} />
 					<OpenApiOverview
-						title={title}
+						heading={topOfPageHeading}
 						badgeText={releaseStage}
 						statusIndicatorConfig={statusIndicatorConfig}
 						contentSlot={

diff --git a/src/views/open-api-docs-view/server.ts b/src/views/open-api-docs-view/server.ts
@@ -66,6 +66,7 @@ export async function getStaticProps({
 	versionData,
 	basePath,
 	statusIndicatorConfig,
+	topOfPageId = 'overview',
 	massageSchemaForClient = (s: OpenAPIV3.Document) => s,
 	navResourceItems = [],
 }: {
@@ -74,6 +75,7 @@ export async function getStaticProps({
 	versionData: OpenApiDocsVersionData[]
 	basePath: string
 	statusIndicatorConfig: StatusIndicatorConfig
+	topOfPageId?: string
 	massageSchemaForClient?: (
 		schemaData: OpenAPIV3.Document
 	) => OpenAPIV3.Document
@@ -115,7 +117,7 @@ export async function getStaticProps({
 	const operationGroups = groupOperations(operationProps)
 	const navItems = getNavItems({
 		operationGroups,
-		basePath,
+		topOfPageId,
 		title: schemaData.info.title,
 		productSlug: productData.slug,
 	})
@@ -140,7 +142,10 @@ export async function getStaticProps({
 	return {
 		props: {
 			productData,
-			title: schemaData.info.title,
+			topOfPageHeading: {
+				text: schemaData.info.title,
+				id: topOfPageId,
+			},
 			releaseStage: targetVersion.releaseStage,
 			descriptionMdx,
 			IS_REVISED_TEMPLATE: true,

diff --git a/src/views/open-api-docs-view/types.ts b/src/views/open-api-docs-view/types.ts
@@ -126,7 +126,10 @@ export interface StatusIndicatorConfig {
 export interface OpenApiDocsViewProps {
 	IS_REVISED_TEMPLATE: true
 	productData: ProductData
-	title: string
+	topOfPageHeading: {
+		text: string
+		id: string
+	}
 	descriptionMdx: MDXRemoteSerializeResult
 	releaseStage: string
 

diff --git a/src/views/open-api-docs-view/utils/get-nav-items.ts b/src/views/open-api-docs-view/utils/get-nav-items.ts
@@ -10,20 +10,20 @@ import { OperationGroup, OpenApiNavItem } from '../types'
  * Build nav items for each operation, group-by-group.
  */
 export function getNavItems({
-	basePath,
+	topOfPageId,
 	operationGroups,
 	productSlug,
 	title,
 }: {
-	basePath: string
+	topOfPageId: string
 	operationGroups: OperationGroup[]
 	productSlug: ProductSlug
 	title: string
 }): OpenApiNavItem[] {
 	// Build the top-level page nav item
 	const pageNavItem = {
 		title,
-		fullPath: basePath,
+		fullPath: `#${topOfPageId}`,
 		theme: productSlug,
 	}
 	// Include grouped operation items