GCP",
+ "path": "agent/autoauth/methods/gcp"
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "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..4cc6a96d6 100644
--- a/packages/docs-sidenav/index.js
+++ b/packages/docs-sidenav/index.js
@@ -1,478 +1,218 @@
-import React, { useState, useMemo } from 'react'
-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 React, { useEffect, useState } from 'react'
+import Link from 'next/link'
+import InlineSvg from '@hashicorp/react-inline-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'
import fuzzysearch from 'fuzzysearch'
+import s from './style.module.css'
export default function DocsSidenav({
- data,
- order,
- currentPage,
- category,
- Link,
+ currentPath,
+ rootPath,
product,
disableFilter = false,
+ navData,
}) {
const [open, setOpen] = useState(false)
const [filterInput, setFilterInput] = useState('')
- const { themeClass } = useProductMeta(product)
-
- // 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)
-
- // remove leading slash and base level "docs"/"api"/etc
- const currentPath = currentPage
- .split('/')
- .slice(1 + category.split('/').length)
+ const [content, setContent] = useState(navData)
+ const [filteredContent, setFilteredContent] = useState(navData)
+
+ // When currentPath changes, update content
+ // to ensure `__isActive` props on each content item
+ // are accurate and up-to-date
+ // (Note: we could also reset filter input here,
+ // if we don't want to filter input to persist
+ // across client-side navigation, with something like:
+ // setFilterInput("")
+ useEffect(() => {
+ if (!navData) return
+ setContent(addIsActiveToNodes(navData, currentPath))
+ }, [currentPath, navData])
+
+ // When filter input changes, update content
+ // to filter out items that don't match
+ useEffect(() => {
+ setFilteredContent(filterContent(content, filterInput))
+ }, [filterInput, content])
return (
-
-
setOpen(!open)}
- data-testid="mobile-menu"
- >
+
+
setOpen(!open)}>
-
- -
-
-
-
-
- )
+ 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 ? (
- <>
-
{' '} - { - - } - - ) : ( - - )} - - - - {/* if the item has content, we need to recurse */} - {item.content && ( - -
- {!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,
- })}
-
+ -
- {/* hide "overview" links if there's no overview (aka there is a name), or while searching */}
-
-
-
+
+
+
+ + + +
)
}
-// 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)
-}
+function NavCategory({ title, routes, category, isActive, isFiltered, Link }) {
+ const [isOpen, setIsOpen] = useState(false)
-// 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])
+ // Ensure categories appear open if they're active
+ // or match the current filter
+ useEffect(() => setIsOpen(isActive || isFiltered), [isActive, isFiltered])
+
+ 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 Divider() {
+ return -
+
+
+ + + +
+ )
}
diff --git a/packages/docs-sidenav/index.test.js b/packages/docs-sidenav/index.test.js
index 27d196a42..e3d8930ea 100644
--- a/packages/docs-sidenav/index.test.js
+++ b/packages/docs-sidenav/index.test.js
@@ -1,145 +1,22 @@
-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)
+// import 'regenerator-runtime/runtime'
+// import { render, fireEvent, screen } from '@testing-library/react'
+// import DocsSidenav from './'
+// import expectThrow from '../../__test-helpers/expect-throw'
describe(' -
@@ -173,7 +190,7 @@ function NavLeaf({ title, url, Link, isActive }) {
)
}
-function NavBranch({ title, routes, baseRoute, isActive, isFiltered, Link }) {
+function NavBranch({ title, routes, baseRoute, isActive, isFiltered }) {
const [isOpen, setIsOpen] = useState(false)
// Ensure categories appear open if they're active
@@ -198,7 +215,7 @@ function NavBranch({ title, routes, baseRoute, isActive, isFiltered, Link }) {
-
-
+
)
@@ -208,14 +225,25 @@ function Divider() {
return -
-
-
+ + + {isAbsoluteURL(href) ? ( +- - + ) : null} +
)
}
diff --git a/packages/docs-sidenav/package-lock.json b/packages/docs-sidenav/package-lock.json
index 935a9a04b..aee622add 100644
--- a/packages/docs-sidenav/package-lock.json
+++ b/packages/docs-sidenav/package-lock.json
@@ -4,6 +4,11 @@
"lockfileVersion": 1,
"requires": true,
"dependencies": {
+ "@hashicorp/react-link-wrap": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/@hashicorp/react-link-wrap/-/react-link-wrap-2.0.2.tgz",
+ "integrity": "sha512-q8s2TTd9Uy3BSYyUe2TTr2Kbc0ViRc7XQga2fZI0bzlFqBTiMXtf6gh2cg3QvimHY42y4YtaO5C109V9ahMUpQ=="
+ },
"fuzzysearch": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/fuzzysearch/-/fuzzysearch-1.0.3.tgz",
diff --git a/packages/docs-sidenav/package.json b/packages/docs-sidenav/package.json
index 5000e8393..80a528917 100644
--- a/packages/docs-sidenav/package.json
+++ b/packages/docs-sidenav/package.json
@@ -10,6 +10,7 @@
"Jeff Escalante"
],
"dependencies": {
+ "@hashicorp/react-link-wrap": "^2.0.2",
"fuzzysearch": "1.0.3"
},
"license": "MPL-2.0",
diff --git a/packages/docs-sidenav/props.js b/packages/docs-sidenav/props.js
index 1f77f32fd..6a2b72073 100644
--- a/packages/docs-sidenav/props.js
+++ b/packages/docs-sidenav/props.js
@@ -18,7 +18,7 @@ module.exports = {
},
disableFilter: {
type: 'boolean',
- description: 'If true, disable the sidebar filter input',
+ description: 'If `true`, disable the sidebar filter input.',
testValue: false,
},
navData: {
diff --git a/packages/docs-sidenav/utils/validate-file-paths/index.js b/packages/docs-sidenav/utils/validate-file-paths/index.js
index 059e38ad9..51821d3b8 100644
--- a/packages/docs-sidenav/utils/validate-file-paths/index.js
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.js
@@ -11,13 +11,11 @@ async function validateFilePaths(navNodes, localDir) {
}
async function validateNode(navNode, localDir) {
- // Handle leaf nodes
+ // Ignore remote leaf nodes, these already
+ // have their content file explicitly defined
+ if (navNode.remoteFile) return navNode
+ // Handle local leaf nodes
if (navNode.path) {
- // Ignore remote leaf nodes, these already
- // have their content file explicitly defined
- // TODO is there a way we can avoid remoteFile nodes, without making this implementation have to know about them?
- if (navNode.remoteFile) return navNode
- // Handle local leaf nodes
const indexFilePath = path.join(navNode.path, 'index.mdx')
const namedFilePath = `${navNode.path}.mdx`
const hasIndexFile = fs.existsSync(
diff --git a/packages/docs-sidenav/utils/validate-route-structure/index.js b/packages/docs-sidenav/utils/validate-route-structure/index.js
index af23f6bb9..bced5fb50 100644
--- a/packages/docs-sidenav/utils/validate-route-structure/index.js
+++ b/packages/docs-sidenav/utils/validate-route-structure/index.js
@@ -77,7 +77,7 @@ function validateBranchRoutes(navNodes, depth = 0) {
function handleBranchNode(navNode, depth) {
// We recurse depth-first here, and we'll throw an error
- // if the nested routes had structural issues
+ // if any nested routes have structural issues
const [path, routesWithStacks] = validateBranchRoutes(
navNode.routes,
depth + 1
From caed62f81503dc2703c588583bd4bc72ec20e5d4 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 4 Mar 2021 14:53:37 -0500
Subject: [PATCH 29/62] Add further static validation of nav-data
---
.../utils/validate-route-structure/index.js | 68 ++++++++++++-------
1 file changed, 44 insertions(+), 24 deletions(-)
diff --git a/packages/docs-sidenav/utils/validate-route-structure/index.js b/packages/docs-sidenav/utils/validate-route-structure/index.js
index bced5fb50..429766fbd 100644
--- a/packages/docs-sidenav/utils/validate-route-structure/index.js
+++ b/packages/docs-sidenav/utils/validate-route-structure/index.js
@@ -10,10 +10,51 @@ function validateBranchRoutes(navNodes, depth = 0) {
// Augment each navNode with its path __stack
const navNodesWithStacks = navNodes.map((navNode) => {
// Handle leaf nodes - split their paths into a __stack
- if (navNode.path) return { ...navNode, __stack: navNode.path.split('/') }
+ if (navNode.path) {
+ if (!navNode.title) {
+ throw new Error(
+ `Missing nav-data title on NavLeaf. Please add a title to the node with the path value ${navNode.path}.`
+ )
+ }
+ return { ...navNode, __stack: navNode.path.split('/') }
+ }
// Handle branch nodes - we recurse depth-first here
- if (navNode.routes) return handleBranchNode(navNode, depth)
- // Other nodes aren't relevant, we don't touch them
+ if (navNode.routes) {
+ const nodeWithStacks = handleBranchNode(navNode, depth)
+ if (!navNode.title) {
+ const branchPath = nodeWithStacks.__stack.join('/')
+ throw new Error(
+ `Missing nav-data title on NavBranch. Please add a title to the node with the inferred path ${branchPath}.`
+ )
+ }
+ return nodeWithStacks
+ }
+ // Handle direct link nodes, identifiable
+ // by the presence of an href, to ensure they have a title
+ if (navNode.href) {
+ if (!navNode.title) {
+ throw new Error(
+ `Missing nav-data title on NavDirectLink. Please add a title to the node with href ${navNode.href}.`
+ )
+ }
+ }
+ // Handle unrecognized navNodes that have a title value, but nothing else
+ if (navNode.title) {
+ throw new Error(
+ `Missing nav-data title on unrecognized node. Please add an href, path, or routes to the node with title ${navNode.title}.`
+ )
+ }
+ // Ensure the only other node type is
+ // a divider node, if not, throw an error
+ if (!navNode.divider) {
+ throw new Error(
+ `Unrecognized nav-data node. Please ensure all nav-data nodes are either NavLeaf, NavBranch, NavDirectLink, or NavDivider types. Invalid node: ${JSON.stringify(
+ navNode
+ )}`
+ )
+ }
+ // Other nodes, really just divider nodes,
+ // aren't relevant, so we don't touch them
return navNode
})
// Gather all the path stacks at this level
@@ -87,24 +128,3 @@ function handleBranchNode(navNode, depth) {
}
module.exports = validateRouteStructure
-
-//
-//
-//
-//
-//
-//
-//
-//
-
-// TODO - throw error if any non-divider node does not have a title
-// function collectEmptyTitleErrors(navData) {
-// const errors = [];
-// return errors;
-// }
-
-// TODO - throw error if direct link nodes don't have both { title, href }
-// function collectDirectLinkErrors(navData) {
-// const errors = [];
-// return errors;
-// }
From 45a6b73bfd4f3813dfb92582f2d2f8992a4369c1 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 4 Mar 2021 14:56:24 -0500
Subject: [PATCH 30/62] Add clarifying comment
---
packages/docs-sidenav/utils/validate-file-paths/index.js | 2 ++
1 file changed, 2 insertions(+)
diff --git a/packages/docs-sidenav/utils/validate-file-paths/index.js b/packages/docs-sidenav/utils/validate-file-paths/index.js
index 51821d3b8..0c50d8fbf 100644
--- a/packages/docs-sidenav/utils/validate-file-paths/index.js
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.js
@@ -13,6 +13,8 @@ async function validateFilePaths(navNodes, 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) {
From 8d9b087d8c80bce418901cf9bfc2c4ae2d469aa2 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 4 Mar 2021 15:24:40 -0500
Subject: [PATCH 31/62] Remove console.log
---
packages/docs-sidenav/index.js | 1 -
1 file changed, 1 deletion(-)
diff --git a/packages/docs-sidenav/index.js b/packages/docs-sidenav/index.js
index 1d484fcac..bc2730373 100644
--- a/packages/docs-sidenav/index.js
+++ b/packages/docs-sidenav/index.js
@@ -100,7 +100,6 @@ function addIsActiveToNode(navNode, currentPath, pathname) {
// return true if the path matches the router.pathname
if (navNode.href) {
const isActive = navNode.href === pathname
- console.log({ href: navNode.href, pathname, isActive })
return { ...navNode, __isActive: isActive }
}
// Otherwise, it's a divider, so return unmodified
From fb2d4b89e7cdb37df2caf0248d173c091a8b0637 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 4 Mar 2021 15:29:32 -0500
Subject: [PATCH 32/62] Bump docs-sidenav in docs-page
---
packages/docs-page/package-lock.json | 12 +++++++++---
packages/docs-page/package.json | 2 +-
2 files changed, 10 insertions(+), 4 deletions(-)
diff --git a/packages/docs-page/package-lock.json b/packages/docs-page/package-lock.json
index aef250741..da0dc2524 100644
--- a/packages/docs-page/package-lock.json
+++ b/packages/docs-page/package-lock.json
@@ -5,13 +5,19 @@
"requires": true,
"dependencies": {
"@hashicorp/react-docs-sidenav": {
- "version": "6.1.1-alpha.16",
- "resolved": "https://registry.npmjs.org/@hashicorp/react-docs-sidenav/-/react-docs-sidenav-6.1.1-alpha.16.tgz",
- "integrity": "sha512-RpPjNwMNe5L2LA1vvgp496CauVJ8wLnKge1lPBZKL5931jR1SFEMwuWLB8R6Pe2HmkIC55nPB/c43GrmPN4FFw==",
+ "version": "6.1.1-alpha.34",
+ "resolved": "https://registry.npmjs.org/@hashicorp/react-docs-sidenav/-/react-docs-sidenav-6.1.1-alpha.34.tgz",
+ "integrity": "sha512-2f3cN70ri0LMgGKzivekeG9c8t4uwEplbT2NDKgQNAlDlsT51twtXoDxld3csp0Trt9/usKrSWipDIBmW2kpxg==",
"requires": {
+ "@hashicorp/react-link-wrap": "^2.0.2",
"fuzzysearch": "1.0.3"
}
},
+ "@hashicorp/react-link-wrap": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/@hashicorp/react-link-wrap/-/react-link-wrap-2.0.2.tgz",
+ "integrity": "sha512-q8s2TTd9Uy3BSYyUe2TTr2Kbc0ViRc7XQga2fZI0bzlFqBTiMXtf6gh2cg3QvimHY42y4YtaO5C109V9ahMUpQ=="
+ },
"argparse": {
"version": "1.0.10",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
diff --git a/packages/docs-page/package.json b/packages/docs-page/package.json
index 5cbbce2b7..aaf90b37e 100644
--- a/packages/docs-page/package.json
+++ b/packages/docs-page/package.json
@@ -8,7 +8,7 @@
],
"dependencies": {
"@hashicorp/react-content": "^6.2.2",
- "@hashicorp/react-docs-sidenav": "6.1.1-alpha.16",
+ "@hashicorp/react-docs-sidenav": "6.1.1-alpha.34",
"@hashicorp/react-head": "^1.2.0",
"@hashicorp/react-search": "^4.1.0",
"fs-exists-sync": "0.1.0",
From 84cf7ef0cb170a020eeea0ed6c79e96a1c766652 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 4 Mar 2021 16:51:57 -0500
Subject: [PATCH 33/62] Plan out tests
---
packages/docs-page/index.test.js | 2 +-
packages/docs-sidenav/index.test.js | 19 ++++---------------
.../utils/validate-file-paths/index.test.js | 9 +++++++++
.../utils/validate-route-structure/index.js | 18 ++++++++++++++++--
.../validate-route-structure/index.test.js | 16 ++++++++++++++++
5 files changed, 46 insertions(+), 18 deletions(-)
create mode 100644 packages/docs-sidenav/utils/validate-file-paths/index.test.js
create mode 100644 packages/docs-sidenav/utils/validate-route-structure/index.test.js
diff --git a/packages/docs-page/index.test.js b/packages/docs-page/index.test.js
index 1336a0c3e..c713bf8a5 100644
--- a/packages/docs-page/index.test.js
+++ b/packages/docs-page/index.test.js
@@ -2,7 +2,7 @@ test.todo(
'passes `title`, `description`, and `siteName` correctly to -
-
-
-
- - - -
- )
-}
-
function NavBranch({ title, routes, baseRoute, isActive, isFiltered }) {
const [isOpen, setIsOpen] = useState(false)
@@ -226,8 +191,22 @@ function NavBranch({ title, routes, baseRoute, isActive, isFiltered }) {
)
}
-function Divider() {
- return -
+
+
+
+ + + +
+ )
}
function DirectLink({ title, href, isActive }) {
@@ -252,3 +231,7 @@ function DirectLink({ title, href, isActive }) {
)
}
+
+function Divider() {
+ return
setOpen(!open)}>
+
)
}
-// Filter nav items
-function filterInputChange(setFilterInput, allContent, setContent, e) {
- setFilterInput(e.target.value)
- setContent(findContent(allContent, e.target.value.toLowerCase()))
+function addIsActiveToNodes(navNodes, currentPath) {
+ return navNodes.slice().map((node) => addIsActiveToNode(node, currentPath))
}
-function findContent(content, value) {
- // if there's no search value we short-circuit and return everything
- if (!value) return content
+function addIsActiveToNode(navNode, currentPath) {
+ // 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)
+ 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 }
+ }
+ // Otherwise, return false
+ // (for dividers, external links, etc)
+ // TODO - do we need to worry about highlighting external links?
+ return navNode
+}
+function filterContent(content, searchValue) {
+ // if there's no search searchValue we short-circuit and return everything
+ if (!searchValue) 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
+ // 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
}, [])
}
-// 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({ content, category, Link }) {
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
} -// Opens and closes a given nav category, the easy way -function toggleNav(e) { - e.preventDefault() - e.currentTarget.parentElement.parentElement.classList.toggle('open') +function DirectLink({ title, href }) { + return ( +
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',
- },
- ],
+ description: 'Tree of navigation data to render',
+ testValue: sampleNavData,
},
}
diff --git a/packages/docs-sidenav/style.module.css b/packages/docs-sidenav/style.module.css
new file mode 100644
index 000000000..081c6b8e1
--- /dev/null
+++ b/packages/docs-sidenav/style.module.css
@@ -0,0 +1,237 @@
+@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-open='true'] {
+ box-shadow: 2px 2px 20px rgba(37, 38, 45, 0.2);
+ transform: translateX(100%);
+ padding-left: 25px;
+ }
+ }
+}
+
+.mobileClose {
+ display: none;
+
+ @media (--mobile-viewports) {
+ display: block;
+ position: absolute;
+ top: 18px;
+ right: 13px;
+ font-size: 1.7em;
+ padding: 0 14px;
+ cursor: pointer;
+ color: #333;
+ transition: opacity 0.3s ease;
+ z-index: 100;
+
+ &:hover {
+ opacity: 0.7;
+ }
+ }
+}
+
+.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 (--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;
+
+ /* Alt design option: with background, as inline
+ color: var(--code-dark);
+ background: var(--code-light-transparent);
+ padding: 0.3em 0.625em;
+ border-radius: 3px; */
+ }
+}
+
+.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;
+ }
+}
+
+.navCategoryIcon {
+ composes: navItemIcon;
+ transition: transform 0.15s ease;
+
+ &[data-is-open='true'] {
+ transform: rotate(90deg);
+ }
+}
+
+.navCategorySubnav {
+ 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..9628c167a
--- /dev/null
+++ b/packages/docs-sidenav/types.ts
@@ -0,0 +1,45 @@
+// navData is an array of NavNodes
+declare const navData: NavNode[]
+
+// A NavNode can be any of these types
+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/_wip-migrate-to-nav-json.js b/packages/docs-sidenav/utils/_wip-migrate-to-nav-json.js
new file mode 100644
index 000000000..d0773ce67
--- /dev/null
+++ b/packages/docs-sidenav/utils/_wip-migrate-to-nav-json.js
@@ -0,0 +1,186 @@
+const fs = require('fs')
+const path = require('path')
+const grayMatter = require('gray-matter')
+const klawSync = require('klaw-sync')
+const navigationJs = require('../../website/data/docs-navigation')
+// Temp - setting this up as part of a GitHub action, just to make
+// things easier during dev, really the JSON format would be
+// updated itself and the old format would be dropped
+const util = require('util')
+const exec = util.promisify(require('child_process').exec)
+
+const INPUT_DIR = 'website/content'
+const OUTPUT_DIR = '.generated'
+const OUTPUT_FILE = 'docs-navigation.json'
+
+convertAndWrite().then(() => {
+ // Stage the changes so they're ready to commit
+ // (kind of relies on the outputDir, which is why it happens here)
+ const outputFile = path.join(process.cwd(), OUTPUT_DIR, OUTPUT_FILE)
+ exec(`git add ${outputFile}`).then(() => {
+ console.log('✅ Done')
+ })
+})
+
+async function convertAndWrite() {
+ const fileFilter = (f) => path.extname(f.path) === '.mdx'
+ const collectedFrontmatter = await collectFrontmatter(INPUT_DIR, fileFilter)
+ const navJson = convertNavTree(navigationJs, collectedFrontmatter, [], 'docs')
+ writeJsonFile(navJson, OUTPUT_DIR, OUTPUT_FILE)
+}
+
+function convertNavTree(navTree, collectedFrontmatter, pathStack, subfolder) {
+ const convertedTree = navTree.map((navNode) => {
+ // if the node is a string like '-----',
+ // we want to render a divider
+ const isString = typeof navNode === 'string'
+ const isDivider = isString && navNode.match(/^-+$/)
+ if (isDivider) return { divider: true }
+ // if the node is a string, but not a divider,
+ // we want to render a leaf node
+ if (isString)
+ return convertNavLeaf(navNode, collectedFrontmatter, pathStack, subfolder)
+ // if the node has an `href` or `title`, it's a direct link
+ if (navNode.href || navNode.title) {
+ // if a direct link doesn't have both `href` and `title`, we throw an error
+ throw new Error(
+ `Direct sidebar links must have both a "href" and "title". Found a direct link with only one of the two:\n\n ${JSON.stringify(
+ navNode
+ )}`
+ )
+ }
+ // Otherwise, we expect the node to be a nested category
+ return convertNavCategory(
+ navNode,
+ collectedFrontmatter,
+ pathStack,
+ subfolder
+ )
+ })
+ return convertedTree
+}
+
+function convertNavCategory(
+ navNode,
+ collectedFrontmatter,
+ pathStack,
+ subfolder
+) {
+ // Throw an error if the category is invalid
+ if (!navNode.category || !navNode.content) {
+ throw new Error(
+ `Nav category nodes must have either a .name or .category property.`
+ )
+ }
+ // Process the navNode's nested content into the new format
+ const nestedPathStack = pathStack.concat(navNode.category)
+ const nestedRoutes = convertNavTree(
+ navNode.content,
+ collectedFrontmatter,
+ nestedPathStack,
+ subfolder
+ )
+ // Then, handle index data, which is a bit more of an undertaking...
+ // First, we try to gather index data for the entry
+ // The path we want for our new format does NOT contain
+ // the content subfolder or the file extension (always `.mdx`)
+ const USE_EXPLICIT_INDEX = false
+ const pathParts = USE_EXPLICIT_INDEX
+ ? [navNode.category, 'index']
+ : [navNode.category]
+ const pathNewFormat = pathStack.concat(pathParts).join('/')
+ // The path we need to match from the older format
+ // includes the content subfolder as well as the file extension
+ const pathFromSubfolder = `${pathNewFormat}${
+ USE_EXPLICIT_INDEX ? '' : '/index'
+ }.mdx`
+ const pathToMatch = path.join(subfolder, pathFromSubfolder)
+ // Try to find the corresponding index page resource
+ const matchedFrontmatter = collectedFrontmatter.filter((resource) => {
+ return resource.__resourcePath === pathToMatch
+ })[0]
+ const fmTitle = matchedFrontmatter
+ ? matchedFrontmatter.sidebar_title || matchedFrontmatter.page_title
+ : false
+ if (!fmTitle && !navNode.name) {
+ throw new Error(
+ `Nav category nodes must have either an index file with a sidebar_title or page_title in the frontmatter, or a .name property.`
+ )
+ }
+ const title = fmTitle || navNode.name
+ // Set up an index page entry, if applicable
+ const indexRoute = matchedFrontmatter
+ ? {
+ title: 'Overview',
+ path: pathNewFormat,
+ }
+ : false
+
+ // Finally, construct and return the category node
+ const routes = indexRoute ? [indexRoute, ...nestedRoutes] : nestedRoutes
+ return {
+ title: formatTitle(title),
+ routes,
+ }
+}
+
+function convertNavLeaf(navNode, collectedFrontmatter, pathStack, subfolder) {
+ // The path we want for our new format does NOT contain
+ // the content subfolder or the file extension (always `.mdx`)
+ const pathNewFormat = pathStack.concat(navNode).join('/')
+ // The path we need to match from the older format
+ // includes the content subfolder as well as the file extension
+ const pathToMatch = path.join(subfolder, `${pathNewFormat}.mdx`)
+ // We filter for matching frontmatter to get the "title" for the nav leaf.
+ // We throw an error if there is no matching resource - there should be!
+ const matchedFrontmatter = collectedFrontmatter.filter((resource) => {
+ return resource.__resourcePath === pathToMatch
+ })[0]
+ if (!matchedFrontmatter) {
+ throw new Error(
+ `Could not find frontmatter for resource path ${pathToMatch}.`
+ )
+ }
+ // We pull the title from frontmatter.
+ // We throw an error if there is no title in frontmatter - there should be!
+ const { sidebar_title, page_title } = matchedFrontmatter
+ const title = sidebar_title || page_title
+ if (!title) {
+ throw new Error(`Could not find title in frontmatter of ${pathToMatch}.`)
+ }
+ // Return the new format for the nav leaf
+ return { title: formatTitle(title), path: pathNewFormat }
+}
+
+async function collectFrontmatter(inputDir, fileFilter) {
+ // Traverse directories and parse frontmatter
+ const targetFilepaths = klawSync(inputDir, {
+ traverseAll: true,
+ filter: fileFilter,
+ }).map((f) => f.path)
+ const inputDirPath = path.join(process.cwd(), inputDir)
+ const collectedFrontmatter = await Promise.all(
+ targetFilepaths.map(async (filePath) => {
+ const rawFile = fs.readFileSync(filePath, 'utf-8')
+ const { data: frontmatter } = grayMatter(rawFile)
+ const __resourcePath = path.relative(inputDirPath, filePath)
+ return { __resourcePath, ...frontmatter }
+ })
+ )
+ return collectedFrontmatter
+}
+
+function formatTitle(title) {
+ return title.replace(//g, '').replace(/<\/tt>/g, '')
+}
+
+function writeJsonFile(data, dir, file) {
+ // Set up a directory for output
+ const outputDir = path.join(process.cwd(), dir)
+ const outputFile = path.join(outputDir, file)
+ fs.mkdirSync(outputDir, { recursive: true })
+ // Stringify the collected frontmatter, and write the file
+ const fileString = JSON.stringify(data, null, 2)
+ fs.writeFileSync(outputFile, fileString)
+ return true
+}
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..059e38ad9
--- /dev/null
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.js
@@ -0,0 +1,58 @@
+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) {
+ // Handle leaf nodes
+ if (navNode.path) {
+ // Ignore remote leaf nodes, these already
+ // have their content file explicitly defined
+ // TODO is there a way we can avoid remoteFile nodes, without making this implementation have to know about them?
+ if (navNode.remoteFile) return navNode
+ // Handle local leaf nodes
+ 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) {
+ console.log(JSON.stringify(navNode, null, 2))
+ throw new Error(
+ `Could not find file to match path "${navNode.path}". Neither "${namedFilePath}" or "${indexFilePath}" could be found.`
+ )
+ }
+ if (hasIndexFile && hasNamedFile) {
+ console.warn(
+ `Ambiguous path "${navNode.path}". Both "${namedFilePath}" and "${indexFilePath}" exist.`
+ )
+ }
+ 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-route-structure/index.js b/packages/docs-sidenav/utils/validate-route-structure/index.js
new file mode 100644
index 000000000..af23f6bb9
--- /dev/null
+++ b/packages/docs-sidenav/utils/validate-route-structure/index.js
@@ -0,0 +1,110 @@
+function validateRouteStructure(navData) {
+ return validateBranchRoutes(navData)[1]
+}
+
+function validateBranchRoutes(navNodes, depth = 0) {
+ // In order to be a valid branch, there needs to be at least one navNode.
+ if (navNodes.length === 0) {
+ throw new Error(`Found empty array of navNodes. Depth: ${depth}`)
+ }
+ // Augment each navNode with its path __stack
+ const navNodesWithStacks = navNodes.map((navNode) => {
+ // Handle leaf nodes - split their paths into a __stack
+ if (navNode.path) return { ...navNode, __stack: navNode.path.split('/') }
+ // Handle branch nodes - we recurse depth-first here
+ if (navNode.routes) return handleBranchNode(navNode, depth)
+ // Other nodes aren't relevant, we don't touch them
+ return navNode
+ })
+ // Gather all the path stacks at this level
+ const routeStacks = navNodesWithStacks.reduce((acc, navNode) => {
+ // Ignore nodes that don't have a path stack
+ if (!navNode.__stack) return acc
+ // For other nodes, add their stacks
+ return acc.concat([navNode.__stack])
+ }, [])
+ // Ensure that there are no duplicate routes
+ // (for example, a nested route with a particular path,
+ // and a named page at the same level with the same path)
+ const routePaths = routeStacks.map((s) => s.join('/'))
+ const duplicateRoutes = routePaths.filter((value, index, self) => {
+ return self.indexOf(value) !== index
+ })
+ if (duplicateRoutes.length > 0) {
+ throw new Error(
+ `Duplicate routes found:\n\n${JSON.stringify(duplicateRoutes)}\n`
+ )
+ }
+ // Gather an array of all resolved paths at this level
+ const parentRoutes = routeStacks.map((stack) => {
+ // Index leaf nodes will have the same
+ // number of path parts as the current nesting depth.
+ const isIndexNode = stack.length === depth
+ if (isIndexNode) {
+ // The "dirPath" for index nodes is
+ // just the original path
+ return stack.join('/')
+ }
+ // Named leaf nodes, and nested routes,
+ // will have one more path part than the current nesting depth.
+ const isNamedNode = stack.length === depth + 1
+ if (isNamedNode) {
+ // The "dirPath" for named nodes is
+ // the original path with the last part dropped.
+ return stack.slice(0, stack.length - 1).join('/')
+ }
+ // If we have any other number of parts in the
+ // leaf node's path, then it is invalid.
+ throw new Error(
+ `Invalid path depth. At depth ${depth}, found path "${stack.join('/')}"`
+ )
+ })
+ // We expect all routes at any level to share the same parent directory.
+ // In other words, we expect there to be exactly one unique "dirPath"
+ // shared across all the routes at this level.
+ const uniqueParents = parentRoutes.filter((value, index, self) => {
+ return self.indexOf(value) === index
+ })
+ // We throw an error if we find mismatched paths
+ // that don't share the same parent path.
+ if (uniqueParents.length > 1) {
+ throw new Error(`Found mismatched paths: ${JSON.stringify(uniqueParents)}`)
+ }
+ const path = uniqueParents[0]
+ // Finally, we return
+ return [path, navNodesWithStacks]
+}
+
+function handleBranchNode(navNode, depth) {
+ // We recurse depth-first here, and we'll throw an error
+ // if the nested routes had structural issues
+ const [path, routesWithStacks] = validateBranchRoutes(
+ navNode.routes,
+ depth + 1
+ )
+ const __stack = path.split('/')
+ return { ...navNode, __stack, routes: routesWithStacks }
+}
+
+module.exports = validateRouteStructure
+
+//
+//
+//
+//
+//
+//
+//
+//
+
+// TODO - throw error if any non-divider node does not have a title
+// function collectEmptyTitleErrors(navData) {
+// const errors = [];
+// return errors;
+// }
+
+// TODO - throw error if direct link nodes don't have both { title, href }
+// function collectDirectLinkErrors(navData) {
+// const errors = [];
+// return errors;
+// }
diff --git a/pages/global.css b/pages/global.css
index 9ee5aa1d7..73d718068 100644
--- a/pages/global.css
+++ b/pages/global.css
@@ -11,7 +11,6 @@
@import '../packages/button/styles/index.css';
@import '../packages/callouts/styles/index.css';
@import '../packages/checkbox-input/style.css';
-@import '../packages/docs-sidenav/style.css';
@import '../packages/accordion/style.css';
@import '../packages/subnav/style.css';
@import '../packages/call-to-action/style.css';
From 8bc32139fc5e60ab6af6756f64abe363eea74bae Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 25 Feb 2021 10:11:44 -0500
Subject: [PATCH 02/62] Reorder props for clearer diff
---
packages/docs-page/index.js | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/packages/docs-page/index.js b/packages/docs-page/index.js
index 986100c51..67392199f 100644
--- a/packages/docs-page/index.js
+++ b/packages/docs-page/index.js
@@ -15,12 +15,12 @@ export function DocsPageWrapper({
description,
filePath,
mainBranch = 'main',
+ navData,
currentPath,
pageTitle,
product: { name, slug },
showEditPage = true,
subpath,
- navData,
}) {
// TEMPORARY (https://app.asana.com/0/1100423001970639/1160656182754009)
// activates the "jump to section" feature
@@ -99,11 +99,11 @@ export default function DocsPage({
return (
+
setOpen(!open)}>
').replace(/<\/tt>/g, '')
}
-
-function writeJsonFile(data, dir, file) {
- // Set up a directory for output
- const outputDir = path.join(process.cwd(), dir)
- const outputFile = path.join(outputDir, file)
- fs.mkdirSync(outputDir, { recursive: true })
- // Stringify the collected frontmatter, and write the file
- const fileString = JSON.stringify(data, null, 2)
- fs.writeFileSync(outputFile, fileString)
- return true
-}
diff --git a/packages/docs-sidenav/bin/npx-hello-world.js b/packages/docs-sidenav/bin/npx-hello-world.js
new file mode 100644
index 000000000..593097b40
--- /dev/null
+++ b/packages/docs-sidenav/bin/npx-hello-world.js
@@ -0,0 +1,3 @@
+#! /usr/bin/env node
+console.log(process.argv)
+console.log('Hello world, executing from react-docs-subnav!')
diff --git a/packages/docs-sidenav/package-lock.json b/packages/docs-sidenav/package-lock.json
index 935a9a04b..8cff3fe71 100644
--- a/packages/docs-sidenav/package-lock.json
+++ b/packages/docs-sidenav/package-lock.json
@@ -4,10 +4,105 @@
"lockfileVersion": 1,
"requires": true,
"dependencies": {
+ "argparse": {
+ "version": "1.0.10",
+ "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
+ "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
+ "dev": true,
+ "requires": {
+ "sprintf-js": "~1.0.2"
+ }
+ },
+ "esprima": {
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
+ "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
+ "dev": true
+ },
+ "extend-shallow": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+ "integrity": "sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8=",
+ "dev": true,
+ "requires": {
+ "is-extendable": "^0.1.0"
+ }
+ },
"fuzzysearch": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/fuzzysearch/-/fuzzysearch-1.0.3.tgz",
"integrity": "sha1-3/yA9tawQiPyImqnndGUIxCW0Ag="
+ },
+ "graceful-fs": {
+ "version": "4.2.6",
+ "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.6.tgz",
+ "integrity": "sha512-nTnJ528pbqxYanhpDYsi4Rd8MAeaBA67+RZ10CM1m3bTAVFEDcd5AuA4a6W5YkGZ1iNXHzZz8T6TBKLeBuNriQ==",
+ "dev": true
+ },
+ "gray-matter": {
+ "version": "4.0.2",
+ "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.2.tgz",
+ "integrity": "sha512-7hB/+LxrOjq/dd8APlK0r24uL/67w7SkYnfwhNFwg/VDIGWGmduTDYf3WNstLW2fbbmRwrDGCVSJ2isuf2+4Hw==",
+ "dev": true,
+ "requires": {
+ "js-yaml": "^3.11.0",
+ "kind-of": "^6.0.2",
+ "section-matter": "^1.0.0",
+ "strip-bom-string": "^1.0.0"
+ }
+ },
+ "is-extendable": {
+ "version": "0.1.1",
+ "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
+ "integrity": "sha1-YrEQ4omkcUGOPsNqYX1HLjAd/Ik=",
+ "dev": true
+ },
+ "js-yaml": {
+ "version": "3.14.1",
+ "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
+ "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
+ "dev": true,
+ "requires": {
+ "argparse": "^1.0.7",
+ "esprima": "^4.0.0"
+ }
+ },
+ "kind-of": {
+ "version": "6.0.3",
+ "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
+ "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
+ "dev": true
+ },
+ "klaw-sync": {
+ "version": "6.0.0",
+ "resolved": "https://registry.npmjs.org/klaw-sync/-/klaw-sync-6.0.0.tgz",
+ "integrity": "sha512-nIeuVSzdCCs6TDPTqI8w1Yre34sSq7AkZ4B3sfOBbI2CgVSB4Du4aLQijFU2+lhAFCwt9+42Hel6lQNIv6AntQ==",
+ "dev": true,
+ "requires": {
+ "graceful-fs": "^4.1.11"
+ }
+ },
+ "section-matter": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
+ "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
+ "dev": true,
+ "requires": {
+ "extend-shallow": "^2.0.1",
+ "kind-of": "^6.0.0"
+ }
+ },
+ "sprintf-js": {
+ "version": "1.0.3",
+ "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
+ "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw=",
+ "dev": true
+ },
+ "strip-bom-string": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
+ "integrity": "sha1-5SEekiQ2n7uB1jOi8ABE3IztrZI=",
+ "dev": true
}
}
}
diff --git a/packages/docs-sidenav/package.json b/packages/docs-sidenav/package.json
index eefcda6f9..ed98d6384 100644
--- a/packages/docs-sidenav/package.json
+++ b/packages/docs-sidenav/package.json
@@ -3,6 +3,10 @@
"description": "Sidebar used for navigation HashiCorp docs",
"version": "7.0.0",
"author": "HashiCorp",
+ "bin": {
+ "npx-hello-world": "bin/npx-hello-world.js",
+ "migrate-nav-data": "bin/migrate-nav-data.js"
+ },
"contributors": [
"Jeff Escalante"
],
@@ -17,5 +21,9 @@
"publishConfig": {
"access": "public"
},
- "gitHead": "c47c50a8419f6278073505ebbe25c9fbe4faab07"
+ "gitHead": "c47c50a8419f6278073505ebbe25c9fbe4faab07",
+ "devDependencies": {
+ "gray-matter": "^4.0.2",
+ "klaw-sync": "^6.0.0"
+ }
}
From 644398e8274b37e73abb4dc956a7743df1a9bdbf Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 25 Feb 2021 13:26:18 -0500
Subject: [PATCH 05/62] Remove devdeps, not useful
---
packages/docs-sidenav/bin/migrate-nav-data.js | 11 +++
packages/docs-sidenav/package-lock.json | 95 -------------------
packages/docs-sidenav/package.json | 6 +-
3 files changed, 12 insertions(+), 100 deletions(-)
diff --git a/packages/docs-sidenav/bin/migrate-nav-data.js b/packages/docs-sidenav/bin/migrate-nav-data.js
index dad42acb2..dbf377c18 100644
--- a/packages/docs-sidenav/bin/migrate-nav-data.js
+++ b/packages/docs-sidenav/bin/migrate-nav-data.js
@@ -4,6 +4,17 @@ const path = require('path')
const grayMatter = require('gray-matter')
const klawSync = require('klaw-sync')
+/*
+USAGE
+
+Eg:
+- old nav data is in ./data/docs-navigation.js
+- content is in ./content/docs
+- output file is ./data/docs-nav-data.json
+
+npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.7 migrate-nav-data ./data/docs-navigation.js ./content/docs ./data/docs-nav-data.json
+*/
+
const navigationJsData = require(path.resolve(process.argv[2]))
const CONTENT_DIR = path.join(process.cwd(), process.argv[3])
const OUT_FILE = path.join(process.cwd(), process.argv[4])
diff --git a/packages/docs-sidenav/package-lock.json b/packages/docs-sidenav/package-lock.json
index 8cff3fe71..935a9a04b 100644
--- a/packages/docs-sidenav/package-lock.json
+++ b/packages/docs-sidenav/package-lock.json
@@ -4,105 +4,10 @@
"lockfileVersion": 1,
"requires": true,
"dependencies": {
- "argparse": {
- "version": "1.0.10",
- "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
- "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
- "dev": true,
- "requires": {
- "sprintf-js": "~1.0.2"
- }
- },
- "esprima": {
- "version": "4.0.1",
- "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
- "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
- "dev": true
- },
- "extend-shallow": {
- "version": "2.0.1",
- "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
- "integrity": "sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8=",
- "dev": true,
- "requires": {
- "is-extendable": "^0.1.0"
- }
- },
"fuzzysearch": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/fuzzysearch/-/fuzzysearch-1.0.3.tgz",
"integrity": "sha1-3/yA9tawQiPyImqnndGUIxCW0Ag="
- },
- "graceful-fs": {
- "version": "4.2.6",
- "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.6.tgz",
- "integrity": "sha512-nTnJ528pbqxYanhpDYsi4Rd8MAeaBA67+RZ10CM1m3bTAVFEDcd5AuA4a6W5YkGZ1iNXHzZz8T6TBKLeBuNriQ==",
- "dev": true
- },
- "gray-matter": {
- "version": "4.0.2",
- "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.2.tgz",
- "integrity": "sha512-7hB/+LxrOjq/dd8APlK0r24uL/67w7SkYnfwhNFwg/VDIGWGmduTDYf3WNstLW2fbbmRwrDGCVSJ2isuf2+4Hw==",
- "dev": true,
- "requires": {
- "js-yaml": "^3.11.0",
- "kind-of": "^6.0.2",
- "section-matter": "^1.0.0",
- "strip-bom-string": "^1.0.0"
- }
- },
- "is-extendable": {
- "version": "0.1.1",
- "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
- "integrity": "sha1-YrEQ4omkcUGOPsNqYX1HLjAd/Ik=",
- "dev": true
- },
- "js-yaml": {
- "version": "3.14.1",
- "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
- "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
- "dev": true,
- "requires": {
- "argparse": "^1.0.7",
- "esprima": "^4.0.0"
- }
- },
- "kind-of": {
- "version": "6.0.3",
- "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
- "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
- "dev": true
- },
- "klaw-sync": {
- "version": "6.0.0",
- "resolved": "https://registry.npmjs.org/klaw-sync/-/klaw-sync-6.0.0.tgz",
- "integrity": "sha512-nIeuVSzdCCs6TDPTqI8w1Yre34sSq7AkZ4B3sfOBbI2CgVSB4Du4aLQijFU2+lhAFCwt9+42Hel6lQNIv6AntQ==",
- "dev": true,
- "requires": {
- "graceful-fs": "^4.1.11"
- }
- },
- "section-matter": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
- "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
- "dev": true,
- "requires": {
- "extend-shallow": "^2.0.1",
- "kind-of": "^6.0.0"
- }
- },
- "sprintf-js": {
- "version": "1.0.3",
- "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
- "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw=",
- "dev": true
- },
- "strip-bom-string": {
- "version": "1.0.0",
- "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
- "integrity": "sha1-5SEekiQ2n7uB1jOi8ABE3IztrZI=",
- "dev": true
}
}
}
diff --git a/packages/docs-sidenav/package.json b/packages/docs-sidenav/package.json
index ed98d6384..135e11a16 100644
--- a/packages/docs-sidenav/package.json
+++ b/packages/docs-sidenav/package.json
@@ -21,9 +21,5 @@
"publishConfig": {
"access": "public"
},
- "gitHead": "c47c50a8419f6278073505ebbe25c9fbe4faab07",
- "devDependencies": {
- "gray-matter": "^4.0.2",
- "klaw-sync": "^6.0.0"
- }
+ "gitHead": "c47c50a8419f6278073505ebbe25c9fbe4faab07"
}
From 8620fb583f1908c4eaf881948e9059b1648c6010 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 25 Feb 2021 13:27:34 -0500
Subject: [PATCH 06/62] Update comment
---
packages/docs-sidenav/bin/migrate-nav-data.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/docs-sidenav/bin/migrate-nav-data.js b/packages/docs-sidenav/bin/migrate-nav-data.js
index dbf377c18..9e5ddeb3f 100644
--- a/packages/docs-sidenav/bin/migrate-nav-data.js
+++ b/packages/docs-sidenav/bin/migrate-nav-data.js
@@ -12,7 +12,7 @@ Eg:
- content is in ./content/docs
- output file is ./data/docs-nav-data.json
-npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.7 migrate-nav-data ./data/docs-navigation.js ./content/docs ./data/docs-nav-data.json
+npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.8 migrate-nav-data ./data/docs-navigation.js ./content/docs ./data/docs-nav-data.json
*/
const navigationJsData = require(path.resolve(process.argv[2]))
From 87bc56cf9aa3042fe7b7477f60a75d8209a1243e Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 25 Feb 2021 15:47:49 -0500
Subject: [PATCH 07/62] Fix issue with direct links
---
packages/docs-sidenav/bin/migrate-nav-data.js | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/packages/docs-sidenav/bin/migrate-nav-data.js b/packages/docs-sidenav/bin/migrate-nav-data.js
index 9e5ddeb3f..0255bebe9 100644
--- a/packages/docs-sidenav/bin/migrate-nav-data.js
+++ b/packages/docs-sidenav/bin/migrate-nav-data.js
@@ -47,12 +47,15 @@ function convertNavTree(navTree, collectedFrontmatter, pathStack, subfolder) {
return convertNavLeaf(navNode, collectedFrontmatter, pathStack, subfolder)
// if the node has an `href` or `title`, it's a direct link
if (navNode.href || navNode.title) {
- // if a direct link doesn't have both `href` and `title`, we throw an error
- throw new Error(
- `Direct sidebar links must have both a "href" and "title". Found a direct link with only one of the two:\n\n ${JSON.stringify(
- navNode
- )}`
- )
+ if (!navNode.href || !navNode.title) {
+ // if a direct link doesn't have both `href` and `title`, we throw an error
+ throw new Error(
+ `Direct sidebar links must have both a "href" and "title". Found a direct link with only one of the two:\n\n ${JSON.stringify(
+ navNode
+ )}`
+ )
+ }
+ return { title: navNode.title, href: navNode.href }
}
// Otherwise, we expect the node to be a nested category
return convertNavCategory(
From a6ca716937356007bfc839720959ee7be91532de Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 25 Feb 2021 16:31:59 -0500
Subject: [PATCH 08/62] Refine DocsPage props API
---
packages/docs-page/index.js | 33 ++++++++++++++-----
packages/docs-page/package-lock.json | 6 ++--
packages/docs-page/package.json | 2 +-
packages/docs-sidenav/bin/migrate-nav-data.js | 2 +-
4 files changed, 29 insertions(+), 14 deletions(-)
diff --git a/packages/docs-page/index.js b/packages/docs-page/index.js
index 67392199f..9fa2ff3cb 100644
--- a/packages/docs-page/index.js
+++ b/packages/docs-page/index.js
@@ -13,8 +13,7 @@ export function DocsPageWrapper({
canonicalUrl,
children,
description,
- filePath,
- mainBranch = 'main',
+ editLink,
navData,
currentPath,
pageTitle,
@@ -71,9 +70,7 @@ export function DocsPageWrapper({
{/* if desired, show an "edit this page" link on the bottom right, linking to github */}
{showEditPage && (
-
+
})
Edit this page
@@ -83,14 +80,33 @@ export function DocsPageWrapper({
)
}
+/*
+
+ const editLink = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/content/${filePath}`
+
+
Date: Thu, 25 Feb 2021 16:47:15 -0500
Subject: [PATCH 09/62] Update comment
---
packages/docs-page/index.js | 1 +
1 file changed, 1 insertion(+)
diff --git a/packages/docs-page/index.js b/packages/docs-page/index.js
index 9fa2ff3cb..72e4f0604 100644
--- a/packages/docs-page/index.js
+++ b/packages/docs-page/index.js
@@ -96,6 +96,7 @@ export function DocsPageWrapper({
frontMatter,
currentPath
}}
+/>
*/
From c53eb2c8bfe3136f4d2abde4d675e3cb690594be Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Thu, 25 Feb 2021 17:12:21 -0500
Subject: [PATCH 10/62] Add todo
---
packages/docs-page/index.js | 28 ++++------------------------
packages/docs-sidenav/index.js | 2 +-
packages/docs-sidenav/package.json | 2 +-
3 files changed, 6 insertions(+), 26 deletions(-)
diff --git a/packages/docs-page/index.js b/packages/docs-page/index.js
index 72e4f0604..86c335a1e 100644
--- a/packages/docs-page/index.js
+++ b/packages/docs-page/index.js
@@ -19,7 +19,7 @@ export function DocsPageWrapper({
pageTitle,
product: { name, slug },
showEditPage = true,
- subpath,
+ subpath, // TODO rename to baseRoute, more accurate
}) {
// TEMPORARY (https://app.asana.com/0/1100423001970639/1160656182754009)
// activates the "jump to section" feature
@@ -46,7 +46,7 @@ export function DocsPageWrapper({
Edit this page
@@ -83,14 +80,33 @@ export function DocsPageWrapper({
)
}
+/*
+
+ const editLink = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/content/${filePath}`
+
+
{/* render the page's data to the document head */}
@@ -46,7 +49,7 @@ export function DocsPageWrapper({
-
+
Edit this page
@@ -82,9 +85,9 @@ export function DocsPageWrapper({
export default function DocsPage({
product,
- subpath, // TODO rename to baseRoute, more accurate
+ baseRoute,
navData,
- editLink,
+ mainBranch,
showEditPage = true,
additionalComponents,
staticProps: { mdxSource, frontMatter, currentPath },
@@ -98,13 +101,13 @@ export default function DocsPage({
{content}
diff --git a/packages/docs-sidenav/index.js b/packages/docs-sidenav/index.js
index bfb121fb3..6f4460c9c 100644
--- a/packages/docs-sidenav/index.js
+++ b/packages/docs-sidenav/index.js
@@ -11,7 +11,7 @@ import s from './style.module.css'
export default function DocsSidenav({
currentPath,
- rootPath, // TODO rename to baseRoute, more accurate
+ baseRoute,
product,
disableFilter = false,
navData,
@@ -60,7 +60,7 @@ export default function DocsSidenav({
/>
)}
{
// Dividers
if (item.divider) {
@@ -133,21 +133,21 @@ function NavTree({ content, category, Link }) {
key={item.path}
title={item.title}
isActive={item.__isActive}
- url={`/${category}/${item.path}`}
+ url={`/${baseRoute}/${item.path}`}
Link={Link}
/>
)
}
- // Otherwise, render a nav category
+ // Otherwise, render a nav branch
// (this will recurse and render a nav tree)
return (
-
Edit this page
@@ -82,9 +85,9 @@ export function DocsPageWrapper({
export default function DocsPage({
product,
- subpath, // TODO rename to baseRoute, more accurate
+ baseRoute,
navData,
- editLink,
+ mainBranch,
showEditPage = true,
additionalComponents,
staticProps: { mdxSource, frontMatter, currentPath },
@@ -98,13 +101,13 @@ export default function DocsPage({
-
-
-
+
This is a cool docs page!
', scope: {}, }, - frontMatter: { page_title: 'Test Page', description: 'test description' }, - filePath: 'test.mdx', - currentPath: componentProps.currentPath.testValue, + navData: componentProps.navData.testValue, }, }} >{`Example Page
diff --git a/packages/docs-page/index.js b/packages/docs-page/index.js index 9c7b7834f..30face2f9 100644 --- a/packages/docs-page/index.js +++ b/packages/docs-page/index.js @@ -86,11 +86,10 @@ export function DocsPageWrapper({ export default function DocsPage({ product, baseRoute, - navData, mainBranch, showEditPage = true, additionalComponents, - staticProps: { mdxSource, frontMatter, currentPath }, + staticProps: { mdxSource, frontMatter, currentPath, navData }, }) { // This component is written to work with next-mdx-remote -- here it hydrates the content const content = hydrate(mdxSource, { diff --git a/packages/docs-sidenav/docs.mdx b/packages/docs-sidenav/docs.mdx index 3edf74178..f3c0d6696 100644 --- a/packages/docs-sidenav/docs.mdx +++ b/packages/docs-sidenav/docs.mdx @@ -7,7 +7,7 @@ DocsSidenav renders a tree of links, with the option to include nested sections.This is a cool docs page!
', scope: {}, }, - navData: componentProps.navData.testValue, + navData: componentProps.staticProps.properties.navData.testValue, + currentPath: componentProps.staticProps.properties.currentPath.testValue, + frontMatter: { page_title: 'Test Page', description: 'test description' }, }, }} >{`hello world
}`', + 'The default branch of the project being documented, typically either "master" or "main". Used for the `Edit this page` link.', + default: 'main', }, 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', description: 'Directly pass the return value of `server/generateStaticProps` in here.', + properties: { + mdxSource: { + type: 'object', + description: + "Data returned from running `next-mdx-remote/render-to-string` on the page's isolated `.mdx` file contents.", + }, + frontmatter: { + type: 'object', + description: "Frontmatter object parsed from the page's `.mdx` file.", + }, + currentPath: docsSidenavProps.currentPath, + navData: docsSidenavProps.navData, + }, }, } diff --git a/packages/docs-sidenav/fixtures/navdata-example.json b/packages/docs-sidenav/fixtures/nav-data.json similarity index 100% rename from packages/docs-sidenav/fixtures/navdata-example.json rename to packages/docs-sidenav/fixtures/nav-data.json diff --git a/packages/docs-sidenav/props.js b/packages/docs-sidenav/props.js index 8acb10a0a..4866a9e48 100644 --- a/packages/docs-sidenav/props.js +++ b/packages/docs-sidenav/props.js @@ -1,22 +1,8 @@ -const sampleNavData = require('./fixtures/navdata-example.json') - -const productSlugs = [ - 'nomad', - 'consul', - 'terraform', - 'packer', - 'vagrant', - 'boundary', - 'waypoint', -] +const sampleNavData = require('./fixtures/nav-data.json') +const sharedProps = require('../../props') module.exports = { - product: { - type: 'string', - description: 'Slug of the current product for color theming', - testValue: 'terraform', - options: productSlugs, - }, + product: sharedProps.product, currentPath: { type: 'string', description: @@ -25,7 +11,8 @@ module.exports = { }, baseRoute: { type: 'string', - description: 'Top level navigation route, for example `docs`, `api`, etc.', + description: + 'Top level navigation route, for example `docs`, `api-docs`, etc.', testValue: 'docs', }, disableFilter: { @@ -35,7 +22,8 @@ module.exports = { }, navData: { type: 'object', - description: 'Tree of navigation data to render', + description: + 'Tree of navigation data to render. See `docs-sidenav/types.js` for details.', testValue: sampleNavData, }, } diff --git a/packages/docs-sidenav/style.module.css b/packages/docs-sidenav/style.module.css index b1679872b..ae79220fe 100644 --- a/packages/docs-sidenav/style.module.css +++ b/packages/docs-sidenav/style.module.css @@ -132,12 +132,6 @@ & code { margin-left: 2px; font-size: 0.875rem; - - /* Alt design option: with background, as inline - color: var(--code-dark); - background: var(--code-light-transparent); - padding: 0.3em 0.625em; - border-radius: 3px; */ } } diff --git a/packages/docs-sidenav/types.ts b/packages/docs-sidenav/types.ts index 9628c167a..57cdad876 100644 --- a/packages/docs-sidenav/types.ts +++ b/packages/docs-sidenav/types.ts @@ -1,8 +1,8 @@ -// navData is an array of NavNodes -declare const navData: NavNode[] +// NavData is an array of NavNodes +export type NavData = NavNode[] // A NavNode can be any of these types -type NavNode = NavLeaf | NavDirectLink | NavDivider | NavBranch +export type NavNode = NavLeaf | NavDirectLink | NavDivider | NavBranch // A NavLeaf represents a page with content. // From 8b3f2f36075fdf93be85648db80746b2495eca9d Mon Sep 17 00:00:00 2001 From: Zach Shilton <4624598+zchsh@users.noreply.github.com> Date: Thu, 4 Mar 2021 13:16:45 -0500 Subject: [PATCH 24/62] Nit to cleanup diff --- packages/docs-page/docs.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/docs-page/docs.mdx b/packages/docs-page/docs.mdx index d4d9c0c52..4839a25ae 100644 --- a/packages/docs-page/docs.mdx +++ b/packages/docs-page/docs.mdx @@ -47,8 +47,7 @@ We have a lot of docs sites, all of which render content in exactly the same way >{`Example Page
From e41cef700fce955aaabe537caa69dde88c9f4341 Mon Sep 17 00:00:00 2001 From: Zach Shilton <4624598+zchsh@users.noreply.github.com> Date: Thu, 4 Mar 2021 13:33:00 -0500 Subject: [PATCH 25/62] Continue refining docs --- packages/docs-page/docs.mdx | 2 +- packages/docs-page/index.js | 7 +++---- packages/docs-page/props.js | 28 +++++++++++++++++++++++++++- packages/docs-sidenav/index.js | 3 ++- packages/docs-sidenav/props.js | 4 +++- 5 files changed, 36 insertions(+), 8 deletions(-) diff --git a/packages/docs-page/docs.mdx b/packages/docs-page/docs.mdx index 4839a25ae..e8e788004 100644 --- a/packages/docs-page/docs.mdx +++ b/packages/docs-page/docs.mdx @@ -40,8 +40,8 @@ We have a lot of docs sites, all of which render content in exactly the same way scope: {}, }, navData: componentProps.staticProps.properties.navData.testValue, - currentPath: componentProps.staticProps.properties.currentPath.testValue, frontMatter: { page_title: 'Test Page', description: 'test description' }, + currentPath: componentProps.staticProps.properties.currentPath.testValue, }, }} >{`
-
+
Edit this page
diff --git a/packages/docs-page/props.js b/packages/docs-page/props.js
index 0f7d391fd..646aee14a 100644
--- a/packages/docs-page/props.js
+++ b/packages/docs-page/props.js
@@ -4,18 +4,22 @@ const sharedProps = require('../../props')
module.exports = {
product: {
type: 'string',
+ required: true,
description:
'The `name` and `slug` of the product this page is being rendered for. Used for theming, page `
} -function DirectLink({ title, href }) { +function DirectLink({ title, href, isActive }) { return ('
)
test.todo(
- 'passes `product`, `category`, `currentPage`, `data`, and `order` correctly to '
+ 'passes `product`, `baseRoute`, `currentPath`, and `navData` correctly to '
)
test.todo('passes `product` and `content` correctly to ')
test.todo('displays `showEditPage` as true by default')
diff --git a/packages/docs-sidenav/index.test.js b/packages/docs-sidenav/index.test.js
index e3d8930ea..bb9458c87 100644
--- a/packages/docs-sidenav/index.test.js
+++ b/packages/docs-sidenav/index.test.js
@@ -4,19 +4,8 @@
// import expectThrow from '../../__test-helpers/expect-throw'
describe(')` - 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
index 3aa224819..5b96be23e 100644
--- a/packages/docs-sidenav/fixtures/nav-data.json
+++ b/packages/docs-sidenav/fixtures/nav-data.json
@@ -1,4 +1,8 @@
[
+ {
+ "title": "What is Vault?",
+ "path": "what-is-vault"
+ },
{
"title": "Vault Agent",
"routes": [
diff --git a/packages/docs-sidenav/utils/validate-file-paths/index.js b/packages/docs-sidenav/utils/validate-file-paths/index.js
index 0c50d8fbf..05253290f 100644
--- a/packages/docs-sidenav/utils/validate-file-paths/index.js
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.js
@@ -27,14 +27,13 @@ async function validateNode(navNode, localDir) {
path.join(process.cwd(), localDir, namedFilePath)
)
if (!hasIndexFile && !hasNamedFile) {
- console.log(JSON.stringify(navNode, null, 2))
throw new Error(
`Could not find file to match path "${navNode.path}". Neither "${namedFilePath}" or "${indexFilePath}" could be found.`
)
}
if (hasIndexFile && hasNamedFile) {
- console.warn(
- `Ambiguous path "${navNode.path}". Both "${namedFilePath}" and "${indexFilePath}" exist.`
+ throw new Error(
+ `Ambiguous path "${navNode.path}". Both "${namedFilePath}" and "${indexFilePath}" exist. Please delete one of these files.`
)
}
const filePath = path.join(
diff --git a/packages/docs-sidenav/utils/validate-file-paths/index.test.js b/packages/docs-sidenav/utils/validate-file-paths/index.test.js
index 29b5f492a..bee8fa0b5 100644
--- a/packages/docs-sidenav/utils/validate-file-paths/index.test.js
+++ b/packages/docs-sidenav/utils/validate-file-paths/index.test.js
@@ -1,9 +1,61 @@
-// import validateFilePaths from './index.test.js'
-// import expectThrow from '../../__test-helpers/expect-throw'
+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('
Edit this page
diff --git a/packages/docs-page/props.js b/packages/docs-page/props.js
index 0f7d391fd..646aee14a 100644
--- a/packages/docs-page/props.js
+++ b/packages/docs-page/props.js
@@ -4,18 +4,22 @@ const sharedProps = require('../../props')
module.exports = {
product: {
type: 'string',
+ required: true,
description:
'The `name` and `slug` of the product this page is being rendered for. Used for theming, page `GCP",
"path": "agent/autoauth/methods/gcp"
+ },
+ { "divider": true },
+ {
+ "title": "External Link",
+ "href": "https://google.com"
+ },
+ {
+ "title": "Internal Direct Link",
+ "href": "/some-non-docs-path"
}
]
}
diff --git a/packages/docs-sidenav/index.js b/packages/docs-sidenav/index.js
index 325d389b3..1d484fcac 100644
--- a/packages/docs-sidenav/index.js
+++ b/packages/docs-sidenav/index.js
@@ -1,6 +1,8 @@
import React, { useEffect, useState } from 'react'
import useProductMeta from '@hashicorp/nextjs-scripts/lib/providers/product-meta'
import Link from 'next/link'
+import { useRouter } from 'next/router'
+import LinkWrap, { isAbsoluteURL } from '@hashicorp/react-link-wrap'
import InlineSvg from '@hashicorp/react-inline-svg'
import svgMenuIcon from './icons/menu.svg?include'
import svgChevron from './icons/chevron.svg?include'
@@ -16,23 +18,23 @@ export default function DocsSidenav({
navData,
disableFilter = false,
}) {
+ const router = useRouter()
+ const pathname = router ? router.pathname : null
const [open, setOpen] = useState(false)
const [filterInput, setFilterInput] = useState('')
- const { themeClass } = useProductMeta(product)
const [content, setContent] = useState(navData)
const [filteredContent, setFilteredContent] = useState(navData)
+ const { themeClass } = useProductMeta(product)
- // When currentPath changes, update content
- // to ensure `__isActive` props on each content item
- // are accurate and up-to-date
- // (Note: we could also reset filter input here,
- // if we don't want to filter input to persist
- // across client-side navigation, with something like:
+ // When currentPath 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(addIsActiveToNodes(navData, currentPath))
- }, [currentPath, navData])
+ setContent(addIsActiveToNodes(navData, currentPath, pathname))
+ }, [currentPath, navData, pathname])
// When filter input changes, update content
// to filter out items that don't match
@@ -70,15 +72,21 @@ export default function DocsSidenav({
)
}
-function addIsActiveToNodes(navNodes, currentPath) {
- return navNodes.slice().map((node) => addIsActiveToNode(node, currentPath))
+function addIsActiveToNodes(navNodes, currentPath, pathname) {
+ return navNodes
+ .slice()
+ .map((node) => addIsActiveToNode(node, currentPath, pathname))
}
-function addIsActiveToNode(navNode, currentPath) {
+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)
+ const routesWithActive = addIsActiveToNodes(
+ navNode.routes,
+ currentPath,
+ pathname
+ )
const isActive = routesWithActive.filter((r) => r.__isActive).length > 0
return { ...navNode, routes: routesWithActive, __isActive: isActive }
}
@@ -88,10 +96,14 @@ function addIsActiveToNode(navNode, currentPath) {
const isActive = navNode.path === currentPath
return { ...navNode, __isActive: isActive }
}
- // Otherwise, return false
- // (for dividers, external links, etc)
- // TODO - do we need to worry about highlighting external links? yes probably,
- // sometimes these are used not as "external" but to internal links outside the baseRoute
+ // If it's a direct link,
+ // return true if the path matches the router.pathname
+ if (navNode.href) {
+ const isActive = navNode.href === pathname
+ console.log({ href: navNode.href, pathname, isActive })
+ return { ...navNode, __isActive: isActive }
+ }
+ // Otherwise, it's a divider, so return unmodified
return navNode
}
@@ -116,7 +128,7 @@ function filterContent(content, searchValue) {
}, [])
}
-function NavTree({ content, baseRoute, Link }) {
+function NavTree({ baseRoute, content }) {
return content.map((item, idx) => {
// Dividers
if (item.divider) {
@@ -125,7 +137,14 @@ function NavTree({ content, baseRoute, Link }) {
}
// Direct links
if (item.title && item.href) {
- return } -function DirectLink({ title, href }) { +function DirectLink({ title, href, isActive }) { return (
([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",
diff --git a/packages/docs-sidenav/index.js b/packages/docs-sidenav/index.js
index bc2730373..c44af36bd 100644
--- a/packages/docs-sidenav/index.js
+++ b/packages/docs-sidenav/index.js
@@ -20,7 +20,7 @@ export default function DocsSidenav({
}) {
const router = useRouter()
const pathname = router ? router.pathname : null
- const [open, setOpen] = useState(false)
+ const [isMobileOpen, setIsMobileOpen] = useState(false)
const [filterInput, setFilterInput] = useState('')
const [content, setContent] = useState(navData)
const [filteredContent, setFilteredContent] = useState(navData)
@@ -43,14 +43,20 @@ export default function DocsSidenav({
}, [filterInput, content])
return (
-
-
setOpen(!open)}>
+
+
- -
-
setOpen(!open)}>
+
+
-
+
setIsMobileOpen(!isMobileOpen)}
+ >
×
{!disableFilter && (
diff --git a/packages/docs-sidenav/index.test.js b/packages/docs-sidenav/index.test.js
index bb9458c87..158d2853a 100644
--- a/packages/docs-sidenav/index.test.js
+++ b/packages/docs-sidenav/index.test.js
@@ -1,11 +1,103 @@
// import 'regenerator-runtime/runtime'
-// import { render, fireEvent, screen } from '@testing-library/react'
-// import DocsSidenav from './'
+import { render, fireEvent, screen } from '@testing-library/react'
// import expectThrow from '../../__test-helpers/expect-throw'
+import DocsSidenav from './'
+import props from './props'
+import { getTestValues } from 'swingset/testing'
+
+const defaultProps = getTestValues(props)
describe('-
-
+
+
{!disableFilter && (
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
-}
-
-function filterContent(content, searchValue) {
- // if there's no search searchValue we short-circuit and return everything
- if (!searchValue) return 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
- }, [])
-}
-
function NavTree({ baseRoute, content }) {
return content.map((item, idx) => {
// Dividers
@@ -177,24 +160,6 @@ function NavTree({ baseRoute, content }) {
})
}
-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 (
- +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 ( +
+} diff --git a/packages/docs-sidenav/style.module.css b/packages/docs-sidenav/style.module.css index f4acac48e..737c58879 100644 --- a/packages/docs-sidenav/style.module.css +++ b/packages/docs-sidenav/style.module.css @@ -32,6 +32,10 @@ transform: translateX(100%); padding-left: 25px; } + + &[data-is-mobile-hidden='true'] { + visibility: hidden; + } } } @@ -39,14 +43,17 @@ display: none; @media (--mobile-viewports) { + background: none; + border: none; + color: #333; + cursor: pointer; display: block; - position: absolute; - top: 18px; - right: 13px; font-size: 1.7em; + line-height: inherit; padding: 0 14px; - cursor: pointer; - color: #333; + position: absolute; + right: 13px; + top: 18px; transition: opacity 0.3s ease; z-index: 100; @@ -65,6 +72,7 @@ border-bottom: 1px solid var(--gray-6); cursor: pointer; display: none; + font-size: inherit; justify-content: center; line-height: inherit; left: 0; 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..292f6b564 --- /dev/null +++ b/packages/docs-sidenav/utils/use-event-listener.js @@ -0,0 +1,30 @@ +/* eslint-disable max-params */ +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 From 9014586f426821c5a0cffa33b7ecb16e135bcc1e Mon Sep 17 00:00:00 2001 From: Zach Shilton <4624598+zchsh@users.noreply.github.com> Date: Fri, 5 Mar 2021 18:08:27 -0500 Subject: [PATCH 40/62] Clean up comment --- packages/docs-sidenav/utils/use-event-listener.js | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/packages/docs-sidenav/utils/use-event-listener.js b/packages/docs-sidenav/utils/use-event-listener.js index 292f6b564..20f0c15ad 100644 --- a/packages/docs-sidenav/utils/use-event-listener.js +++ b/packages/docs-sidenav/utils/use-event-listener.js @@ -1,4 +1,3 @@ -/* eslint-disable max-params */ import { useRef, useEffect } from 'react' const useEventListener = ( @@ -17,13 +16,10 @@ const useEventListener = ( 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) - } + return () => element.removeEventListener(eventName, eventListener, opts) }, [eventName, element, capture, passive, once]) } From 88965e38d5ca35bfc80c34fae135903193fa4029 Mon Sep 17 00:00:00 2001 From: Zach Shilton <4624598+zchsh@users.noreply.github.com> Date: Fri, 5 Mar 2021 20:53:13 -0500 Subject: [PATCH 41/62] Add tests for docs-page --- package-lock.json | 6 + package.json | 1 + packages/docs-page/_temp-pr-notes.md | 6 + packages/docs-page/docs.mdx | 46 +----- packages/docs-page/index.test.js | 144 ++++++++++++++++-- packages/docs-page/props.js | 46 +++++- .../docs-page/temporary_jump-to-section.js | 2 +- 7 files changed, 189 insertions(+), 62 deletions(-) diff --git a/package-lock.json b/package-lock.json index 77b921667..962f4411d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11023,6 +11023,12 @@ "is-obj": "^1.0.0" } }, + "dotenv": { + "version": "8.2.0", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-8.2.0.tgz", + "integrity": "sha512-8sJ78ElpbDJBHNeBzUbUVLsqKdccaa/BXF1uPTw3GrvQTBgrQrtObr2mUrE38vzYd8cEv+m/JBfDLioYcfXoaw==", + "dev": true + }, "download": { "version": "6.2.5", "resolved": "https://registry.npmjs.org/download/-/download-6.2.5.tgz", diff --git a/package.json b/package.json index f036265a4..6883749bd 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ "devDependencies": { "@testing-library/jest-dom": "^5.11.6", "@testing-library/react": "^11.2.2", + "dotenv": "^8.2.0", "eslint": "^7.18.0", "husky": "^4.3.8", "identity-obj-proxy": "^3.0.0", diff --git a/packages/docs-page/_temp-pr-notes.md b/packages/docs-page/_temp-pr-notes.md index afd17cce7..4b9464893 100644 --- a/packages/docs-page/_temp-pr-notes.md +++ b/packages/docs-page/_temp-pr-notes.md @@ -2,6 +2,12 @@ To implement MKTG-032, changes have been made to both the `docs-page` and `doc-sidenav` components. +## Notes on tests + +- ran into difficulty testing jump-to-section +- Jest doesn't know what `innerText` is (line 13 of temporary_jump-to-section) +- Replace with `textContent` (?) We did a similar thing for `code-block`: https://app.asana.com/0/1199883977708219/1199877101801285/f ... but in this case we actually don't want to see the "permalink" text 🤔 EDIT: nvm it's fine, we were already using slice() to omit the >> char from the permalink text. + ## Common changes - `subpath` prop renamed to `baseRoute` diff --git a/packages/docs-page/docs.mdx b/packages/docs-page/docs.mdx index e8e788004..9d39ef7de 100644 --- a/packages/docs-page/docs.mdx +++ b/packages/docs-page/docs.mdx @@ -5,46 +5,9 @@ componentName: 'DocsPage' We have a lot of docs sites, all of which render content in exactly the same way. This component is a minimal abstraction of that rendering, and is intended to be used entirely as a template for all documentation content.
Example Page
This is a cool docs page!
', - scope: {}, - }, - navData: componentProps.staticProps.properties.navData.testValue, - frontMatter: { page_title: 'Test Page', description: 'test description' }, - currentPath: componentProps.staticProps.properties.currentPath.testValue, - }, - }} ->{`Example Page
This is a cool docs page!
-Example Page
This is a cool docs page!
', + scope: {}, + }, }, - frontmatter: { + frontMatter: { type: 'object', required: true, description: "Frontmatter object parsed from the page's `.mdx` file.", properties: { - canonicalUrl: { + canonical_url: { type: 'string', description: 'Optional canonical URL. Passed directly to [@hashicorp/react-head](/?component=Head).', @@ -67,17 +101,21 @@ module.exports = { description: 'Used for the ``. Passed directly to [@hashicorp/react-head](/?component=Head).', required: true, + testValue: 'Test description', }, - pageTitle: { + page_title: { type: 'string', description: 'Used to construct the meta `Example Page
This is a cool docs page!
-
-
+
Edit this page
@@ -85,10 +83,9 @@ export function DocsPageWrapper({
export default function DocsPage({
product,
baseRoute,
- mainBranch,
showEditPage = true,
additionalComponents,
- staticProps: { mdxSource, frontMatter, currentPath, navData },
+ 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, {
@@ -99,7 +96,7 @@ export default function DocsPage({
{
- p.__resourcePath = `docs/${p.__resourcePath}`
- return p
- })
+ // Read in the nav-data.json file
+ const navDataFilePath = path.join(process.cwd(), navDataFile)
+ const navDataRaw = JSON.parse(fs.readFileSync(navDataFilePath, 'utf8'))
+ const navData = await validateFilePaths(navDataRaw, docsPath)
+ // Construct the mdxSource from the provided terms
const { terms, mdxBlob } = await getGlossaryTerms()
+ const mdxSource = await renderToString(mdxBlob, {
+ mdxOptions: markdownDefaults({
+ resolveIncludes: path.join(process.cwd(), 'content/partials'),
+ }),
+ components: generateComponents(product.name, additionalComponents),
+ })
+
+ // Construct the githubFileUrl, used for "Edit this page" link
+ const githubFileUrl = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/content/glossary.mdx`
+
return {
props: {
terms,
- content: await renderToString(mdxBlob, {
- mdxOptions: markdownDefaults({
- resolveIncludes: path.join(process.cwd(), 'content/partials'),
- }),
- components: generateComponents(productName, additionalComponents),
- }),
- docsPageData,
+ mdxSource,
+ navData,
+ githubFileUrl,
},
}
}
From 1a1d5d076b410713e003a5f5daaaaa0d2a33f38e Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:00:25 -0500
Subject: [PATCH 45/62] Fix issue with githubFileUrl
---
packages/docs-page/server.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/docs-page/server.js b/packages/docs-page/server.js
index 65d417af3..1922eeab5 100644
--- a/packages/docs-page/server.js
+++ b/packages/docs-page/server.js
@@ -69,7 +69,7 @@ async function generateStaticProps(
scope,
})
// Construct the githubFileUrl, used for "Edit this page" link
- const githubFileUrl = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/content/${navNode.filePath}`
+ const githubFileUrl = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/${navNode.filePath}`
// Return all the props
return { currentPath, frontMatter, githubFileUrl, mdxSource, navData }
}
From 9c781fd6ba25f415eb9b8cee05433f2ea7dcc9d5 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:06:27 -0500
Subject: [PATCH 46/62] Bump content dep, glossary-page dep
---
packages/docs-page/package-lock.json | 5 +++++
packages/docs-page/package.json | 2 +-
packages/glossary-page/package-lock.json | 6 +++---
packages/glossary-page/package.json | 2 +-
4 files changed, 10 insertions(+), 5 deletions(-)
diff --git a/packages/docs-page/package-lock.json b/packages/docs-page/package-lock.json
index da0dc2524..22b506710 100644
--- a/packages/docs-page/package-lock.json
+++ b/packages/docs-page/package-lock.json
@@ -4,6 +4,11 @@
"lockfileVersion": 1,
"requires": true,
"dependencies": {
+ "@hashicorp/react-content": {
+ "version": "6.3.0",
+ "resolved": "https://registry.npmjs.org/@hashicorp/react-content/-/react-content-6.3.0.tgz",
+ "integrity": "sha512-B+QMlkMGryeNx3dGON4ExbzNvvll2ZXN3x+TkX80tUGClMI80MKjfSXiXIoVixlp22DMNG6wrnL42LC4WzZOxg=="
+ },
"@hashicorp/react-docs-sidenav": {
"version": "6.1.1-alpha.34",
"resolved": "https://registry.npmjs.org/@hashicorp/react-docs-sidenav/-/react-docs-sidenav-6.1.1-alpha.34.tgz",
diff --git a/packages/docs-page/package.json b/packages/docs-page/package.json
index aaf90b37e..40e97b10b 100644
--- a/packages/docs-page/package.json
+++ b/packages/docs-page/package.json
@@ -7,7 +7,7 @@
"Jeff Escalante"
],
"dependencies": {
- "@hashicorp/react-content": "^6.2.2",
+ "@hashicorp/react-content": "^6.3.0",
"@hashicorp/react-docs-sidenav": "6.1.1-alpha.34",
"@hashicorp/react-head": "^1.2.0",
"@hashicorp/react-search": "^4.1.0",
diff --git a/packages/glossary-page/package-lock.json b/packages/glossary-page/package-lock.json
index a76fedcf1..b43c402f4 100644
--- a/packages/glossary-page/package-lock.json
+++ b/packages/glossary-page/package-lock.json
@@ -133,9 +133,9 @@
"integrity": "sha512-B+QMlkMGryeNx3dGON4ExbzNvvll2ZXN3x+TkX80tUGClMI80MKjfSXiXIoVixlp22DMNG6wrnL42LC4WzZOxg=="
},
"@hashicorp/react-docs-page": {
- "version": "10.9.4-alpha.31",
- "resolved": "https://registry.npmjs.org/@hashicorp/react-docs-page/-/react-docs-page-10.9.4-alpha.31.tgz",
- "integrity": "sha512-Zm2NPlJ0B41afIabOza8Etkokh1gEYXwb9etv8NgxXvY+2uD+cfU51+/N+gVXREEHKnU3MgX/Hj6Qx/tHcSTtw==",
+ "version": "10.9.4-alpha.44",
+ "resolved": "https://registry.npmjs.org/@hashicorp/react-docs-page/-/react-docs-page-10.9.4-alpha.44.tgz",
+ "integrity": "sha512-RYDdWfnA6DrfSPN9kU7w0yFFL3Gk32dtoAyQFbKEC7CwczQJk7aSd5gEgcnRFUfl/QBoZynXoQVxLQIwUhaGYw==",
"requires": {
"@hashicorp/react-content": "^6.3.0",
"@hashicorp/react-docs-sidenav": "6.1.1-alpha.34",
diff --git a/packages/glossary-page/package.json b/packages/glossary-page/package.json
index 3f0ed6106..8cd239b5d 100644
--- a/packages/glossary-page/package.json
+++ b/packages/glossary-page/package.json
@@ -7,7 +7,7 @@
"Bryce Kalow"
],
"dependencies": {
- "@hashicorp/react-docs-page": "^10.9.4-alpha.31",
+ "@hashicorp/react-docs-page": "^10.9.4-alpha.44",
"@hashicorp/remark-plugins": "^3.1.1"
},
"license": "MPL-2.0",
From dcc0280a54593763522e7b156fa71d36fa34453e Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:08:49 -0500
Subject: [PATCH 47/62] Revert useless changes to package.jsons
---
packages/docs-page/package-lock.json | 2 +-
packages/docs-page/package.json | 2 +-
packages/docs-sidenav/package-lock.json | 2 +-
packages/docs-sidenav/package.json | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/packages/docs-page/package-lock.json b/packages/docs-page/package-lock.json
index 22b506710..e99a051a8 100644
--- a/packages/docs-page/package-lock.json
+++ b/packages/docs-page/package-lock.json
@@ -1,6 +1,6 @@
{
"name": "@hashicorp/react-docs-page",
- "version": "11.0.0",
+ "version": "10.9.3",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
diff --git a/packages/docs-page/package.json b/packages/docs-page/package.json
index 40e97b10b..84eae2649 100644
--- a/packages/docs-page/package.json
+++ b/packages/docs-page/package.json
@@ -1,7 +1,7 @@
{
"name": "@hashicorp/react-docs-page",
"description": "Create a Hashicorp branded docs page in NextJS projects.",
- "version": "11.0.0",
+ "version": "10.9.3",
"author": "HashiCorp",
"contributors": [
"Jeff Escalante"
diff --git a/packages/docs-sidenav/package-lock.json b/packages/docs-sidenav/package-lock.json
index 935a9a04b..c1ad4a81b 100644
--- a/packages/docs-sidenav/package-lock.json
+++ b/packages/docs-sidenav/package-lock.json
@@ -1,6 +1,6 @@
{
"name": "@hashicorp/react-docs-sidenav",
- "version": "7.0.0",
+ "version": "6.1.0",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
diff --git a/packages/docs-sidenav/package.json b/packages/docs-sidenav/package.json
index 80a528917..422063a30 100644
--- a/packages/docs-sidenav/package.json
+++ b/packages/docs-sidenav/package.json
@@ -1,7 +1,7 @@
{
"name": "@hashicorp/react-docs-sidenav",
"description": "Sidebar used for navigation HashiCorp docs",
- "version": "7.0.0",
+ "version": "6.1.0",
"author": "HashiCorp",
"bin": {
"migrate-to-mktg-032": "bin/migrate-to-mktg-032.js"
From 38eb643ffca5f026d9f2a086ec10e58fe22995e7 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:14:28 -0500
Subject: [PATCH 48/62] Remove unused imports
---
packages/docs-sidenav/index.test.js | 2 --
1 file changed, 2 deletions(-)
diff --git a/packages/docs-sidenav/index.test.js b/packages/docs-sidenav/index.test.js
index 158d2853a..f00e2f539 100644
--- a/packages/docs-sidenav/index.test.js
+++ b/packages/docs-sidenav/index.test.js
@@ -1,6 +1,4 @@
-// import 'regenerator-runtime/runtime'
import { render, fireEvent, screen } from '@testing-library/react'
-// import expectThrow from '../../__test-helpers/expect-throw'
import DocsSidenav from './'
import props from './props'
import { getTestValues } from 'swingset/testing'
From 1944c79ccd095a241d25bb6cca7bd730a0c47fbd Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:36:56 -0500
Subject: [PATCH 49/62] Add delete fm script to docs-sidenav
---
.../bin/delete-sidebar-title-frontmatter.js | 46 +++++++++++++++++++
packages/docs-sidenav/package.json | 1 +
2 files changed, 47 insertions(+)
create mode 100644 packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
diff --git a/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js b/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
new file mode 100644
index 000000000..745ebb411
--- /dev/null
+++ b/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
@@ -0,0 +1,46 @@
+#! /usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const grayMatter = require('gray-matter')
+const klawSync = require('klaw-sync')
+
+const CONTENT_DIR = path.join(process.cwd(), process.argv[3])
+
+function fileFilter(f) {
+ return path.extname(f.path) === '.mdx'
+}
+
+function processFrontmatter(frontmatter) {
+ const processed = { ...frontmatter }
+ delete processed.sidebar_title
+ return processed
+}
+
+modifyFrontmatter(CONTENT_DIR, fileFilter, processFrontmatter).then(
+ (processedEntries) => {
+ console.log(processedEntries)
+ }
+)
+
+async function modifyFrontmatter(inputDir, fileFilter, processFrontmatter) {
+ // Traverse directories and parse frontmatter
+ const targetFilepaths = klawSync(inputDir, {
+ traverseAll: true,
+ filter: fileFilter,
+ }).map((f) => f.path)
+ const withProcessedFrontmatter = await Promise.all(
+ targetFilepaths.map(async (filePath) => {
+ const rawFile = fs.readFileSync(filePath, 'utf-8')
+ const { data: frontmatter, content } = grayMatter(rawFile)
+ const processedFrontmatter = processFrontmatter(frontmatter)
+ const processedFile = grayMatter.stringify(content, processedFrontmatter)
+ fs.writeFileSync(filePath, processedFile)
+ return {
+ filePath,
+ after: processedFrontmatter,
+ }
+ })
+ )
+ return withProcessedFrontmatter
+}
diff --git a/packages/docs-sidenav/package.json b/packages/docs-sidenav/package.json
index 422063a30..054e68120 100644
--- a/packages/docs-sidenav/package.json
+++ b/packages/docs-sidenav/package.json
@@ -4,6 +4,7 @@
"version": "6.1.0",
"author": "HashiCorp",
"bin": {
+ "delete-sidebar-title-frontmatter": "bin/delete-sidebar-title-frontmatter.js",
"migrate-to-mktg-032": "bin/migrate-to-mktg-032.js"
},
"contributors": [
From 6c09a1c23b1297b7e793fe18e71a1b16abad4095 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:38:59 -0500
Subject: [PATCH 50/62] Fix issue with extra arg
---
.../bin/delete-sidebar-title-frontmatter.js | 14 +++++++++++++-
1 file changed, 13 insertions(+), 1 deletion(-)
diff --git a/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js b/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
index 745ebb411..6f511947d 100644
--- a/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
+++ b/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
@@ -5,7 +5,19 @@ const path = require('path')
const grayMatter = require('gray-matter')
const klawSync = require('klaw-sync')
-const CONTENT_DIR = path.join(process.cwd(), process.argv[3])
+/*
+
+DELETE sidebar_title FROM ALL .mdx FRONTMATTER
+
+USAGE
+
+```
+npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.52 delete-sidebar-title-frontmatter ./content
+```
+
+*/
+
+const CONTENT_DIR = path.join(process.cwd(), process.argv[2])
function fileFilter(f) {
return path.extname(f.path) === '.mdx'
From 4688cc96467dce0363da303a6226325acb66ce8f Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:39:28 -0500
Subject: [PATCH 51/62] Update comment
---
packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js b/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
index 6f511947d..8258a8113 100644
--- a/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
+++ b/packages/docs-sidenav/bin/delete-sidebar-title-frontmatter.js
@@ -12,7 +12,7 @@ DELETE sidebar_title FROM ALL .mdx FRONTMATTER
USAGE
```
-npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.52 delete-sidebar-title-frontmatter ./content
+npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.53 delete-sidebar-title-frontmatter ./content
```
*/
From 9c9cbc6aba4d93aa2348dec392195b41698bba71 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:41:01 -0500
Subject: [PATCH 52/62] Remote outdated comment
---
packages/docs-sidenav/bin/migrate-to-mktg-032.js | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/packages/docs-sidenav/bin/migrate-to-mktg-032.js b/packages/docs-sidenav/bin/migrate-to-mktg-032.js
index 71ea7a422..de8375083 100644
--- a/packages/docs-sidenav/bin/migrate-to-mktg-032.js
+++ b/packages/docs-sidenav/bin/migrate-to-mktg-032.js
@@ -23,7 +23,7 @@ to avoid installing migration-related packages into `@hashicorp/react-docs-siden
Here's a full example command:
```
-npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.10 migrate-to-mktg-032 ./data/docs-navigation.js ./content/docs ./data/docs-nav-data.json
+npx --package gray-matter --package klaw-sync --package @hashicorp/react-docs-sidenav@6.1.1-alpha.52 migrate-to-mktg-032 ./data/docs-navigation.js ./content/docs ./data/docs-nav-data.json
```
This a bit wordy - we can break this command down argument by argument:
@@ -179,7 +179,6 @@ function convertNavLeaf(navNode, collectedFrontmatter, pathStack, subfolder) {
if (!title) {
throw new Error(`Could not find title in frontmatter of ${pathToMatch}.`)
}
- // TODO should remove all `sidebar_title` values from each `.mdx` file as part of this process
// Return the new format for the nav leaf
return { title: formatTitle(title), path: pathNewFormat }
}
From 132e9c92357f998fea415042a434c832daaf6c03 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 5 Mar 2021 23:43:57 -0500
Subject: [PATCH 53/62] Fix updated test value
---
packages/docs-page/index.test.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/docs-page/index.test.js b/packages/docs-page/index.test.js
index de82c35d8..670002ddf 100644
--- a/packages/docs-page/index.test.js
+++ b/packages/docs-page/index.test.js
@@ -63,7 +63,7 @@ describe('
---
packages/glossary-page/server.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/glossary-page/server.js b/packages/glossary-page/server.js
index 31b536702..698ccc5c1 100644
--- a/packages/glossary-page/server.js
+++ b/packages/glossary-page/server.js
@@ -30,7 +30,7 @@ export default async function generateStaticProps({
})
// Construct the githubFileUrl, used for "Edit this page" link
- const githubFileUrl = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/content/glossary.mdx`
+ const githubFileUrl = `https://github.com/hashicorp/${product.slug}/blob/${mainBranch}/website/content/glossary`
return {
props: {
From 8d8092c17109dbcb042085c8b6eac998700b7cd4 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Mon, 8 Mar 2021 14:39:10 -0500
Subject: [PATCH 57/62] Fix issue with navData direct link edge case, add
related test
---
.../utils/validate-route-structure/index.js | 10 ++++++-
.../validate-route-structure/index.test.js | 27 +++++++++++++++++++
2 files changed, 36 insertions(+), 1 deletion(-)
diff --git a/packages/docs-sidenav/utils/validate-route-structure/index.js b/packages/docs-sidenav/utils/validate-route-structure/index.js
index 785cf2108..c19298069 100644
--- a/packages/docs-sidenav/utils/validate-route-structure/index.js
+++ b/packages/docs-sidenav/utils/validate-route-structure/index.js
@@ -53,6 +53,8 @@ function validateBranchRoutes(navNodes, depth = 0) {
`Missing nav-data title on NavDirectLink. Please add a title to the node with href "${navNode.href}".`
)
}
+ // Otherwise, we have a valid direct link node, we return it
+ return navNode
}
// Ensure the only other node type is
// a divider node, if not, throw an error
@@ -127,6 +129,8 @@ function validateBranchRoutes(navNodes, depth = 0) {
)}.`
)
}
+ // Note: some branches may not have any children with paths,
+ // for example branches with only direct links. So, path may be undefined.
const path = uniqueParents[0]
// Finally, we return
return [path, navNodesWithStacks]
@@ -139,7 +143,11 @@ function handleBranchNode(navNode, depth) {
navNode.routes,
depth + 1
)
- const __stack = path.split('/')
+ // Path will be undefined if the child routes are
+ // only non-path nodes (such as direct links).
+ // In this case, we set __stack to false so this route
+ // is left out of tree structure validation
+ const __stack = !path ? false : path.split('/')
return { ...navNode, __stack, routes: routesWithStacks }
}
diff --git a/packages/docs-sidenav/utils/validate-route-structure/index.test.js b/packages/docs-sidenav/utils/validate-route-structure/index.test.js
index e99ed5263..292c7c89d 100644
--- a/packages/docs-sidenav/utils/validate-route-structure/index.test.js
+++ b/packages/docs-sidenav/utils/validate-route-structure/index.test.js
@@ -166,4 +166,31 @@ describe('
Edit this page
@@ -85,10 +83,9 @@ export function DocsPageWrapper({
export default function DocsPage({
product,
baseRoute,
- mainBranch,
showEditPage = true,
additionalComponents,
- staticProps: { mdxSource, frontMatter, currentPath, navData },
+ 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, {
@@ -99,7 +96,7 @@ export default function DocsPage({
').replace(/<\/tt>/g, '')
-}
diff --git a/packages/docs-sidenav/package.json b/packages/docs-sidenav/package.json
index 054e68120..06eaba39e 100644
--- a/packages/docs-sidenav/package.json
+++ b/packages/docs-sidenav/package.json
@@ -3,10 +3,6 @@
"description": "Sidebar used for navigation HashiCorp docs",
"version": "6.1.0",
"author": "HashiCorp",
- "bin": {
- "delete-sidebar-title-frontmatter": "bin/delete-sidebar-title-frontmatter.js",
- "migrate-to-mktg-032": "bin/migrate-to-mktg-032.js"
- },
"contributors": [
"Jeff Escalante"
],
From 89f85aea1f832525cb0caeb6cc4df1172a5ecfe8 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Mon, 8 Mar 2021 18:34:02 -0500
Subject: [PATCH 62/62] Update tests to avoid unstable parentNode selection
---
packages/docs-page/index.test.js | 10 ++++---
packages/docs-sidenav/index.test.js | 45 ++++++++++++++---------------
2 files changed, 28 insertions(+), 27 deletions(-)
diff --git a/packages/docs-page/index.test.js b/packages/docs-page/index.test.js
index 670002ddf..b59aaaac0 100644
--- a/packages/docs-page/index.test.js
+++ b/packages/docs-page/index.test.js
@@ -44,8 +44,10 @@ describe('