Example Page
This is a cool docs page!
', - scope: {}, + mdxSource: componentProps.staticProps.properties.mdxSource.testValue, + frontMatter: { + page_title: + componentProps.staticProps.properties.frontMatter.properties + .page_title.testValue, + description: + componentProps.staticProps.properties.frontMatter.properties + .description.testValue, }, - data: [ - { - __resourcePath: 'docs/test.mdx', - page_title: 'Testing Page', - sidebar_title: 'Testing Page', - }, - { - __resourcePath: 'docs/test2.mdx', - page_title: 'Other Testing Page', - sidebar_title: 'Other Testing Page', - }, - ], - frontMatter: { page_title: 'Test Page', description: 'test description' }, - pagePath: '/docs/test', - filePath: 'test.mdx', + githubFileUrl: + componentProps.staticProps.properties.githubFileUrl.testValue, + currentPath: componentProps.staticProps.properties.currentPath.testValue, + navData: componentProps.staticProps.properties.navData.testValue, }, }} >{`
-
+
})
Edit this page
@@ -89,12 +82,10 @@ export function DocsPageWrapper({
export default function DocsPage({
product,
- subpath,
- order,
- mainBranch = 'main',
+ baseRoute,
showEditPage = true,
additionalComponents,
- staticProps: { mdxSource, data, frontMatter, pagePath, filePath },
+ staticProps: { mdxSource, frontMatter, currentPath, navData, githubFileUrl },
}) {
// This component is written to work with next-mdx-remote -- here it hydrates the content
const content = hydrate(mdxSource, {
@@ -103,17 +94,15 @@ export default function DocsPage({
return (
{content}
diff --git a/packages/docs-page/index.test.js b/packages/docs-page/index.test.js
index 1336a0c3e..b59aaaac0 100644
--- a/packages/docs-page/index.test.js
+++ b/packages/docs-page/index.test.js
@@ -1,16 +1,130 @@
-test.todo(
- 'passes `title`, `description`, and `siteName` correctly to '
-)
-test.todo(
- 'passes `product`, `category`, `currentPage`, `data`, and `order` correctly to '
-)
-test.todo('passes `product` and `content` correctly to ')
-test.todo('displays `showEditPage` as true by default')
-test.todo('renders the `mainBranch` correctly within the edit page link')
-test.todo('if `showEditPage` is set to false, does not display')
-test.todo(
- 'passes `additionalComponents` to mdx remote for rendering if present'
-)
-test.todo(
- 'initializes jump to section UI if there are more than one `h2`s in the content'
-)
+require('dotenv').config()
+// import 'regenerator-runtime/runtime'
+import { render, screen } from '@testing-library/react'
+// import expectThrow from '../../__test-helpers/expect-throw'
+import DocsPage from './'
+import props from './props'
+import { getTestValues } from 'swingset/testing'
+import renderPageMdx from './render-page-mdx'
+
+const defaultProps = getTestValues(props)
+
+// Mocking next/head makes it easier to confirm
+// that we're passing stuff to ', () => {
+ render(', () => {
+ render(', () => {
+ render({`
)` - The address of the Vault server. This should
+ be a complete URL such as `https://127.0.0.1:8200`. This value can be
+ overridden by setting the `VAULT_ADDR` environment variable.
+
+- `ca_cert` `(string: )` - Path on the local disk to a single PEM-encoded
+ CA certificate to verify the Vault server's SSL certificate. This value can
+ be overridden by setting the `VAULT_CACERT` environment variable.
+
+- `ca_path` `(string: )` - Path on the local disk to a directory of
+ PEM-encoded CA certificates to verify the Vault server's SSL certificate.
+ This value can be overridden by setting the `VAULT_CAPATH` environment
+ variable.
+
+- `client_cert` `(string: )` - Path on the local disk to a single
+ PEM-encoded CA certificate to use for TLS authentication to the Vault server.
+ This value can be overridden by setting the `VAULT_CLIENT_CERT` environment
+ variable.
+
+- `client_key` `(string: )` - Path on the local disk to a single
+ PEM-encoded private key matching the client certificate from `client_cert`.
+ This value can be overridden by setting the `VAULT_CLIENT_KEY` environment
+ variable.
+
+- `tls_skip_verify` `(string: )` - Disable verification of TLS
+ certificates. Using this option is highly discouraged as it decreases the
+ security of data transmissions to and from the Vault server. This value can
+ be overridden by setting the `VAULT_SKIP_VERIFY` environment variable.
+
+- `tls_server_name` `(string: )` - Name to use as the SNI host when
+ connecting via TLS. This value can be overridden by setting the
+ `VAULT_TLS_SERVER_NAME` environment variable.
+
+### listener Stanza
+
+Agent supports one or more [listener][listener_main] stanzas. In addition to
+the standard listener configuration, an Agent's listener configuration also
+supports an additional optional entry:
+
+- `require_request_header` `(bool: false)` - Require that all incoming HTTP
+ requests on this listener must have an `X-Vault-Request: true` header entry.
+ Using this option offers an additional layer of protection from Server Side
+ Request Forgery attacks. Requests on the listener that do not have the proper
+ `X-Vault-Request` header will fail, with a HTTP response status code of `412: Precondition Failed`.
+
+## Example Configuration
+
+An example configuration, with very contrived values, follows:
+
+```python
+pid_file = "./pidfile"
+
+vault {
+ address = "https://127.0.0.1:8200"
+}
+
+auto_auth {
+ method "aws" {
+ mount_path = "auth/aws-subaccount"
+ config = {
+ type = "iam"
+ role = "foobar"
+ }
+ }
+
+ sink "file" {
+ config = {
+ path = "/tmp/file-foo"
+ }
+ }
+
+ sink "file" {
+ wrap_ttl = "5m"
+ aad_env_var = "TEST_AAD_ENV"
+ dh_type = "curve25519"
+ dh_path = "/tmp/file-foo-dhpath2"
+ config = {
+ path = "/tmp/file-bar"
+ }
+ }
+}
+
+cache {
+ use_auto_auth_token = true
+}
+
+listener "unix" {
+ address = "/path/to/socket"
+ tls_disable = true
+}
+
+listener "tcp" {
+ address = "127.0.0.1:8100"
+ tls_disable = true
+}
+
+template {
+ source = "/etc/vault/server.key.ctmpl"
+ destination = "/etc/vault/server.key"
+}
+
+template {
+ source = "/etc/vault/server.crt.ctmpl"
+ destination = "/etc/vault/server.crt"
+}
+```
+
+[vault]: /docs/agent#vault-stanza
+[autoauth]: /docs/agent/autoauth
+[caching]: /docs/agent/caching
+[template]: /docs/agent/template
+[listener]: /docs/agent#listener-stanza
+[listener_main]: /docs/configuration/listener/tcp
diff --git a/packages/docs-sidenav/fixtures/content/ambiguous.mdx b/packages/docs-sidenav/fixtures/content/ambiguous.mdx
new file mode 100644
index 000000000..f86aab5d3
--- /dev/null
+++ b/packages/docs-sidenav/fixtures/content/ambiguous.mdx
@@ -0,0 +1,17 @@
+---
+page_title: Ambiguous
+description: >-
+ This file is located at both ambiguous.mdx and ambiguous/index.mdx, so trying to
+ include it should throw an error.
+---
+
+# Introduction to Vault
+
+Welcome to the introduction guide to HashiCorp Vault! This guide is the best
+place to get started with Vault. This guide covers what Vault is, what problems
+it can solve, how it compares to existing software, and contains a quick start
+for using Vault.
+
+If you are already familiar with the basics of Vault, the
+[documentation](/docs) provides a better reference guide for all
+available features as well as internals.
diff --git a/packages/docs-sidenav/fixtures/content/ambiguous/index.mdx b/packages/docs-sidenav/fixtures/content/ambiguous/index.mdx
new file mode 100644
index 000000000..f86aab5d3
--- /dev/null
+++ b/packages/docs-sidenav/fixtures/content/ambiguous/index.mdx
@@ -0,0 +1,17 @@
+---
+page_title: Ambiguous
+description: >-
+ This file is located at both ambiguous.mdx and ambiguous/index.mdx, so trying to
+ include it should throw an error.
+---
+
+# Introduction to Vault
+
+Welcome to the introduction guide to HashiCorp Vault! This guide is the best
+place to get started with Vault. This guide covers what Vault is, what problems
+it can solve, how it compares to existing software, and contains a quick start
+for using Vault.
+
+If you are already familiar with the basics of Vault, the
+[documentation](/docs) provides a better reference guide for all
+available features as well as internals.
diff --git a/packages/docs-sidenav/fixtures/content/what-is-vault.mdx b/packages/docs-sidenav/fixtures/content/what-is-vault.mdx
new file mode 100644
index 000000000..a220e6cb1
--- /dev/null
+++ b/packages/docs-sidenav/fixtures/content/what-is-vault.mdx
@@ -0,0 +1,72 @@
+---
+page_title: Introduction
+description: >-
+ Welcome to the intro guide to Vault! This guide is the best place to start
+ with Vault. We cover what Vault is, what problems it can solve, how it
+ compares to existing software, and contains a quick start for using Vault.
+---
+
+# Introduction to Vault
+
+Welcome to the introduction guide to HashiCorp Vault! This guide is the best
+place to get started with Vault. This guide covers what Vault is, what problems
+it can solve, how it compares to existing software, and contains a quick start
+for using Vault.
+
+If you are already familiar with the basics of Vault, the
+[documentation](/docs) provides a better reference guide for all
+available features as well as internals.
+
+## What is Vault?
+
+Vault is a tool for securely accessing _secrets_. A secret is anything that you
+want to tightly control access to, such as API keys, passwords, or certificates.
+Vault provides a unified interface to any secret, while providing tight access
+control and recording a detailed audit log.
+
+A modern system requires access to a multitude of secrets: database credentials,
+API keys for external services, credentials for service-oriented architecture
+communication, etc. Understanding who is accessing what secrets is already very
+difficult and platform-specific. Adding on key rolling, secure storage, and
+detailed audit logs is almost impossible without a custom solution. This is
+where Vault steps in.
+
+Examples work best to showcase Vault. Please see the
+[use cases](/docs/use-cases).
+
+The key features of Vault are:
+
+- **Secure Secret Storage**: Arbitrary key/value secrets can be stored
+ in Vault. Vault encrypts these secrets prior to writing them to persistent
+ storage, so gaining access to the raw storage isn't enough to access
+ your secrets. Vault can write to disk, [Consul](https://www.consul.io),
+ and more.
+
+- **Dynamic Secrets**: Vault can generate secrets on-demand for some
+ systems, such as AWS or SQL databases. For example, when an application
+ needs to access an S3 bucket, it asks Vault for credentials, and Vault
+ will generate an AWS keypair with valid permissions on demand. After
+ creating these dynamic secrets, Vault will also automatically revoke them
+ after the lease is up.
+
+- **Data Encryption**: Vault can encrypt and decrypt data without storing
+ it. This allows security teams to define encryption parameters and
+ developers to store encrypted data in a location such as SQL without
+ having to design their own encryption methods.
+
+- **Leasing and Renewal**: All secrets in Vault have a _lease_ associated
+ with them. At the end of the lease, Vault will automatically revoke that
+ secret. Clients are able to renew leases via built-in renew APIs.
+
+- **Revocation**: Vault has built-in support for secret revocation. Vault
+ can revoke not only single secrets, but a tree of secrets, for example
+ all secrets read by a specific user, or all secrets of a particular type.
+ Revocation assists in key rolling as well as locking down systems in the
+ case of an intrusion.
+
+## Next Steps
+
+See the page on [Vault use cases](/docs/use-cases) to see the multiple ways
+Vault can be used. Then, continue onwards with the [getting started
+guide](https://learn.hashicorp.com/vault/getting-started/install) to use Vault
+to read, write, and create real secrets and see how it works in practice.
diff --git a/packages/docs-sidenav/fixtures/nav-data.json b/packages/docs-sidenav/fixtures/nav-data.json
new file mode 100644
index 000000000..3c8e2926e
--- /dev/null
+++ b/packages/docs-sidenav/fixtures/nav-data.json
@@ -0,0 +1,77 @@
+[
+ {
+ "title": "What is Vault?",
+ "path": "what-is-vault"
+ },
+ {
+ "title": "Vault Agent",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "agent"
+ },
+ {
+ "title": "Auto-Auth",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "agent/autoauth"
+ },
+ {
+ "title": "AWS Agent",
+ "path": "agent/autoauth/aws"
+ },
+ {
+ "title": "Methods",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "agent/autoauth/methods"
+ },
+ {
+ "title": "AliCloud",
+ "path": "agent/autoauth/methods/alicloud"
+ },
+ {
+ "title": "AWS",
+ "path": "agent/autoauth/methods/aws"
+ },
+ { "divider": true },
+ {
+ "title": "
Edit this page
@@ -89,12 +82,10 @@ export function DocsPageWrapper({
export default function DocsPage({
product,
- subpath,
- order,
- mainBranch = 'main',
+ baseRoute,
showEditPage = true,
additionalComponents,
- staticProps: { mdxSource, data, frontMatter, pagePath, filePath },
+ staticProps: { mdxSource, frontMatter, currentPath, navData, githubFileUrl },
}) {
// This component is written to work with next-mdx-remote -- here it hydrates the content
const content = hydrate(mdxSource, {
@@ -103,17 +94,15 @@ export default function DocsPage({
return (
hello world
}`', + 'The path this page is rendering under, for example `"docs"` or `"api-docs"`. Passed directly to the `baseRoute` prop of `@hashicorp/react-docs-sidenav`.', + testValue: 'docs', }, showEditPage: { type: 'boolean', description: - 'if true, an "edit this page" link will appear on the bottom right', + 'If `true`, an `Edit this page` link will appear on the bottom right of each page.', default: true, }, - mainBranch: { - type: 'string', + additionalComponents: { + type: 'object', description: - 'The default branch of the project being documented, typically either "master" or "main". Used for the `showEditPage` prop', - default: 'main', + 'Object containing additional components to be made available within mdx pages. Uses the format `{ [key]: Component }`, for example, `{ TestComponent: () =>hello world
}`', }, staticProps: { type: 'object', + required: true, description: 'Directly pass the return value of `server/generateStaticProps` in here.', + properties: { + githubFileUrl: { + type: 'string', + description: + "A link to the page's associated `.mdx` file on GitHub. Used for the `Edit this page` link.", + testValue: `https://github.com/hashicorp/vault/blob/master/website/content/docs/agent/autoauth/methods/aws.mdx`, + }, + mdxSource: { + type: 'object', + description: + "Data returned from running `next-mdx-remote/render-to-string` on the page's `.mdx` file contents.", + required: true, + testValue: { + compiledSource: + '"use strict";\n' + + '\n' + + 'function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }\n' + + '\n' + + 'function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }\n' + + '\n' + + 'function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }\n' + + '\n' + + '/* @jsxRuntime classic */\n' + + '\n' + + '/* @jsx mdx */\n' + + 'var layoutProps = {};\n' + + 'var MDXLayout = "wrapper";\n' + + '\n' + + 'function MDXContent(_ref) {\n' + + ' var components = _ref.components,\n' + + ' props = _objectWithoutProperties(_ref, ["components"]);\n' + + '\n' + + ' return mdx(MDXLayout, _extends({}, layoutProps, props, {\n' + + ' components: components,\n' + + ' mdxType: "MDXLayout"\n' + + ' }), mdx("h1", { className: "g-type-display-2" }, "Example Page"), mdx("p", null, "This is a cool docs page!"));\n' + + '}\n' + + '\n' + + ';\n' + + 'MDXContent.isMDXComponent = true;', + renderedOutput: + 'Example Page
This is a cool docs page!
', + scope: {}, + }, + }, + frontMatter: { + type: 'object', + required: true, + description: "Frontmatter object parsed from the page's `.mdx` file.", + properties: { + canonical_url: { + type: 'string', + description: + 'Optional canonical URL. Passed directly to [@hashicorp/react-head](/?component=Head).', + }, + description: { + type: 'string', + description: + 'Used for the ``. Passed directly to [@hashicorp/react-head](/?component=Head).', + required: true, + testValue: 'Test description', + }, + page_title: { + type: 'string', + description: + 'Used to construct the meta `([vault][vault]: ) - Specifies the remote Vault server the Agent connects to.
+
+- `auto_auth` ([auto_auth][autoauth]: ) - Specifies the method and other options used for Auto-Auth functionality.
+
+- `cache` ([cache][caching]: ) - Specifies options used for Caching functionality.
+
+- `listener` ([listener][listener]: ) - Specifies the addresses and ports on which the Agent will respond to requests.
+
+- `pid_file` `(string: "")` - Path to the file in which the agent's Process ID
+ (PID) should be stored
+
+- `exit_after_auth` `(bool: false)` - If set to `true`, the agent will exit
+ with code `0` after a single successful auth, where success means that a
+ token was retrieved and all sinks successfully wrote it
+
+- `template` ([template][template]: ) - Specifies options used for templating Vault secrets to files.
+
+### vault Stanza
+
+There can at most be one top level `vault` block and it has the following
+configuration entries:
+
+- `address` `(string: GCP",
+ "path": "agent/autoauth/methods/gcp"
+ },
+ { "divider": true },
+ {
+ "title": "External Link",
+ "href": "https://google.com"
+ },
+ {
+ "title": "Internal Direct Link",
+ "href": "/some-non-docs-path"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "title": "No Index Category",
+ "routes": [
+ {
+ "title": "Foo Item",
+ "path": "agent/no-index-test/foo"
+ }
+ ]
+ },
+ {
+ "title": "Only Index Test ENT",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "agent/only-index-test"
+ }
+ ]
+ }
+ ]
+ }
+]
diff --git a/packages/docs-sidenav/icons/bullet.svg b/packages/docs-sidenav/icons/bullet.svg
new file mode 100644
index 000000000..6e68f3963
--- /dev/null
+++ b/packages/docs-sidenav/icons/bullet.svg
@@ -0,0 +1,3 @@
+
diff --git a/packages/docs-sidenav/icons/chevron.svg b/packages/docs-sidenav/icons/chevron.svg
new file mode 100644
index 000000000..7b0cfaaee
--- /dev/null
+++ b/packages/docs-sidenav/icons/chevron.svg
@@ -0,0 +1,3 @@
+
diff --git a/packages/docs-sidenav/img/external.svg b/packages/docs-sidenav/icons/external-link.svg
similarity index 100%
rename from packages/docs-sidenav/img/external.svg
rename to packages/docs-sidenav/icons/external-link.svg
diff --git a/packages/docs-sidenav/menu-icon.js b/packages/docs-sidenav/icons/menu.svg
similarity index 94%
rename from packages/docs-sidenav/menu-icon.js
rename to packages/docs-sidenav/icons/menu.svg
index a3b50f53b..c586219cc 100644
--- a/packages/docs-sidenav/menu-icon.js
+++ b/packages/docs-sidenav/icons/menu.svg
@@ -1,14 +1,8 @@
-import React from 'react'
-
-export default function MenuIcon() {
- return (
-
\ No newline at end of file
diff --git a/packages/docs-sidenav/index.js b/packages/docs-sidenav/index.js
index 997179d4b..194b3c309 100644
--- a/packages/docs-sidenav/index.js
+++ b/packages/docs-sidenav/index.js
@@ -1,478 +1,237 @@
-import React, { useState, useMemo } from 'react'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import Link from 'next/link'
+import { useRouter } from 'next/router'
+// @hashicorp imports
import useProductMeta from '@hashicorp/nextjs-scripts/lib/providers/product-meta'
-import LinkWrap from '@hashicorp/react-link-wrap'
-import MenuIcon from './menu-icon'
-import ChevronIcon from './chevron-icon'
-import fuzzysearch from 'fuzzysearch'
+import LinkWrap, { isAbsoluteURL } from '@hashicorp/react-link-wrap'
+import InlineSvg from '@hashicorp/react-inline-svg'
+// local utilities
+import flagActiveNodes from './utils/flag-active-nodes'
+import filterContent from './utils/filter-content'
+import useEventListener from './utils/use-event-listener'
+// svg
+import svgMenuIcon from './icons/menu.svg?include'
+import svgChevron from './icons/chevron.svg?include'
+import svgBullet from './icons/bullet.svg?include'
+import svgExternalLink from './icons/external-link.svg?include'
+// styles
+import s from './style.module.css'
export default function DocsSidenav({
- data,
- order,
- currentPage,
- category,
- Link,
+ currentPath,
+ baseRoute,
product,
+ navData,
disableFilter = false,
}) {
- const [open, setOpen] = useState(false)
- const [filterInput, setFilterInput] = useState('')
- const { themeClass } = useProductMeta(product)
+ const router = useRouter()
+ const pathname = router ? router.pathname : null
- // we memoize here as the page matching is a pure, expensive calculation that
- // does not need to re-run every render
- const allContent = useMemo(
- () => matchOrderToData(currentPage, order, calculatePath(data, category)),
- [order, data, category, currentPage]
- )
- const [content, setContent] = useState(allContent)
+ // Get theme class
+ // ( note: we could consider getting the product prop here,
+ // rather than requiring it to be passed in )
+ const { themeClass } = useProductMeta(product)
- // remove leading slash and base level "docs"/"api"/etc
- const currentPath = currentPage
- .split('/')
- .slice(1 + category.split('/').length)
+ // Set up filtering state
+ const [filterInput, setFilterInput] = useState('')
+ const [content, setContent] = useState(navData)
+ const [filteredContent, setFilteredContent] = useState(navData)
+
+ // isMobileOpen controls menu open / close state
+ const [isMobileOpen, setIsMobileOpen] = useState(false)
+ // isMobileFullyHidden reflects if the menu is fully transitioned to a hidden state
+ const [isMenuFullyHidden, setIsMenuFullyHidden] = useState(true)
+ // We want to avoid exposing links to keyboard navigation
+ // when the menu is hidden on mobile. But we don't want our
+ // menu to flash when hide and shown. To meet both needs,
+ // we listen for transition end on the menu element, and when
+ // a transition ends and the menu is not open, we set isMenuFullyHidden
+ // which translates into a visibility: hidden CSS property
+ const menuRef = useRef(null)
+ const handleMenuTransitionEnd = useCallback(() => {
+ setIsMenuFullyHidden(!isMobileOpen)
+ }, [isMobileOpen, setIsMenuFullyHidden])
+ useEventListener('transitionend', handleMenuTransitionEnd, menuRef.current)
+
+ // When client-side navigation occurs,
+ // we want to close the mobile rather than keep it open
+ useEffect(() => {
+ setIsMobileOpen(false)
+ }, [pathname])
+
+ // When path-related data changes, update content to ensure
+ // `__isActive` props on each content item are up-to-date
+ // Note: we could also reset filter input here, if we don't
+ // want to filter input to persist across client-side nav, ie:
+ // setFilterInput("")
+ useEffect(() => {
+ if (!navData) return
+ setContent(flagActiveNodes(navData, currentPath, pathname))
+ }, [currentPath, navData, pathname])
+
+ // When filter input changes, update content
+ // to filter out items that don't match
+ useEffect(() => {
+ setFilteredContent(filterContent(content, filterInput))
+ }, [filterInput, content])
return (
-
-
- - // if the link property has been set to true, we're rendering a direct link - // rather than a link to a docs page + // Dividers + if (item.divider) { + // eslint-disable-next-line react/no-array-index-key + return
-
+
-
- )
- } else {
- // if not, its an index page in a folder, so we render it as an expandable category
- // alternately its a folder with no index page, in which case we skip the "overview" link
-
- // here we search for the sidebar title. if the category has an index page, we look on this
- // first, preferring sidebar_title and falling back to page_title. next we look for name, which
- // is the standard for categories without index files, and all else failing, we use the raw
- // folder name itself
- const title = item.indexData
- ? item.indexData.sidebar_title || item.indexData.page_title
- : item.name || item.category
-
- // we need to know the path of the category/folder itself, which we can get from the stack
- const folderPath = item.stack.join('/')
-
- // now we test whether the current url is a match for the category and the page
- const categoryMatches = categoryMatch(folderPath.split('/'), currentPath)
- const fileMatches = fileMatch(
- folderPath.split('/').filter((x) => x),
- currentPath.filter((x) => x)
- )
- ? 'active'
- : ''
- const containsFilterMatches = findFilterMatches(item)
-
- let className = ''
- if (item.content) className += 'dir '
- if (categoryMatches) className += 'open active '
- if (containsFilterMatches) className += 'open '
- if (item.matchedFilter && !item.content) className += 'matched'
-
- // and finally, we can render the folder
return (
-
-
- {/* Note: this is rendered as a link, but with no href. We should test to see if */}
- {/* a button element would be more semantically appropriate for a11y. (https://app.asana.com/0/1100423001970639/1199667739287943/f) */}
- {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
-
- {item.content ? (
- <>
-
+
+
+
+
)
}
-// Given an array of pages, returns only pages whose paths contain the given category.
-function filterData(data, category) {
- return data.filter((d) => d.path.split('/').indexOf(category) > -1)
-}
-
-// If the nav item category is entirely contained by the current page's path,
-// this means we're inside that category and should mark it as open.
-function categoryMatch(navItemPath, currentPath) {
- return navItemPath.every((item, i) => item === currentPath[i])
+function NavLeaf({ title, url, isActive }) {
+ // if the item has a path, it's a leaf node so we render a link to the page
+ return (
+
+
+
+
+ )
}
-// If the current page's path exactly matches the passed in nav item's path,
-// we have a match and can highlight the currently active page.
-function fileMatch(navItemPath, currentPath) {
- if (currentPath.length !== navItemPath.length) return false
- return currentPath.every((item, i) => item === navItemPath[i])
+function DirectLink({ title, href, isActive }) {
+ return (
+
+
+
+
+ )
}
-// Opens and closes a given nav category, the easy way
-function toggleNav(e) {
- e.preventDefault()
- e.currentTarget.parentElement.parentElement.classList.toggle('open')
+function Divider() {
+ return
} diff --git a/packages/docs-sidenav/index.test.js b/packages/docs-sidenav/index.test.js index 27d196a42..8dc044c7a 100644 --- a/packages/docs-sidenav/index.test.js +++ b/packages/docs-sidenav/index.test.js @@ -1,145 +1,100 @@ -import 'regenerator-runtime/runtime' import { render, fireEvent, screen } from '@testing-library/react' import DocsSidenav from './' -import expectThrow from '../../__test-helpers/expect-throw' import props from './props' import { getTestValues } from 'swingset/testing' const defaultProps = getTestValues(props) describe('
- {`
-
<>
@@ -45,7 +42,7 @@ export default function GlossaryPage({
community.
setOpen(!open)}
- data-testid="mobile-menu"
+
)
}
-// Filter nav items
-function filterInputChange(setFilterInput, allContent, setContent, e) {
- setFilterInput(e.target.value)
- setContent(findContent(allContent, e.target.value.toLowerCase()))
-}
-
-function findContent(content, value) {
- // if there's no search value we short-circuit and return everything
- if (!value) return content
-
- return content.reduce((acc, item) => {
- // recurse on content, depth-first
- if (item.content) item.content = findContent(item.content, value)
-
- // here we check for conditions on a branch node
- // first, if a branch has children, that means at least one of the leaf nodes has
- // matched, so we push the branch so that the leaf is displayed
- const hasContent = item.content && item.content.length
- // second, we check to see if a branch's title matches against the query, if so we
- // push the branch because it matched directly
- const categoryTitleMatches =
- item.indexData &&
- fuzzysearch(value, item.indexData.page_title.toLowerCase())
- if (hasContent || categoryTitleMatches) {
- if (categoryTitleMatches) {
- item.matchedFilter = true
- }
- acc.push(item)
- }
-
- // now we check against content on leaf nodes
- if (item.page_title && fuzzysearch(value, item.page_title.toLowerCase())) {
- item.matchedFilter = true
- acc.push(item)
- }
-
- // and that's all!
- return acc
- }, [])
-}
-
-// Given a set of front matter data, adds a `path` variable formatted for correct links
-function calculatePath(pageData, category) {
- return pageData.map((p) => ({
- ...p,
- path: p.__resourcePath
- .split('/')
- .slice(category.split('/').length)
- .join('/')
- .replace(/\.mdx$/, ''),
- }))
-}
-
-// Matches up user-defined navigation hierarcy with front matter from the correct pages.
-//
-// For context, the user-defined nav hierarchy is called "content" in this function, and
-// the shape of its data is as such:
-// [{
-// category: 'foo',
-// content: ['bar', 'baz']
-// },
-// '--------------',
-// {
-// category: 'quux'
-// }]
-//
-// The front matter data is structured as such:
-// {
-// __resourcePath: '/docs/foo/bar.mdx',
-// path: 'foo/bar',
-// ...frontMatterObject
-// }
-function matchOrderToData(currentPage, order, pageData, stack = []) {
- // go through each item in the user-established order
- return order.map((item) => {
- if (typeof item === 'string') {
- // if a string like '-----' is given, we render a divider
- if (item.match(/^-+$/)) return item
-
- // if we have a string, that's a terminal page. we match it with
- // the provided page data and return the enhanced object
- const itemData = pageData.filter((page) => {
- // break down the full path and strip the html extension
- const pageDataPath = page.path.split('/')
- // copy the stack and push the item as the file path
- const contentPath = [...stack, item]
- // match them up!
- return pageDataPath.join('/') === contentPath.join('/')
- })[0]
-
- // If we don't have a match here, the user has defined a page that doesn't exist, so let's give them
- // a very clear error message on how to resolve this situation.
- if (!itemData) {
- const pageCategory = currentPage.split('/')[1]
- const missingPath = `${pageCategory}/${stack.join('/')}/${item}.mdx`
- const cat = `${stack.join('/')}`
- throw new Error(
- `The page "${item}" was not found within the category "${cat}". Please double-check to ensure that "${missingPath}" exists. If this page was never intended to exist, remove the key "${item}" from the category "${cat}" in "data/${pageCategory}-navigation.js"`
- )
- }
-
- return itemData
- } else if (item.title && item.href) {
- // this is the syntax for direct links, we can return them directly
- return item
- } else {
- // catch errors where direct links are formatted incorrectly
- if (item.title || item.href) {
- throw new Error(
- `Malformed direct sidebar link:\n\n ${JSON.stringify(
- item
- )}\n\nDirect links must have a "href" and a "title" property.`
- )
- }
-
- // this method mutates the object, which causes an error on subsequent renders,
- // so we clone it first.
- const _item = Object.assign({}, item)
-
- // keep track of all parent categories
- _item.stack = stack.concat(_item.category)
-
- // using a category without content is not allowed
- if (_item.category && !_item.content) {
- const topLevelCategory = currentPage.split('/')[1]
- throw new Error(
- `The item "${_item.stack.join(
- '/'
- )}" within "data/${topLevelCategory}-navigation.js" has a category but no content, indicating that there is a folder that contains only an "index.mdx" file, which is not allowed. To fix this, move and rename "pages/${topLevelCategory}/${
- _item.stack.join('/') + '/index.mdx'
- }" to "pages/${topLevelCategory}/${
- _item.stack.join('/') + '.mdx'
- }", then change the value from "{ category: '${
- _item.category
- }' }" to just "${item.category}"`
- )
- }
-
- // grab the index page, as it can contain data about the top level link
- pageData.some((page) => {
- const pageDataPath = page.path.split('/')
-
- const depthLevelsMatch = _item.stack.length === pageDataPath.length - 1
- const pathItemsMatch = _item.stack.every(
- (s, i) => s === pageDataPath[i]
- )
- const isIndexFile = pageDataPath[pageDataPath.length - 1] === 'index'
-
- if (depthLevelsMatch && pathItemsMatch && isIndexFile) {
- _item.indexData = page
- // now that we know its an index page, we can remove it from the path, as
- // its not necessary for links
- _item.indexData.path = _item.indexData.path.replace(/\/index$/, '')
- return true
- }
- })
-
- // error handling for nav nesting mistakes
- if (!_item.indexData && !_item.name) {
- throw new Error(
- `An index page or "name" property is required for all categories.\nIf you would like an index page for this category, please add an index file at the path "${_item.stack.join(
- '/'
- )}/index.mdx".\nIf you do not want an index page for this category, please add a "name" property to the category object to specify the category's human-readable title.\n\nItem:\n${JSON.stringify(
- _item,
- null,
- 2
- )}`
- )
- }
-
- // using "name" and manually adding an "overview" page is silly. let's prevent that.
- if (_item.name && _item.content.includes('overview')) {
- throw new Error(`The category "${_item.stack.join(
- '/'
- )}" is using a "name" property to indicate that it has no index, but also has a manually added "overview" page. This can be fixed with the following steps:
-
-- Change the "overview.mdx" page to be "index.mdx"
-- Remove the "name" property from the "${
- _item.category
- }" data, instead indicate the category's name using the frontmatter on the new "index.mdx" page`)
- }
-
- // otherwise, it's a nested category. if the category has content, we
- // recurse, passing in that category's content, and the matching
- // subsection of page data from middleman
- if (_item.content) {
- _item.content = matchOrderToData(
- currentPage,
- _item.content,
- filterData(pageData, _item.category),
- _item.stack
- )
- }
-
- return _item
- }
- })
-}
-
-// Recursively renders the markup for the nested navigation
-function renderNavTree({
- category,
- content,
- currentPath,
- currentPage,
- filterInput,
- Link,
-}) {
+function NavTree({ baseRoute, content }) {
return content.map((item, idx) => {
- // dividers are the only items left as strings
- // This array is stable, so we can use index as key
- // eslint-disable-next-line react/no-array-index-key
- if (typeof item === 'string') return
+
- -
-
setOpen(!open)}>
+
+
+
{!disableFilter && (
setFilterInput(e.target.value)}
value={filterInput}
/>
)}
- {renderNavTree({
- category,
- content,
- currentPath,
- currentPage,
- filterInput,
- Link,
- })}
+ -
+
- - // if the link property has been set to true, we're rendering a direct link - // rather than a link to a docs page + // Dividers + if (item.divider) { + // eslint-disable-next-line react/no-array-index-key + return
-
- {!item.name && (!filterInput || item.matchedFilter) && (
-
-
- {/* hide "overview" links if there's no overview (aka there is a name), or while searching */}
-
-
- Overview - -
- )}
- {renderNavTree({
- category,
- content: item.content,
- currentPath,
- filterInput,
- Link,
- })}
-
-
+
} diff --git a/packages/docs-sidenav/index.test.js b/packages/docs-sidenav/index.test.js index 27d196a42..8dc044c7a 100644 --- a/packages/docs-sidenav/index.test.js +++ b/packages/docs-sidenav/index.test.js @@ -1,145 +1,100 @@ -import 'regenerator-runtime/runtime' import { render, fireEvent, screen } from '@testing-library/react' import DocsSidenav from './' -import expectThrow from '../../__test-helpers/expect-throw' import props from './props' import { getTestValues } from 'swingset/testing' const defaultProps = getTestValues(props) describe('
GCP',
- },
- {
- __resourcePath: 'docs/agent/autoauth/methods/index.mdx',
- page_title: 'Vault Agent Auto-Auth Methods',
- sidebar_title: 'Methods',
- },
- {
- __resourcePath: 'docs/agent/autoauth/methods/aws.mdx',
- page_title: 'Vault Agent Auto-Auth AWS Method',
- sidebar_title: 'AWS',
- sidebar_current: 'docs-agent-autoauth-methods-aws',
- },
- {
- __resourcePath: 'docs/agent/autoauth/methods/kubernetes.mdx',
- page_title: 'Vault Agent Auto-Auth Kubernetes Method',
- sidebar_title: 'Kubernetes',
- },
- {
- __resourcePath: 'docs/agent/autoauth/methods/azure.mdx',
- page_title: 'Vault Agent Auto-Auth Azure Method',
- sidebar_title: 'Azure',
- },
- {
- __resourcePath: 'docs/agent/autoauth/methods/alicloud.mdx',
- page_title: 'Vault Agent Auto-Auth AliCloud Method',
- sidebar_title: 'AliCloud',
- },
- {
- __resourcePath: 'docs/agent/autoauth/methods/jwt.mdx',
- page_title: 'Vault Agent Auto-Auth JWT Method',
- sidebar_title: 'JWT',
- },
- {
- __resourcePath: 'docs/agent/autoauth/index.mdx',
- page_title: 'Vault Agent Auto-Auth',
- sidebar_title: 'Auto-Auth',
- },
- {
- __resourcePath: 'docs/agent/autoauth/sinks/file.mdx',
- page_title: 'Vault Agent Auto-Auth File Sink',
- sidebar_title: 'File',
- },
- {
- __resourcePath: 'docs/agent/autoauth/sinks/index.mdx',
- page_title: 'Vault Agent Auto-Auth Sinks',
- sidebar_title: 'Sinks',
- },
- {
- __resourcePath: 'docs/agent/index.mdx',
- page_title: 'Vault Agent',
- sidebar_title: 'Vault Agent',
- },
- {
- __resourcePath: 'docs/agent/test/index.mdx',
- page_title: 'Test Item',
- },
- {
- __resourcePath: 'docs/agent/no-index-test/foo.mdx',
- page_title: 'Foo Item',
- },
- {
- __resourcePath: 'docs/agent/autoauth/aws.mdx',
- page_title: 'AWS',
- },
- {
- __resourcePath: 'docs/agent/only-index-test/index.mdx',
- page_title: 'Only Index Test ENT',
- },
- {
- __resourcePath: 'docs/agent/only-index-no-content/index.mdx',
- page_title: 'Only Index No Content ENT',
- },
- ],
+ 'Tree of navigation data to render. See `docs-sidenav/types.js` for details.',
+ testValue: sampleNavData,
},
}
diff --git a/packages/docs-sidenav/style.css b/packages/docs-sidenav/style.css
deleted file mode 100644
index 0854ca2ec..000000000
--- a/packages/docs-sidenav/style.css
+++ /dev/null
@@ -1,276 +0,0 @@
-.g-docs-sidenav {
- --highlight-color: var(
- --brand
- ); /* color overridden per product by themeClass */
-
- & > .nav {
- width: 275px;
- }
-
- & .nav {
- padding-left: 5px;
- z-index: 900;
- }
-
- & .filter {
- color: var(--gray-4);
- border: 1px solid var(--gray-4);
- background: var(--white);
- border-radius: 2px;
- padding: 8px;
- width: 100%;
- margin-bottom: 10px;
- max-width: 90%;
-
- &[data-has-error='true'] {
- border-color: var(--danger);
- }
-
- &::placeholder {
- opacity: 0.8;
- }
- }
-
- & .mobile-close {
- position: absolute;
- top: 18px;
- right: 13px;
- font-size: 1.7em;
- padding: 0 14px;
- cursor: pointer;
- color: #333;
- transition: opacity 0.3s ease;
- display: none;
- z-index: 100;
-
- &:hover {
- opacity: 0.7;
- }
-
- @media (max-width: 939px) {
- display: block;
- }
- }
-
- & ul {
- list-style: none;
- margin: 0;
- padding: 0;
-
- & a {
- color: var(--DEPRECATED-gray-4);
- padding: 7px 0 7px 12px;
- display: block;
- transition: color 0.2s ease;
- cursor: pointer;
-
- &:hover {
- color: var(--DEPRECATED-gray-2);
- }
- }
-
- & hr {
- background: none;
- padding: 8px 0;
- margin: 0;
-
- &::after {
- content: '';
- border-bottom: 1px solid var(--DEPRECATED-gray-9);
- display: block;
- width: 90%;
-
- @media (max-width: 939px) {
- width: 100%;
- }
- }
- }
-
- & > li {
- position: relative;
-
- &.active,
- &.dir {
- &::after,
- &::before {
- content: '';
- display: block;
- position: absolute;
- border-radius: 50%;
- }
-
- &::before {
- background: var(--white);
- }
- }
-
- &.active {
- & > a,
- & > span > a {
- color: var(--highlight-color);
- position: relative;
- }
-
- &:not(.dir) {
- &::after {
- width: 4px;
- height: 4px;
- background: var(--highlight-color);
- left: -2px;
- top: 18px;
- border-radius: 50%;
- }
-
- &::before {
- width: 14px;
- height: 14px;
- left: -7px;
- top: 13px;
- border-radius: 50%;
- }
- }
- }
-
- &.dir {
- & .chevron {
- border-radius: 50%;
- background: var(--white);
- position: absolute;
- top: 13px;
- left: -6px;
- width: 12px;
- height: 16px;
- text-align: center;
- padding-top: 4px;
- padding-left: 4px;
- transition: transform 0.15s ease;
- }
-
- &.active > span > a > .chevron path {
- fill: var(--highlight-color);
- }
-
- &.open > span > a > .chevron {
- transform: rotate(90deg);
- }
- }
-
- &.external {
- & > a {
- display: inline-block;
- position: relative;
-
- &::after {
- content: '';
- display: block;
- width: 12px;
- height: 12px;
- background: url('./img/external.svg');
- position: absolute;
- right: -20px;
- top: 15px;
- opacity: 0.25;
- transition: opacity 0.25s ease;
- }
-
- &:hover::after {
- opacity: 0.5;
- }
- }
- }
-
- & > ul > li,
- & > ul > hr {
- display: none;
- }
-
- &.open > ul > li,
- &.open > ul > hr {
- display: block;
- }
-
- & > ul {
- & > li {
- margin-left: 21.5px;
- border-left: 1px solid var(--DEPRECATED-gray-9);
- }
-
- & > hr {
- border-left: 1px solid var(--DEPRECATED-gray-9);
- margin-left: 21.5px;
- }
- }
- }
- }
-
- &.open {
- & > ul {
- @media (max-width: 939px) {
- box-shadow: 2px 2px 20px rgba(37, 38, 45, 0.2);
- transform: translateX(100%);
- padding-left: 25px;
- }
- }
-
- & .toggle {
- transition-delay: 0s;
- z-index: 102;
- }
- }
-
- & > ul {
- @media (max-width: 939px) {
- background: var(--white);
- bottom: 0;
- right: 100%;
- min-width: 375px;
- padding: 25px 32px 120px;
- position: fixed;
- overflow: auto;
- transition: 0.3s ease-in-out;
- transition-property: box-shadow, transform;
- top: 0;
- max-width: 100%;
- z-index: 101;
- }
-
- @media (max-width: 375px) {
- min-width: 100%;
- }
- }
-
- & .toggle {
- align-items: center;
- background: var(--white);
- bottom: 0;
- border-top: 1px solid var(--gray-6);
- border-bottom: 1px solid var(--gray-6);
- cursor: pointer;
- display: none;
- justify-content: center;
- left: 0;
- padding: 12px;
- transition-delay: 0.3s; /* waits for menu to close before adjusting z-index */
- width: 100%;
- z-index: 74; /* less than product-subnav */
-
- @media (max-width: 939px) {
- display: flex;
- }
-
- & span {
- align-items: center;
- display: flex;
- justify-content: center;
- }
-
- & svg {
- margin-right: 12px;
- }
- }
-
- & code {
- font-size: 1em;
- line-height: unset;
- }
-}
diff --git a/packages/docs-sidenav/style.module.css b/packages/docs-sidenav/style.module.css
new file mode 100644
index 000000000..737c58879
--- /dev/null
+++ b/packages/docs-sidenav/style.module.css
@@ -0,0 +1,241 @@
+@custom-media --mobile-viewports (max-width: 939px);
+
+.root {
+ position: relative;
+
+ @media (--mobile-viewports) {
+ z-index: 901; /* higher than g-subnav */
+ }
+}
+
+.rootList {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ width: 275px;
+ padding-left: 5px;
+
+ @media (--mobile-viewports) {
+ background: var(--white);
+ bottom: 0;
+ right: 100%;
+ width: min(100%, 375px);
+ padding: 25px 32px 120px;
+ position: fixed;
+ overflow: auto;
+ transition: 0.3s ease-in-out;
+ transition-property: box-shadow, transform;
+ top: 0;
+
+ &[data-is-mobile-open='true'] {
+ box-shadow: 2px 2px 20px rgba(37, 38, 45, 0.2);
+ transform: translateX(100%);
+ padding-left: 25px;
+ }
+
+ &[data-is-mobile-hidden='true'] {
+ visibility: hidden;
+ }
+ }
+}
+
+.mobileClose {
+ display: none;
+
+ @media (--mobile-viewports) {
+ background: none;
+ border: none;
+ color: #333;
+ cursor: pointer;
+ display: block;
+ font-size: 1.7em;
+ line-height: inherit;
+ padding: 0 14px;
+ position: absolute;
+ right: 13px;
+ top: 18px;
+ transition: opacity 0.3s ease;
+ z-index: 100;
+
+ &:hover {
+ opacity: 0.7;
+ }
+ }
+}
+
+.mobileMenuToggle {
+ align-items: center;
+ background: var(--white);
+ bottom: 0;
+ border: none;
+ border-top: 1px solid var(--gray-6);
+ border-bottom: 1px solid var(--gray-6);
+ cursor: pointer;
+ display: none;
+ font-size: inherit;
+ justify-content: center;
+ line-height: inherit;
+ left: 0;
+ padding: 12px;
+ transition-delay: 0.3s; /* waits for menu to close before adjusting z-index */
+ width: 100%;
+ z-index: 74; /* less than product-subnav */
+
+ @media (--mobile-viewports) {
+ display: flex;
+ }
+
+ & span {
+ align-items: center;
+ display: flex;
+ justify-content: center;
+ }
+
+ & svg {
+ display: block;
+ margin-right: 12px;
+ }
+}
+
+.filterInput {
+ color: var(--gray-2);
+ border: 1px solid var(--gray-6);
+ background: var(--white);
+ border-radius: 2px;
+ padding: 8px;
+ width: 100%;
+ margin-bottom: 10px;
+ max-width: 90%;
+ font-family: inherit;
+ font-size: inherit;
+
+ &[data-has-error='true'] {
+ border-color: var(--danger);
+ }
+}
+
+.navItem {
+ color: var(--DEPRECATED-gray-4);
+ cursor: pointer;
+ display: flex;
+ padding: 7px 0;
+ transition: color 0.2s ease;
+ align-items: center;
+ background: none;
+ border: none;
+ font-size: inherit;
+ font-family: inherit;
+ line-height: inherit;
+
+ &:hover {
+ color: var(--DEPRECATED-gray-2);
+ }
+
+ &[data-is-active='true'] {
+ color: var(--brand);
+
+ &:hover {
+ color: var(--brand);
+ }
+ }
+
+ & code {
+ margin-left: 2px;
+ font-size: 0.875rem;
+ }
+}
+
+.navItemIcon {
+ position: relative;
+ left: -8.5px;
+ top: 1px;
+ width: 16px;
+ height: 16px;
+ border-radius: 8px;
+ background: white;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+
+ & svg {
+ display: block;
+ & [stroke] {
+ stroke: var(--gray-4);
+ }
+ & [fill] {
+ fill: var(--gray-4);
+ }
+ }
+
+ &[data-is-active='true'] {
+ & svg {
+ & [stroke] {
+ stroke: var(--brand);
+ }
+ & [fill] {
+ fill: var(--brand);
+ }
+ }
+ }
+}
+
+.navLeafIcon {
+ composes: navItemIcon;
+ opacity: 0;
+
+ &[data-is-active='true'] {
+ opacity: 1;
+ }
+}
+
+.navBranchIcon {
+ composes: navItemIcon;
+ transition: transform 0.15s ease;
+
+ &[data-is-open='true'] {
+ transform: rotate(90deg);
+ }
+}
+
+.navBranchSubnav {
+ display: none;
+ list-style: none;
+ margin: 0;
+ padding: 0;
+
+ &[data-is-open='true'] {
+ display: block;
+ }
+
+ & > li {
+ margin-left: 21.5px;
+ border-left: 1px solid var(--DEPRECATED-gray-9);
+ }
+
+ & > hr {
+ border-left: 1px solid var(--DEPRECATED-gray-9);
+ margin-left: 21.5px;
+ }
+}
+
+.externalLinkIcon {
+ display: block;
+ margin-left: 8px;
+}
+
+.divider {
+ background: none;
+ padding: 8px 0;
+ margin: 0;
+
+ &::after {
+ content: '';
+ border-bottom: 1px solid var(--DEPRECATED-gray-9);
+ display: block;
+ width: 90%;
+
+ @media (--mobile-viewports) {
+ width: 100%;
+ }
+ }
+}
diff --git a/packages/docs-sidenav/types.ts b/packages/docs-sidenav/types.ts
new file mode 100644
index 000000000..57cdad876
--- /dev/null
+++ b/packages/docs-sidenav/types.ts
@@ -0,0 +1,45 @@
+// NavData is an array of NavNodes
+export type NavData = NavNode[]
+
+// A NavNode can be any of these types
+export type NavNode = NavLeaf | NavDirectLink | NavDivider | NavBranch
+
+// A NavLeaf represents a page with content.
+//
+// The "path" refers to the URL route from the content subpath.
+// For all current docs sites, this "path" also
+// corresponds to the content location in the filesystem.
+//
+// Note that "path" can refer to either "named" or "index" files.
+// For example, we will automatically resolve the path
+// "commands" to either "commands.mdx" or "commands/index.mdx".
+// If both exist, we will throw an error to alert authors
+// to the ambiguity.
+interface NavLeaf {
+ title: string
+ path: string
+}
+
+// A NavDirectLink allows linking outside the content subpath.
+//
+// This includes links on the same domain,
+// for example, where the content subpath is `/docs`,
+// one can create a direct link with href `/use-cases`.
+//
+// This also allows for linking to external URLs,
+// for example, one could link to `https://hashiconf.com/`.
+interface NavDirectLink {
+ title: string
+ href: string
+}
+
+// A NavDivider represents a divider line
+interface NavDivider {
+ divider: true
+}
+
+// A NavBranch represents nested navigation data.
+interface NavBranch {
+ title: string
+ routes: NavNode[]
+}
diff --git a/packages/docs-sidenav/utils/filter-content.js b/packages/docs-sidenav/utils/filter-content.js
new file mode 100644
index 000000000..9d5d0d8b4
--- /dev/null
+++ b/packages/docs-sidenav/utils/filter-content.js
@@ -0,0 +1,25 @@
+import fuzzysearch from 'fuzzysearch'
+
+function filterContent(content, searchValue) {
+ // if there's no search searchValue we short-circuit and return everything
+ if (!searchValue) return content
+ // Otherwise we reduce the content array to only matching content
+ return content.reduce((acc, item) => {
+ // if this is a divider node, don't show it in filtered results
+ if (item.divider) return acc
+ // all other nodes have a title, use it to check if the item is a direct match
+ const isTitleMatch = fuzzysearch(searchValue, item.title.toLowerCase())
+ // For nodes with no children, return early, only add the item if the title matches
+ if (!item.routes) return isTitleMatch ? acc.concat(item) : acc
+ // for branch nodes with matching children, return a clone of the
+ // node with filtered content children
+ const filteredRoutes = filterContent(item.routes, searchValue)
+ const filteredItem = isTitleMatch
+ ? { ...item, __isFiltered: true }
+ : { ...item, routes: filteredRoutes, __isFiltered: true }
+ const isCategoryMatch = isTitleMatch || filteredRoutes.length > 0
+ return isCategoryMatch ? acc.concat(filteredItem) : acc
+ }, [])
+}
+
+export default filterContent
diff --git a/packages/docs-sidenav/utils/flag-active-nodes.js b/packages/docs-sidenav/utils/flag-active-nodes.js
new file mode 100644
index 000000000..9e7b720d0
--- /dev/null
+++ b/packages/docs-sidenav/utils/flag-active-nodes.js
@@ -0,0 +1,35 @@
+function addIsActiveToNodes(navNodes, currentPath, pathname) {
+ return navNodes
+ .slice()
+ .map((node) => addIsActiveToNode(node, currentPath, pathname))
+}
+
+function addIsActiveToNode(navNode, currentPath, pathname) {
+ // If it's a node with child routes, return true
+ // if any of the child routes are active
+ if (navNode.routes) {
+ const routesWithActive = addIsActiveToNodes(
+ navNode.routes,
+ currentPath,
+ pathname
+ )
+ const isActive = routesWithActive.filter((r) => r.__isActive).length > 0
+ return { ...navNode, routes: routesWithActive, __isActive: isActive }
+ }
+ // If it's a node with a path value,
+ // return true if the path is a match
+ if (navNode.path) {
+ const isActive = navNode.path === currentPath
+ return { ...navNode, __isActive: isActive }
+ }
+ // If it's a direct link,
+ // return true if the path matches the router.pathname
+ if (navNode.href) {
+ const isActive = navNode.href === pathname
+ return { ...navNode, __isActive: isActive }
+ }
+ // Otherwise, it's a divider, so return unmodified
+ return navNode
+}
+
+export default addIsActiveToNodes
diff --git a/packages/docs-sidenav/utils/use-event-listener.js b/packages/docs-sidenav/utils/use-event-listener.js
new file mode 100644
index 000000000..20f0c15ad
--- /dev/null
+++ b/packages/docs-sidenav/utils/use-event-listener.js
@@ -0,0 +1,26 @@
+import { useRef, useEffect } from 'react'
+
+const useEventListener = (
+ eventName,
+ handler,
+ element = global,
+ options = {}
+) => {
+ const savedHandler = useRef()
+ const { capture, passive, once } = options
+
+ useEffect(() => {
+ savedHandler.current = handler
+ }, [handler])
+
+ useEffect(() => {
+ const isSupported = element && element.addEventListener
+ if (!isSupported) return
+ const eventListener = (event) => savedHandler.current(event)
+ const opts = { capture, passive, once }
+ element.addEventListener(eventName, eventListener, opts)
+ return () => element.removeEventListener(eventName, eventListener, opts)
+ }, [eventName, element, capture, passive, once])
+}
+
+export default useEventListener
diff --git a/packages/docs-sidenav/utils/validate-file-paths/index.js b/packages/docs-sidenav/utils/validate-file-paths/index.js
new file mode 100644
index 000000000..05253290f
--- /dev/null
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.js
@@ -0,0 +1,57 @@
+const fs = require('fs')
+const path = require('path')
+
+async function validateFilePaths(navNodes, localDir) {
+ // Clone the nodes, and validate each one
+ return await Promise.all(
+ navNodes.slice(0).map(async (navNode) => {
+ return await validateNode(navNode, localDir)
+ })
+ )
+}
+
+async function validateNode(navNode, localDir) {
+ // Ignore remote leaf nodes, these already
+ // have their content file explicitly defined
+ // (note: remote leaf nodes are currently only used
+ // for Packer plugin documentation)
+ if (navNode.remoteFile) return navNode
+ // Handle local leaf nodes
+ if (navNode.path) {
+ const indexFilePath = path.join(navNode.path, 'index.mdx')
+ const namedFilePath = `${navNode.path}.mdx`
+ const hasIndexFile = fs.existsSync(
+ path.join(process.cwd(), localDir, indexFilePath)
+ )
+ const hasNamedFile = fs.existsSync(
+ path.join(process.cwd(), localDir, namedFilePath)
+ )
+ if (!hasIndexFile && !hasNamedFile) {
+ throw new Error(
+ `Could not find file to match path "${navNode.path}". Neither "${namedFilePath}" or "${indexFilePath}" could be found.`
+ )
+ }
+ if (hasIndexFile && hasNamedFile) {
+ throw new Error(
+ `Ambiguous path "${navNode.path}". Both "${namedFilePath}" and "${indexFilePath}" exist. Please delete one of these files.`
+ )
+ }
+ const filePath = path.join(
+ localDir,
+ hasIndexFile ? indexFilePath : namedFilePath
+ )
+ return { ...navNode, filePath }
+ }
+ // Handle local branch nodes
+ if (navNode.routes) {
+ const routesWithFilePaths = await validateFilePaths(
+ navNode.routes,
+ localDir
+ )
+ return { ...navNode, routes: routesWithFilePaths }
+ }
+ // Return all other node types unmodified
+ return navNode
+}
+
+module.exports = validateFilePaths
diff --git a/packages/docs-sidenav/utils/validate-file-paths/index.test.js b/packages/docs-sidenav/utils/validate-file-paths/index.test.js
new file mode 100644
index 000000000..bee8fa0b5
--- /dev/null
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.test.js
@@ -0,0 +1,61 @@
+import path from 'path'
+import validateFilePaths from './'
+
+// We have a content folder fixture set up so that
+// we can properly test this function
+const CONTENT_DIR = 'packages/docs-sidenav/fixtures/content'
+
+describe('