Skip to content
GitLab
Unverified Commit 99b9a8d2 authored by Ryan Oaks's avatar Ryan Oaks Committed by GitHub
Browse files

Merge pull request #9036 from hashicorp/ro.docs-vercel-migration 

Update docs site to deploy to Vercel instead of Netlify
parents c04e7f6f c1b3e141
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 2254 additions and 2952 deletions
+2254 -2952
website/README.md
+ 15
- 17
View file @ 99b9a8d2
# Nomad Documentation Website
[![Netlify Status](https://img.shields.io/netlify/57d01198-7abc-4c39-a89b-386a2fe7de09?style=flat-square)](https://app.netlify.com/sites/nomad-website/deploys)
This subdirectory contains the entire source for the [Nomad Website](https://nomadproject.io/). This is a [NextJS](https://nextjs.org/) project, which builds a static site from these source files.
<!--
......@@ -378,29 +376,29 @@ You may customize the parameters in any way you'd like. To remove a prerelease f
## Redirects
This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects.
This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects. It's important to note that redirects should only be used to cover for external links -- if you are moving a path which internal links point to, the internal links should also be adjusted to point to the correct page, rather than relying on a redirect.
To add a redirect, head over to the `_redirects` file - the format is fairly simple. On the left is the current path, and on the right is the path that should be redirected to. It's important to note that if there are links to a `.html` version of a page, that must also be explicitly redirected. For example:
To add a redirect, head over to the `redirects.js` file - the format is fairly simple - there's a `source` and a `destination` - fill them both in, indicate that it's a permanent redirect or not using the `permanent` key, and that's it. Let's look at an example:
```
/foo /bar 301!
/foo.html /bar 301!
{
source: '/foo',
destination: '/bar',
permanent: true
}
```
This redirect rule will send all incoming links to `/foo` and `/foo.html` to `/bar`. For more details on the redirects file format, [check out the docs on netlify](https://docs.netlify.com/routing/redirects/rewrites-proxies). Note that it is critical that `301!` is added to every one-to-one redirect - if it is left off the redirect may not work.
This redirect rule will send all incoming links to `/foo` to `/bar`. For more details on the redirects file format, [check out the docs on vercel](https://vercel.com/docs/configuration#project/redirects). All redirects will work both locally and in production exactly the same way, so feel free to test and verify your redirects locally. In the past testing redirects has required a preview deployment -- this is no longer the case. Please note however that if you add a redirect while the local server is running, you will need to restart it in order to see the effects of the redirect.
There are a couple important caveats with redirects. First, redirects are applied at the hosting layer, and therefore will not work by default in local dev mode. To test in local dev mode, you can use [`netlify dev`](https://www.netlify.com/products/dev/), or just push a commit and check using the deploy preview.
There is still one caveat though: redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly.
Second, redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly.
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to redirects as such:
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such:
```
/foo /nested/foo 301!
/foo.html /nested/foo 301!
```js
{ source: '/foo(.html)?', destination: '/nested/foo', permanent: true }
```
Finally, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
Next, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-navigation` file. If previously the structure looked like:
......@@ -426,7 +424,7 @@ If we no longer want the link to be in the side nav, we can simply remove it. If
As the majority of items in the side nav are internal links, the structure makes it as easy as possible to represent these links. This alternate syntax is the most concise manner than an external link can be represented. External links can be used anywhere within the docs sidenav.
It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the `_redirects` file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first.
It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the redirects file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first.
<!-- END: redirects -->
......@@ -448,6 +446,6 @@ We support the following browsers targeting roughly the versions specified.
## Deployment
This website is hosted on Netlify and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews.
This website is hosted on Vercel and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews.
<!-- END: deployment -->
website/_redirects
+ 0
- 1
View file @ 99b9a8d2
......@@ -168,7 +168,6 @@
/api/index /api-docs 301!
/api-docs/index.html /api-docs 301!
/api-docs/index /api-docs 301!
/resources /resources 301!
/docs/agent/config.html /docs/configuration 301!
/docs/agent/config /docs/configuration 301!
/docs/jobops https://learn.hashicorp.com/collections/nomad/manage-jobs 301!
......
website/layouts/api.jsx
+ 36
- 36
View file @ 99b9a8d2
......@@ -9,40 +9,40 @@ import order from '../data/api-navigation.js'
const MDXProvider = createMdxProvider({ product: 'nomad' })
export default function ApiLayoutWrapper(pageMeta) {
function ApiLayout(props) {
const { children, ...propsWithoutChildren } = props
return (
<MDXProvider>
<DocsPage
{...propsWithoutChildren}
product="nomad"
head={{
is: Head,
title: `${pageMeta.page_title} | Nomad by HashiCorp`,
description: pageMeta.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'api-docs',
currentPage: props.path,
data,
order,
disableFilter: true,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${pageMeta.__resourcePath}`}
>
<SearchProvider>
<SearchBar />
{children}
</SearchProvider>
</DocsPage>
</MDXProvider>
)
}
ApiLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
return ApiLayout
export default function ApiLayout({
children,
frontMatter,
path,
...propsWithoutChildren
}) {
return (
<MDXProvider>
<DocsPage
{...propsWithoutChildren}
product="nomad"
head={{
is: Head,
title: `${frontMatter.page_title} | Nomad by HashiCorp`,
description: frontMatter.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'api-docs',
currentPage: path,
data,
order,
disableFilter: true,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${frontMatter.__resourcePath}`}
>
<SearchProvider>
<SearchBar />
{children}
</SearchProvider>
</DocsPage>
</MDXProvider>
)
}
ApiLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
website/layouts/docs.jsx
+ 37
- 37
View file @ 99b9a8d2
......@@ -3,7 +3,7 @@ import Link from 'next/link'
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
import DocsPage from '@hashicorp/react-docs-page'
import { SearchProvider } from '@hashicorp/react-search'
import { frontMatter } from '../pages/docs/**/*.mdx'
import { frontMatter as data } from '../pages/docs/**/*.mdx'
import Placement from '../components/placement-table'
import SearchBar from '../components/search-bar'
import order from '../data/docs-navigation.js'
......@@ -13,40 +13,40 @@ const MDXProvider = createMdxProvider({
additionalComponents: { Placement },
})
export default function DocsLayoutWrapper(pageMeta) {
function DocsLayout(props) {
const { children, ...propsWithoutChildren } = props
return (
<MDXProvider>
<DocsPage
{...propsWithoutChildren}
product="nomad"
head={{
is: Head,
title: `${pageMeta.page_title} | Nomad by HashiCorp`,
description: pageMeta.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'docs',
currentPage: props.path,
data: frontMatter,
order,
disableFilter: true,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${pageMeta.__resourcePath}`}
>
<SearchProvider>
<SearchBar />
{children}
</SearchProvider>
</DocsPage>
</MDXProvider>
)
}
DocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
return DocsLayout
export default function DocsLayout({
children,
frontMatter,
path,
...propsWithoutChildren
}) {
return (
<MDXProvider>
<DocsPage
{...propsWithoutChildren}
product="nomad"
head={{
is: Head,
title: `${frontMatter.page_title} | Nomad by HashiCorp`,
description: frontMatter.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'docs',
currentPage: path,
data,
order,
disableFilter: true,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${frontMatter.__resourcePath}`}
>
<SearchProvider>
<SearchBar />
{children}
</SearchProvider>
</DocsPage>
</MDXProvider>
)
}
DocsLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
website/layouts/guides.jsx deleted 100644 → 0
+ 0
- 39
View file @ c04e7f6f
import DocsPage from '@hashicorp/react-docs-page'
import order from 'data/guides-navigation.js'
import { frontMatter as data } from '../pages/guides/**/*.mdx'
import Head from 'next/head'
import Link from 'next/link'
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
const MDXProvider = createMdxProvider({ product: 'nomad' })
export default function GuidesLayoutWrapper(pageMeta) {
function GuidesLayout(props) {
return (
<MDXProvider>
<DocsPage
{...props}
product="nomad"
head={{
is: Head,
title: `${pageMeta.page_title} | Nomad by HashiCorp`,
description: pageMeta.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'guides',
currentPage: props.path,
data,
order,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${pageMeta.__resourcePath}`}
/>
</MDXProvider>
)
}
GuidesLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
return GuidesLayout
}
website/layouts/intro.jsx
+ 36
- 36
View file @ 99b9a8d2
......@@ -9,40 +9,40 @@ import order from 'data/intro-navigation.js'
const MDXProvider = createMdxProvider({ product: 'nomad' })
export default function IntroLayoutWrapper(pageMeta) {
function IntroLayout(props) {
const { children, ...propsWithoutChildren } = props
return (
<MDXProvider>
<DocsPage
{...propsWithoutChildren}
product="nomad"
head={{
is: Head,
title: `${pageMeta.page_title} | Nomad by HashiCorp`,
description: pageMeta.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'intro',
currentPage: props.path,
data,
order,
disableFilter: true,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${pageMeta.__resourcePath}`}
>
<SearchProvider>
<SearchBar />
{children}
</SearchProvider>
</DocsPage>
</MDXProvider>
)
}
IntroLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
return IntroLayout
export default function IntroLayout({
children,
frontMatter,
path,
...propsWithoutChildren
}) {
return (
<MDXProvider>
<DocsPage
{...propsWithoutChildren}
product="nomad"
head={{
is: Head,
title: `${frontMatter.page_title} | Nomad by HashiCorp`,
description: frontMatter.description,
siteName: 'Nomad by HashiCorp',
}}
sidenav={{
Link,
category: 'intro',
currentPage: path,
data,
order,
disableFilter: true,
}}
resourceURL={`https://github.com/hashicorp/nomad/blob/master/website/pages/${frontMatter.__resourcePath}`}
>
<SearchProvider>
<SearchBar />
{children}
</SearchProvider>
</DocsPage>
</MDXProvider>
)
}
IntroLayout.getInitialProps = ({ asPath }) => ({ path: asPath })
website/next.config.js
+ 9
- 10
View file @ 99b9a8d2
const withHashicorp = require('@hashicorp/nextjs-scripts')
const path = require('path')
const dotenv = require('dotenv')
const redirects = require('./redirects')
const rewrites = require('./rewrites')
dotenv.config()
module.exports = withHashicorp({
defaultLayout: true,
transpileModules: ['is-absolute-url', '@hashicorp/react-mega-nav'],
transpileModules: ['is-absolute-url', '@hashicorp/react-.*'],
mdx: { resolveIncludes: path.join(__dirname, 'pages/partials') },
})({
redirects() {
return redirects
},
rewrites() {
return rewrites
},
svgo: {
plugins: [
{
......@@ -16,15 +24,6 @@ module.exports = withHashicorp({
},
],
},
experimental: {
modern: true,
rewrites: () => [
{
source: '/api/:path*',
destination: '/api-docs/:path*',
},
],
},
env: {
HASHI_ENV: process.env.HASHI_ENV || 'development',
SEGMENT_WRITE_KEY: 'qW11yxgipKMsKFKQUCpTVgQUYftYsJj0',
......
website/package-lock.json
+ 902
- 2770
View file @ 99b9a8d2
This diff is collapsed.
website/package.json
+ 5
- 5
View file @ 99b9a8d2
......@@ -4,9 +4,9 @@
"version": "0.0.1",
"author": "HashiCorp",
"dependencies": {
"@hashicorp/nextjs-scripts": "11.1.1",
"@hashicorp/nextjs-scripts": "13.0.0",
"@hashicorp/react-alert-banner": "3.1.0",
"@hashicorp/react-button": "2.2.1",
"@hashicorp/react-button": "3.0.2",
"@hashicorp/react-call-to-action": "0.2.1",
"@hashicorp/react-case-study-slider": "2.1.1",
"@hashicorp/react-content": "4.0.0",
......@@ -34,7 +34,7 @@
"imagemin-optipng": "8.0.0",
"imagemin-svgo": "8.0.0",
"marked": "0.7.0",
"next": "9.4.4",
"next": "9.5.3",
"nuka-carousel": "4.7.0",
"react": "16.13.1",
"react-device-detect": "1.13.1",
......@@ -59,7 +59,7 @@
"generate:readme": "next-hashicorp markdown-blocks README.md",
"lint": "next-hashicorp lint",
"start": "rm -rf .next/cache/next-babel-loader/ && next dev",
"static": "npm run build && npm run export && cp _redirects out/.",
"linkcheck": "linkcheck https://nomadproject.io"
"static": "npm run build && npm run export",
"linkcheck": "linkcheck https://www.nomadproject.io"
}
}
website/pages/style.css
+ 1
- 1
View file @ 99b9a8d2
......@@ -13,7 +13,7 @@
/* Global Transpiled Components */
@import '~@hashicorp/react-alert/dist/style.css';
@import '~@hashicorp/react-button/dist/style.css';
@import '~@hashicorp/react-button/styles/index.css';
@import '~@hashicorp/react-call-to-action/dist/style.css';
@import '~@hashicorp/react-code-block/dist/style.css';
@import '~@hashicorp/react-consent-manager/dist/style.css';
......
website/redirects.js 0 → 100644
+ 1206
- 0
View file @ 99b9a8d2
This diff is collapsed.
website/rewrites.js 0 → 100644
+ 1
- 0
View file @ 99b9a8d2
module.exports = [{ source: '/api/:splat*', destination: '/api-docs/:splat*' }]
website/vercel.json 0 → 100644
+ 6
- 0
View file @ 99b9a8d2
{
"version": 2,
"github": {
"silent": true
}
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

免费DevSecOps平台，让您的项目体验完整的DevSecOps流程，让项目更安全